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


-- | Clash: a functional hardware description language - Prelude library
--   
--   Clash is a functional hardware description language that borrows both
--   its syntax and semantics from the functional programming language
--   Haskell. The Clash compiler transforms these high-level descriptions
--   to low-level synthesizable VHDL, Verilog, or SystemVerilog.
--   
--   Features of Clash:
--   
--   <ul>
--   <li>Strongly typed, but with a very high degree of type inference,
--   enabling both safe and fast prototyping using concise
--   descriptions.</li>
--   <li>Interactive REPL: load your designs in an interpreter and easily
--   test all your component without needing to setup a test bench.</li>
--   <li>Higher-order functions, with type inference, result in designs
--   that are fully parametric by default.</li>
--   <li>Synchronous sequential circuit design based on streams of values,
--   called <tt>Signal</tt>s, lead to natural descriptions of feedback
--   loops.</li>
--   <li>Support for multiple clock domains, with type safe clock domain
--   crossing.</li>
--   </ul>
--   
--   This package provides:
--   
--   <ul>
--   <li>Prelude library containing datatypes and functions for circuit
--   design</li>
--   </ul>
--   
--   To use the library:
--   
--   <ul>
--   <li>Import <a>Clash.Prelude</a></li>
--   <li>Alternatively, if you want to explicitly route clock and reset
--   ports, for more straightforward multi-clock designs, you can import
--   the <a>Clash.Explicit.Prelude</a> module. Note that you should not
--   import <a>Clash.Prelude</a> and <a>Clash.Explicit.Prelude</a> at the
--   same time as they have overlapping definitions.</li>
--   </ul>
--   
--   A preliminary version of a tutorial can be found in
--   <a>Clash.Tutorial</a>, for a general overview of the library you
--   should however check out <a>Clash.Prelude</a>. Some circuit examples
--   can be found in <a>Clash.Examples</a>.
@package clash-prelude
@version 1.8.1


-- | Using <i>ANN</i> pragma's you can tell the Clash compiler to use a
--   custom bit representation for a data type. See <tt>DataReprAnn</tt>
--   for documentation.
module Clash.Annotations.BitRepresentation

-- | Annotation for custom bit representations of data types
--   
--   Using <i>ANN</i> pragma's you can tell the Clash compiler to use a
--   custom bit-representation for a data type.
--   
--   For example:
--   
--   <pre>
--   data Color = R | G | B
--   {-# ANN module (<a>DataReprAnn</a>
--                     $(<a>liftQ</a> [t|Color|])
--                     2
--                     [ <a>ConstrRepr</a> 'R 0b11 0b00 []
--                     , <a>ConstrRepr</a> 'G 0b11 0b01 []
--                     , <a>ConstrRepr</a> 'B 0b11 0b10 []
--                     ]) #-}
--   </pre>
--   
--   This specifies that <tt>R</tt> should be encoded as 0b00, <tt>G</tt>
--   as 0b01, and <tt>B</tt> as 0b10. The first binary value in every
--   <tt>ConstrRepr</tt> in this example is a mask, indicating which bits
--   in the data type are relevant. In this case all of the bits are.
--   
--   Or if we want to annotate <tt>Maybe Color</tt>:
--   
--   <pre>
--   {-# ANN module ( <a>DataReprAnn</a>
--                      $(<a>liftQ</a> [t|Maybe Color|])
--                      2
--                      [ <a>ConstrRepr</a> 'Nothing 0b11 0b11 []
--                      , <a>ConstrRepr</a> 'Just 0b00 0b00 [0b11]
--                      ] ) #-}
--   </pre>
--   
--   By default, <tt>Maybe Color</tt> is a data type which consumes 3 bits.
--   A single bit to indicate the constructor (either <tt>Just</tt> or
--   <tt>Nothing</tt>), and two bits to encode the first field of
--   <tt>Just</tt>. Notice that we saved a single bit by exploiting the
--   fact that <tt>Color</tt> only uses three values (0, 1, 2), but takes
--   two bits to encode it. We can therefore use the last - unused - value
--   (3), to encode one of the constructors of <tt>Maybe</tt>. We indicate
--   which bits encode the underlying <tt>Color</tt> field of <tt>Just</tt>
--   by passing <i>[0b11]</i> to ConstrRepr. This indicates that the first
--   field is encoded in the first and second bit of the whole datatype
--   (0b11).
--   
--   <b>NB</b>: BitPack for a custom encoding can be derived using
--   <a>deriveBitPack</a>.
data DataReprAnn
DataReprAnn :: Type -> Size -> [ConstrRepr] -> DataReprAnn

-- | Annotation for constructors. Indicates how to match this constructor
--   based off of the whole datatype.
data ConstrRepr
ConstrRepr :: Name -> BitMask -> Value -> [FieldAnn] -> ConstrRepr
type BitMask = Integer
type Value = Integer
type Size = Int

-- | BitMask used to mask fields
type FieldAnn = BitMask

-- | Lift values inside of <a>Q</a> to a Template Haskell expression
liftQ :: Lift a => Q a -> Q Exp
instance Language.Haskell.TH.Syntax.Lift Clash.Annotations.BitRepresentation.ConstrRepr
instance GHC.Generics.Generic Clash.Annotations.BitRepresentation.ConstrRepr
instance GHC.Classes.Eq Clash.Annotations.BitRepresentation.ConstrRepr
instance Data.Data.Data Clash.Annotations.BitRepresentation.ConstrRepr
instance GHC.Show.Show Clash.Annotations.BitRepresentation.ConstrRepr
instance Language.Haskell.TH.Syntax.Lift Clash.Annotations.BitRepresentation.DataReprAnn
instance GHC.Generics.Generic Clash.Annotations.BitRepresentation.DataReprAnn
instance GHC.Classes.Eq Clash.Annotations.BitRepresentation.DataReprAnn
instance Data.Data.Data Clash.Annotations.BitRepresentation.DataReprAnn
instance GHC.Show.Show Clash.Annotations.BitRepresentation.DataReprAnn


module Clash.Annotations.BitRepresentation.Internal

-- | Create indices based on names of constructors and data types
buildCustomReprs :: [DataRepr'] -> CustomReprs
dataReprAnnToDataRepr' :: DataReprAnn -> DataRepr'
constrReprToConstrRepr' :: Int -> ConstrRepr -> ConstrRepr'

-- | Lookup constructor representation based on name
getConstrRepr :: Text -> CustomReprs -> Maybe ConstrRepr'

-- | Unchecked version of getConstrRepr
uncheckedGetConstrRepr :: HasCallStack => Text -> CustomReprs -> ConstrRepr'

-- | Lookup data type representation based on name
getDataRepr :: Type' -> CustomReprs -> Maybe DataRepr'

-- | Convert template haskell type to simple representation of type
thTypeToType' :: Type -> Type'

-- | Internal version of ConstrRepr
data ConstrRepr'
ConstrRepr' :: Text -> Int -> BitMask -> Value -> [FieldAnn] -> ConstrRepr'

-- | Qualified name of constructor
[crName] :: ConstrRepr' -> Text

-- | Syntactical position in the custom representations definition
[crPosition] :: ConstrRepr' -> Int

-- | Mask needed to determine constructor
[crMask] :: ConstrRepr' -> BitMask

-- | Value after applying mask
[crValue] :: ConstrRepr' -> Value

-- | Indicates where fields are stored
[crFieldAnns] :: ConstrRepr' -> [FieldAnn]

-- | Internal version of DataRepr
data DataRepr'
DataRepr' :: Type' -> Size -> [ConstrRepr'] -> DataRepr'

-- | Simple representation of data type
[drType] :: DataRepr' -> Type'

-- | Size of data type
[drSize] :: DataRepr' -> Size

-- | Constructors
[drConstrs] :: DataRepr' -> [ConstrRepr']

-- | Simple version of template haskell type. Used internally to match on.
data Type'

-- | Type application
AppTy' :: Type' -> Type' -> Type'

-- | Qualified name of type
ConstTy' :: Text -> Type'

-- | Numeral literal (used in BitVector 10, for example)
LitTy' :: Integer -> Type'

-- | Symbol literal (used in for example (Signal <a>System</a> Int))
SymLitTy' :: Text -> Type'

-- | Convenience type for index built by buildCustomReprs
type CustomReprs = (Map Type' DataRepr', Map Text ConstrRepr')
instance GHC.Show.Show Clash.Annotations.BitRepresentation.Internal.Type'
instance GHC.Classes.Ord Clash.Annotations.BitRepresentation.Internal.Type'
instance Data.Hashable.Class.Hashable Clash.Annotations.BitRepresentation.Internal.Type'
instance GHC.Classes.Eq Clash.Annotations.BitRepresentation.Internal.Type'
instance Control.DeepSeq.NFData Clash.Annotations.BitRepresentation.Internal.Type'
instance GHC.Generics.Generic Clash.Annotations.BitRepresentation.Internal.Type'
instance Data.Hashable.Class.Hashable Clash.Annotations.BitRepresentation.Internal.ConstrRepr'
instance GHC.Classes.Ord Clash.Annotations.BitRepresentation.Internal.ConstrRepr'
instance GHC.Classes.Eq Clash.Annotations.BitRepresentation.Internal.ConstrRepr'
instance Control.DeepSeq.NFData Clash.Annotations.BitRepresentation.Internal.ConstrRepr'
instance GHC.Generics.Generic Clash.Annotations.BitRepresentation.Internal.ConstrRepr'
instance GHC.Show.Show Clash.Annotations.BitRepresentation.Internal.ConstrRepr'
instance GHC.Classes.Ord Clash.Annotations.BitRepresentation.Internal.DataRepr'
instance Data.Hashable.Class.Hashable Clash.Annotations.BitRepresentation.Internal.DataRepr'
instance GHC.Classes.Eq Clash.Annotations.BitRepresentation.Internal.DataRepr'
instance Control.DeepSeq.NFData Clash.Annotations.BitRepresentation.Internal.DataRepr'
instance GHC.Generics.Generic Clash.Annotations.BitRepresentation.Internal.DataRepr'
instance GHC.Show.Show Clash.Annotations.BitRepresentation.Internal.DataRepr'


module Clash.Annotations.BitRepresentation.Util

-- | Given a type size and one of its constructor this function will yield
--   a specification of which bits the whole type is made up of. I.e., a
--   construction plan on how to make the whole data structure, given its
--   individual constructor fields.
bitOrigins :: DataRepr' -> ConstrRepr' -> [BitOrigin]

-- | Same as bitOrigins, but each item in result list represents a single
--   bit.
bitOrigins' :: DataRepr' -> ConstrRepr' -> [BitOrigin]

-- | Determine consecutively set bits in word. Will produce ranges from
--   high to low. Examples:
--   
--   bitRanges 0b10 == [(1,1)] bitRanges 0b101 == [(2,2),(0,0)] bitRanges
--   0b10011001111 == [(10,10),(7,6),(3,0)]
bitRanges :: Integer -> [(Int, Int)]
isContinuousMask :: Integer -> Bool

-- | Result of various utilty functions. Indicates the origin of a certain
--   bit: either a literal from the constructor (or an undefined bit), or
--   from a literal.
data BitOrigin

-- | Literal (high, low, undefind)
Lit :: [Bit] -> BitOrigin

-- | Bits originate from a field. Field <i>fieldnr</i> <i>from</i>
--   <i>downto</i>.
Field :: Int -> Int -> Int -> BitOrigin
data Bit

-- | High
H :: Bit

-- | Low
L :: Bit

-- | Undefined
U :: Bit
instance GHC.Classes.Eq Clash.Annotations.BitRepresentation.Util.Bit
instance GHC.Show.Show Clash.Annotations.BitRepresentation.Util.Bit
instance GHC.Show.Show Clash.Annotations.BitRepresentation.Util.BitOrigin


-- | Instruct the Clash compiler to look for primitive HDL templates
--   provided inline or in a specified directory. For distribution of new
--   packages with primitive HDL templates. Primitive guards can be added
--   to warn on instantiating primitives.
module Clash.Annotations.Primitive

-- | Marks value as not translatable. Clash will error if it finds a
--   blackbox definition for it, or when it is forced to translate it. You
--   can annotate a variable or function <tt>f</tt> like:
--   
--   <pre>
--   {-# ANN f dontTranslate #-}
--   </pre>
dontTranslate :: PrimitiveGuard ()

-- | Marks a value as having a blackbox. Clash will error if it hasn't
--   found a blackbox. You can annotate a variable or function <tt>f</tt>
--   like:
--   
--   <pre>
--   {-# ANN f hasBlackBox #-}
--   </pre>
hasBlackBox :: PrimitiveGuard ()

-- | Marks value as non-synthesizable. This will trigger a warning if
--   instantiated in a non-testbench context. You can annotate a variable
--   or function <tt>f</tt> like:
--   
--   <pre>
--   {-# ANN f (warnNonSynthesizable "Tread carefully, user!") #-}
--   </pre>
--   
--   Implies <a>hasBlackBox</a>.
warnNonSynthesizable :: String -> PrimitiveGuard ()

-- | Always emit warning upon primitive instantiation. You can annotate a
--   variable or function <tt>f</tt> like:
--   
--   <pre>
--   {-# ANN f (warnAlways "Tread carefully, user!") #-}
--   </pre>
--   
--   Implies <a>hasBlackBox</a>.
warnAlways :: String -> PrimitiveGuard ()

-- | The <a>Primitive</a> constructor instructs the clash compiler to look
--   for primitive HDL templates in the indicated directory.
--   <a>InlinePrimitive</a> is equivalent but provides the HDL template
--   inline. They are intended for the distribution of new packages with
--   primitive HDL templates.
--   
--   <h3>Example of <a>Primitive</a></h3>
--   
--   You have some existing IP written in one of HDLs supported by Clash,
--   and you want to distribute some bindings so that the IP can be easily
--   instantiated from Clash.
--   
--   You create a package which has a <tt>myfancyip.cabal</tt> file with
--   the following stanza:
--   
--   <pre>
--   data-files: path/to/MyFancyIP.primitives
--   cpp-options: -DCABAL
--   </pre>
--   
--   and a <tt>MyFancyIP.hs</tt> module with the simulation definition and
--   primitive.
--   
--   <pre>
--   module MyFancyIP where
--   
--   import Clash.Prelude
--   
--   myFancyIP :: ...
--   myFancyIP = ...
--   {-# NOINLINE myFancyIP #-}
--   </pre>
--   
--   The <tt>NOINLINE</tt> pragma is needed so that GHC will never inline
--   the definition.
--   
--   Now you need to add the following imports and <tt>ANN</tt> pragma:
--   
--   <pre>
--   #ifdef CABAL
--   import           Clash.Annotations.Primitive
--   import           System.FilePath
--   import qualified Paths_myfancyip
--   import           System.IO.Unsafe
--   
--   {-# ANN module (Primitive [VHDL] (unsafePerformIO Paths_myfancyip.getDataDir &lt;/&gt; "path" &lt;/&gt; "to")) #-}
--   #endif
--   </pre>
--   
--   Add more files to the <tt>data-files</tt> stanza in your
--   <tt>.cabal</tt> files and more <tt>ANN</tt> pragma's if you want to
--   add more primitive templates for other HDLs
--   
--   <h3>Example of <a>InlineYamlPrimitive</a></h3>
--   
--   The following example shows off an inline HDL primitive template. It
--   uses the <a>string-interpolate</a> package for nicer multiline
--   strings.
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   module InlinePrimitive where
--   
--   import           Clash.Annotations.Primitive
--   import           Clash.Prelude
--   import           Data.String.Interpolate      (__i)
--   
--   {-# ANN example (InlineYamlPrimitive [VHDL] [__i|
--     BlackBox:
--       kind: Declaration
--       name: InlinePrimitive.example
--       template: |-
--         -- begin InlinePrimitive example:
--         ~GENSYM[example][0] : block
--         ~RESULT &lt;= 1 + ~ARG[0];
--         end block;
--         -- end InlinePrimitive example
--     |]) #-}
--   {-# NOINLINE example #-}
--   example :: Signal System (BitVector 2) -&gt; Signal System (BitVector 2)
--   example = fmap succ
--   </pre>
data Primitive

-- | Description of a primitive for a given <a>HDL</a>s in a file at
--   <a>FilePath</a>
Primitive :: [HDL] -> FilePath -> Primitive

-- | Description of a primitive for a given <a>HDL</a>s as an inline JSON
--   <a>String</a>
InlinePrimitive :: [HDL] -> String -> Primitive

-- | Description of a primitive for a given <a>HDL</a>s as an inline YAML
--   <a>String</a>
InlineYamlPrimitive :: [HDL] -> String -> Primitive

-- | A compilation target HDL.
data HDL
SystemVerilog :: HDL
Verilog :: HDL
VHDL :: HDL

-- | Primitive guard to mark a value as either not translatable or as
--   having a blackbox with an optional extra warning. Helps Clash generate
--   better error messages.
--   
--   For use, see <a>dontTranslate</a>, <a>hasBlackBox</a>,
--   <a>warnNonSynthesizable</a> and <a>warnAlways</a>.
data PrimitiveGuard a

-- | Marks value as not translatable. Clash will error if it finds a
--   blackbox definition for it, or when it is forced to translate it.
DontTranslate :: PrimitiveGuard a

-- | Marks a value as having a blackbox. Clash will error if it hasn't
--   found a blackbox.
HasBlackBox :: [PrimitiveWarning] -> a -> PrimitiveGuard a

-- | Warning that will be emitted on instantiating a guarded value.
data PrimitiveWarning

-- | Marks value as non-synthesizable. This will trigger a warning if
--   instantiated in a non-testbench context.
WarnNonSynthesizable :: String -> PrimitiveWarning

-- | Always emit warning upon primitive instantiation.
WarnAlways :: String -> PrimitiveWarning

-- | Extract primitive definition from a PrimitiveGuard. Will yield Nothing
--   for guards of value <a>DontTranslate</a>.
extractPrim :: PrimitiveGuard a -> Maybe a

-- | Extract primitive warnings from a PrimitiveGuard. Will yield an empty
--   list for guards of value <a>DontTranslate</a>.
extractWarnings :: PrimitiveGuard a -> [PrimitiveWarning]
instance GHC.Enum.Bounded Clash.Annotations.Primitive.HDL
instance GHC.Enum.Enum Clash.Annotations.Primitive.HDL
instance Data.Hashable.Class.Hashable Clash.Annotations.Primitive.HDL
instance Control.DeepSeq.NFData Clash.Annotations.Primitive.HDL
instance GHC.Generics.Generic Clash.Annotations.Primitive.HDL
instance Data.Data.Data Clash.Annotations.Primitive.HDL
instance GHC.Read.Read Clash.Annotations.Primitive.HDL
instance GHC.Show.Show Clash.Annotations.Primitive.HDL
instance GHC.Classes.Eq Clash.Annotations.Primitive.HDL
instance GHC.Classes.Eq Clash.Annotations.Primitive.Primitive
instance Data.Hashable.Class.Hashable Clash.Annotations.Primitive.Primitive
instance Control.DeepSeq.NFData Clash.Annotations.Primitive.Primitive
instance GHC.Generics.Generic Clash.Annotations.Primitive.Primitive
instance Data.Data.Data Clash.Annotations.Primitive.Primitive
instance GHC.Read.Read Clash.Annotations.Primitive.Primitive
instance GHC.Show.Show Clash.Annotations.Primitive.Primitive
instance GHC.Classes.Eq Clash.Annotations.Primitive.PrimitiveWarning
instance Data.Binary.Class.Binary Clash.Annotations.Primitive.PrimitiveWarning
instance Data.Hashable.Class.Hashable Clash.Annotations.Primitive.PrimitiveWarning
instance Control.DeepSeq.NFData Clash.Annotations.Primitive.PrimitiveWarning
instance GHC.Generics.Generic Clash.Annotations.Primitive.PrimitiveWarning
instance Data.Data.Data Clash.Annotations.Primitive.PrimitiveWarning
instance GHC.Read.Read Clash.Annotations.Primitive.PrimitiveWarning
instance GHC.Show.Show Clash.Annotations.Primitive.PrimitiveWarning
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Annotations.Primitive.PrimitiveGuard a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Clash.Annotations.Primitive.PrimitiveGuard a)
instance Data.Traversable.Traversable Clash.Annotations.Primitive.PrimitiveGuard
instance Data.Foldable.Foldable Clash.Annotations.Primitive.PrimitiveGuard
instance GHC.Base.Functor Clash.Annotations.Primitive.PrimitiveGuard
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Clash.Annotations.Primitive.PrimitiveGuard a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Annotations.Primitive.PrimitiveGuard a)
instance GHC.Generics.Generic (Clash.Annotations.Primitive.PrimitiveGuard a)
instance Data.Data.Data a => Data.Data.Data (Clash.Annotations.Primitive.PrimitiveGuard a)
instance GHC.Read.Read a => GHC.Read.Read (Clash.Annotations.Primitive.PrimitiveGuard a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Annotations.Primitive.PrimitiveGuard a)

module Clash.Class.Counter.TH
counterName :: Name
countMinName :: Name
countMaxName :: Name
countSuccName :: Name
countPredName :: Name
mkTupTy :: [Type] -> Type
mkTup :: [Exp] -> Exp
genTupleInstances :: Int -> Q [Dec]
genTupleInstance :: Int -> Q Dec
genCount :: Name -> Int -> Clause
genCountOverflow :: Name -> Int -> Q Clause


module Clash.Class.HasDomain.Common

-- | Combine multiple lines with line break. Type-level version of the
--   <tt>unlines</tt> function but for ErrorMessage.
type family Unlines (ln :: [k]) :: ErrorMessage
type (:<<>>:) (k1 :: t1) (k2 :: t2) = ToEM k1 :<>: ToEM k2
infixl 5 :<<>>:
type (:$$$:) (k1 :: t1) (k2 :: t2) = ToEM k1 :$$: ToEM k2
infixl 4 :$$$:
type family (:++:) (as :: [k]) (bs :: [k]) :: [k]
infixl 4 :++:
type family ToEM (k :: t) :: ErrorMessage


module Clash.Class.Num

-- | Adding, subtracting, and multiplying values of two different
--   (sub-)types.
class ExtendingNum a b where {
    
    -- | Type of the result of the addition or subtraction
    type family AResult a b;
    
    -- | Type of the result of the multiplication
    type family MResult a b;
}

-- | Add values of different (sub-)types, return a value of a (sub-)type
--   that is potentially different from either argument.
add :: ExtendingNum a b => a -> b -> AResult a b

-- | Subtract values of different (sub-)types, return a value of a
--   (sub-)type that is potentially different from either argument.
sub :: ExtendingNum a b => a -> b -> AResult a b

-- | Multiply values of different (sub-)types, return a value of a
--   (sub-)type that is potentially different from either argument.
mul :: ExtendingNum a b => a -> b -> MResult a b
infixl 7 `mul`
infixl 6 `add`
infixl 6 `sub`

-- | Determine how overflow and underflow are handled by the functions in
--   <a>SaturatingNum</a>
data SaturationMode

-- | Wrap around on overflow and underflow
SatWrap :: SaturationMode

-- | Become <a>maxBound</a> on overflow, and <a>minBound</a> on underflow
SatBound :: SaturationMode

-- | Become <tt>0</tt> on overflow and underflow
SatZero :: SaturationMode

-- | Become <a>maxBound</a> on overflow, and (<tt><a>minBound</a> + 1</tt>)
--   on underflow for signed numbers, and <a>minBound</a> for unsigned
--   numbers.
SatSymmetric :: SaturationMode

-- | Become an XException on overflow and underflow
SatError :: SaturationMode

-- | <a>Num</a> operators in which overflow and underflow behavior can be
--   specified using <a>SaturationMode</a>.
class (Bounded a, Num a) => SaturatingNum a

-- | Addition with parameterizable over- and underflow behavior
satAdd :: SaturatingNum a => SaturationMode -> a -> a -> a

-- | Subtraction with parameterizable over- and underflow behavior
satSub :: SaturatingNum a => SaturationMode -> a -> a -> a

-- | Multiplication with parameterizable over- and underflow behavior
satMul :: SaturatingNum a => SaturationMode -> a -> a -> a

-- | Get successor of (or in other words, add 1 to) given number
satSucc :: SaturatingNum a => SaturationMode -> a -> a

-- | Get predecessor of (or in other words, subtract 1 from) given number
satPred :: SaturatingNum a => SaturationMode -> a -> a
infixl 6 `satAdd`
infixl 6 `satSub`
infixl 7 `satMul`

-- | Addition that clips to <a>maxBound</a> on overflow, and
--   <a>minBound</a> on underflow
boundedAdd :: SaturatingNum a => a -> a -> a
infixl 6 `boundedAdd`

-- | Subtraction that clips to <a>maxBound</a> on overflow, and
--   <a>minBound</a> on underflow
boundedSub :: SaturatingNum a => a -> a -> a
infixl 6 `boundedSub`

-- | Multiplication that clips to <a>maxBound</a> on overflow, and
--   <a>minBound</a> on underflow
boundedMul :: SaturatingNum a => a -> a -> a
infixl 7 `boundedMul`
instance GHC.Enum.Bounded Clash.Class.Num.SaturationMode
instance GHC.Enum.Enum Clash.Class.Num.SaturationMode
instance GHC.Classes.Eq Clash.Class.Num.SaturationMode
instance GHC.Show.Show Clash.Class.Num.SaturationMode


-- | <a>Clash.HaskellPrelude</a> re-exports most of the Haskell
--   <a>Prelude</a> with the exception of those functions that the Clash
--   API defines to work on <a>Vec</a> from <a>Clash.Sized.Vector</a>
--   instead of on lists as the Haskell Prelude does. In addition, for the
--   <a>odd</a> and <a>even</a> functions a type class called <a>Parity</a>
--   is available at <a>Clash.Class.Parity</a>.
module Clash.HaskellPrelude

-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
--   otherwise equal to <tt>b</tt>. In other words, it evaluates the first
--   argument <tt>a</tt> to weak head normal form (WHNF). <tt>seq</tt> is
--   usually introduced to improve performance by avoiding unneeded
--   laziness.
--   
--   A note on evaluation order: the expression <tt>seq a b</tt> does
--   <i>not</i> guarantee that <tt>a</tt> will be evaluated before
--   <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
--   <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
--   returns a value. In particular, this means that <tt>b</tt> may be
--   evaluated before <tt>a</tt>. If you need to guarantee a specific order
--   of evaluation, you must use the function <tt>pseq</tt> from the
--   "parallel" package.
seq :: forall (r :: RuntimeRep) a (b :: TYPE r). a -> b -> b
infixr 0 `seq`

-- | &lt;math&gt;. <a>filter</a>, applied to a predicate and a list,
--   returns the list of those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; filter odd [1, 2, 3]
--   [1,3]
--   </pre>
filter :: (a -> Bool) -> [a] -> [a]

-- | The <a>print</a> function outputs a value of any printable type to the
--   standard output device. Printable types are those that are instances
--   of class <a>Show</a>; <a>print</a> converts values to strings for
--   output using the <a>show</a> operation and adds a newline.
--   
--   For example, a program to print the first 20 integers and their powers
--   of 2 could be written as:
--   
--   <pre>
--   main = print ([(n, 2^n) | n &lt;- [0..19]])
--   </pre>
print :: Show a => a -> IO ()

-- | Extract the first component of a pair.
fst :: (a, b) -> a

-- | Extract the second component of a pair.
snd :: (a, b) -> b

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool

-- | Application operator. This operator is redundant, since ordinary
--   application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
--   However, <a>$</a> has low, right-associative binding precedence, so it
--   sometimes allows parentheses to be omitted; for example:
--   
--   <pre>
--   f $ g $ h x  =  f (g (h x))
--   </pre>
--   
--   It is also useful in higher-order situations, such as <tt><a>map</a>
--   (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
--   
--   Note that <tt>(<a>$</a>)</tt> is levity-polymorphic in its result
--   type, so that <tt>foo <a>$</a> True</tt> where <tt>foo :: Bool -&gt;
--   Int#</tt> is well-typed.
($) :: forall (r :: RuntimeRep) a (b :: TYPE r). (a -> b) -> a -> b
infixr 0 $

-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b

-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b

-- | The <a>Bounded</a> class is used to name the upper and lower limits of
--   a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
--   that are not totally ordered may also have upper and lower bounds.
--   
--   The <a>Bounded</a> class may be derived for any enumeration type;
--   <a>minBound</a> is the first constructor listed in the <tt>data</tt>
--   declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
--   be derived for single-constructor datatypes whose constituent types
--   are in <a>Bounded</a>.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a

-- | Class <a>Enum</a> defines operations on sequentially ordered types.
--   
--   The <tt>enumFrom</tt>... methods are used in Haskell's translation of
--   arithmetic sequences.
--   
--   Instances of <a>Enum</a> may be derived for any enumeration type
--   (types whose constructors have no fields). The nullary constructors
--   are assumed to be numbered left-to-right by <a>fromEnum</a> from
--   <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell
--   Report</i> for more details.
--   
--   For any type that is an instance of class <a>Bounded</a> as well as
--   <a>Enum</a>, the following should hold:
--   
--   <ul>
--   <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a>
--   <a>minBound</a></tt> should result in a runtime error.</li>
--   <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if
--   the result value is not representable in the result type. For example,
--   <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li>
--   <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an
--   implicit bound, thus:</li>
--   </ul>
--   
--   <pre>
--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y &gt;= fromEnum x = maxBound
--             | otherwise                = minBound
--   </pre>
class Enum a

-- | the successor of a value. For numeric types, <a>succ</a> adds 1.
succ :: Enum a => a -> a

-- | the predecessor of a value. For numeric types, <a>pred</a> subtracts
--   1.
pred :: Enum a => a -> a

-- | Convert from an <a>Int</a>.
toEnum :: Enum a => Int -> a

-- | Convert to an <a>Int</a>. It is implementation-dependent what
--   <a>fromEnum</a> returns when applied to a value that is too large to
--   fit in an <a>Int</a>.
fromEnum :: Enum a => a -> Int

-- | Used in Haskell's translation of <tt>[n..]</tt> with <tt>[n..] =
--   enumFrom n</tt>, a possible implementation being <tt>enumFrom n = n :
--   enumFrom (succ n)</tt>. For example:
--   
--   <ul>
--   <li><pre>enumFrom 4 :: [Integer] = [4,5,6,7,...]</pre></li>
--   <li><pre>enumFrom 6 :: [Int] = [6,7,8,9,...,maxBound ::
--   Int]</pre></li>
--   </ul>
enumFrom :: Enum a => a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..]</tt> with <tt>[n,n'..] =
--   enumFromThen n n'</tt>, a possible implementation being
--   <tt>enumFromThen n n' = n : n' : worker (f x) (f x n')</tt>,
--   <tt>worker s v = v : worker s (s v)</tt>, <tt>x = fromEnum n' -
--   fromEnum n</tt> and <tt>f n y | n &gt; 0 = f (n - 1) (succ y) | n &lt;
--   0 = f (n + 1) (pred y) | otherwise = y</tt> For example:
--   
--   <ul>
--   <li><pre>enumFromThen 4 6 :: [Integer] = [4,6,8,10...]</pre></li>
--   <li><pre>enumFromThen 6 2 :: [Int] = [6,2,-2,-6,...,minBound ::
--   Int]</pre></li>
--   </ul>
enumFromThen :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n..m]</tt> with <tt>[n..m] =
--   enumFromTo n m</tt>, a possible implementation being <tt>enumFromTo n
--   m | n &lt;= m = n : enumFromTo (succ n) m | otherwise = []</tt>. For
--   example:
--   
--   <ul>
--   <li><pre>enumFromTo 6 10 :: [Int] = [6,7,8,9,10]</pre></li>
--   <li><pre>enumFromTo 42 1 :: [Integer] = []</pre></li>
--   </ul>
enumFromTo :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..m]</tt> with <tt>[n,n'..m]
--   = enumFromThenTo n n' m</tt>, a possible implementation being
--   <tt>enumFromThenTo n n' m = worker (f x) (c x) n m</tt>, <tt>x =
--   fromEnum n' - fromEnum n</tt>, <tt>c x = bool (&gt;=) (<a>(x</a>
--   0)</tt> <tt>f n y | n &gt; 0 = f (n - 1) (succ y) | n &lt; 0 = f (n +
--   1) (pred y) | otherwise = y</tt> and <tt>worker s c v m | c v m = v :
--   worker s c (s v) m | otherwise = []</tt> For example:
--   
--   <ul>
--   <li><pre>enumFromThenTo 4 2 -6 :: [Integer] =
--   [4,2,0,-2,-4,-6]</pre></li>
--   <li><pre>enumFromThenTo 6 8 2 :: [Int] = []</pre></li>
--   </ul>
enumFromThenTo :: Enum a => a -> a -> a -> [a]

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   The Haskell Report defines no laws for <a>Eq</a>. However, <a>==</a>
--   is customarily expected to implement an equivalence relationship where
--   two values comparing equal are indistinguishable by "public"
--   functions, with a "public" function being one not allowing to see
--   implementation details. For example, for a type representing
--   non-normalised natural numbers modulo 100, a "public" function doesn't
--   make the difference between 1 and 201. It is expected to have the
--   following properties:
--   
--   <ul>
--   <li><i><b>Reflexivity</b></i> <tt>x == x</tt> = <a>True</a></li>
--   <li><i><b>Symmetry</b></i> <tt>x == y</tt> = <tt>y == x</tt></li>
--   <li><i><b>Transitivity</b></i> if <tt>x == y &amp;&amp; y == z</tt> =
--   <a>True</a>, then <tt>x == z</tt> = <a>True</a></li>
--   <li><i><b>Substitutivity</b></i> if <tt>x == y</tt> = <a>True</a> and
--   <tt>f</tt> is a "public" function whose return type is an instance of
--   <a>Eq</a>, then <tt>f x == f y</tt> = <a>True</a></li>
--   <li><i><b>Negation</b></i> <tt>x /= y</tt> = <tt>not (x ==
--   y)</tt></li>
--   </ul>
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool
infix 4 ==
infix 4 /=

-- | Trigonometric and hyperbolic functions and related functions.
--   
--   The Haskell Report defines no laws for <a>Floating</a>. However,
--   <tt>(<a>+</a>)</tt>, <tt>(<a>*</a>)</tt> and <a>exp</a> are
--   customarily expected to define an exponential field and have the
--   following properties:
--   
--   <ul>
--   <li><tt>exp (a + b)</tt> = <tt>exp a * exp b</tt></li>
--   <li><tt>exp (fromInteger 0)</tt> = <tt>fromInteger 1</tt></li>
--   </ul>
class Fractional a => Floating a
pi :: Floating a => a
exp :: Floating a => a -> a
log :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a
infixr 8 **

-- | Fractional numbers, supporting real division.
--   
--   The Haskell Report defines no laws for <a>Fractional</a>. However,
--   <tt>(<a>+</a>)</tt> and <tt>(<a>*</a>)</tt> are customarily expected
--   to define a division ring and have the following properties:
--   
--   <ul>
--   <li><i><b><a>recip</a> gives the multiplicative inverse</b></i> <tt>x
--   * recip x</tt> = <tt>recip x * x</tt> = <tt>fromInteger 1</tt></li>
--   </ul>
--   
--   Note that it <i>isn't</i> customarily expected that a type instance of
--   <a>Fractional</a> implement a field. However, all instances in
--   <tt>base</tt> do.
class Num a => Fractional a

-- | Fractional division.
(/) :: Fractional a => a -> a -> a

-- | Reciprocal fraction.
recip :: Fractional a => a -> a

-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
--   <a>Integer</a></tt>). A floating literal stands for an application of
--   <a>fromRational</a> to a value of type <a>Rational</a>, so such
--   literals have type <tt>(<a>Fractional</a> a) =&gt; a</tt>.
fromRational :: Fractional a => Rational -> a
infixl 7 /

-- | Integral numbers, supporting integer division.
--   
--   The Haskell Report defines no laws for <a>Integral</a>. However,
--   <a>Integral</a> instances are customarily expected to define a
--   Euclidean domain and have the following properties for the
--   <a>div</a>/<a>mod</a> and <a>quot</a>/<a>rem</a> pairs, given suitable
--   Euclidean functions <tt>f</tt> and <tt>g</tt>:
--   
--   <ul>
--   <li><tt>x</tt> = <tt>y * quot x y + rem x y</tt> with <tt>rem x y</tt>
--   = <tt>fromInteger 0</tt> or <tt>g (rem x y)</tt> &lt; <tt>g
--   y</tt></li>
--   <li><tt>x</tt> = <tt>y * div x y + mod x y</tt> with <tt>mod x y</tt>
--   = <tt>fromInteger 0</tt> or <tt>f (mod x y)</tt> &lt; <tt>f
--   y</tt></li>
--   </ul>
--   
--   An example of a suitable Euclidean function, for <a>Integer</a>'s
--   instance, is <a>abs</a>.
class (Real a, Enum a) => Integral a

-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a

-- | integer remainder, satisfying
--   
--   <pre>
--   (x `quot` y)*y + (x `rem` y) == x
--   </pre>
rem :: Integral a => a -> a -> a

-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a

-- | integer modulus, satisfying
--   
--   <pre>
--   (x `div` y)*y + (x `mod` y) == x
--   </pre>
mod :: Integral a => a -> a -> a

-- | simultaneous <a>quot</a> and <a>rem</a>
quotRem :: Integral a => a -> a -> (a, a)

-- | simultaneous <a>div</a> and <a>mod</a>
divMod :: Integral a => a -> a -> (a, a)

-- | conversion to <a>Integer</a>
toInteger :: Integral a => a -> Integer
infixl 7 `mod`
infixl 7 `div`
infixl 7 `rem`
infixl 7 `quot`

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following:
--   
--   <ul>
--   <li><i>Left identity</i> <tt><a>return</a> a <a>&gt;&gt;=</a> k = k
--   a</tt></li>
--   <li><i>Right identity</i> <tt>m <a>&gt;&gt;=</a> <a>return</a> =
--   m</tt></li>
--   <li><i>Associativity</i> <tt>m <a>&gt;&gt;=</a> (\x -&gt; k x
--   <a>&gt;&gt;=</a> h) = (m <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a>
--   h</tt></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>m1 <a>&lt;*&gt;</a> m2 = m1 <a>&gt;&gt;=</a> (x1 -&gt; m2
--   <a>&gt;&gt;=</a> (x2 -&gt; <a>return</a> (x1 x2)))</pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: Type -> Type)

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
--   
--   '<tt>as <a>&gt;&gt;=</a> bs</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do a &lt;- as
--      bs a
--   </pre>
(>>=) :: Monad m => m a -> (a -> m b) -> m b

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
--   
--   '<tt>as <a>&gt;&gt;</a> bs</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do as
--      bs
--   </pre>
(>>) :: Monad m => m a -> m b -> m b

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a
infixl 1 >>=
infixl 1 >>

-- | A type <tt>f</tt> is a Functor if it provides a function <tt>fmap</tt>
--   which, given any types <tt>a</tt> and <tt>b</tt> lets you apply any
--   function from <tt>(a -&gt; b)</tt> to turn an <tt>f a</tt> into an
--   <tt>f b</tt>, preserving the structure of <tt>f</tt>. Furthermore
--   <tt>f</tt> needs to adhere to the following:
--   
--   <ul>
--   <li><i>Identity</i> <tt><a>fmap</a> <a>id</a> == <a>id</a></tt></li>
--   <li><i>Composition</i> <tt><a>fmap</a> (f . g) == <a>fmap</a> f .
--   <a>fmap</a> g</tt></li>
--   </ul>
--   
--   Note, that the second law follows from the free theorem of the type
--   <a>fmap</a> and the first law, so you need only check that the former
--   condition holds.
class Functor (f :: Type -> Type)

-- | Using <tt>ApplicativeDo</tt>: '<tt><a>fmap</a> f as</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      pure (f a)
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint.
fmap :: Functor f => (a -> b) -> f a -> f b

-- | Replace all locations in the input with the same value. The default
--   definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
--   overridden with a more efficient version.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt>a <a>&lt;$</a> bs</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do bs
--      pure a
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint.
(<$) :: Functor f => a -> f b -> f a
infixl 4 <$

-- | Basic numeric class.
--   
--   The Haskell Report defines no laws for <a>Num</a>. However,
--   <tt>(<a>+</a>)</tt> and <tt>(<a>*</a>)</tt> are customarily expected
--   to define a ring and have the following properties:
--   
--   <ul>
--   <li><i><b>Associativity of <tt>(<a>+</a>)</tt></b></i> <tt>(x + y) +
--   z</tt> = <tt>x + (y + z)</tt></li>
--   <li><i><b>Commutativity of <tt>(<a>+</a>)</tt></b></i> <tt>x + y</tt>
--   = <tt>y + x</tt></li>
--   <li><i><b><tt><a>fromInteger</a> 0</tt> is the additive
--   identity</b></i> <tt>x + fromInteger 0</tt> = <tt>x</tt></li>
--   <li><i><b><a>negate</a> gives the additive inverse</b></i> <tt>x +
--   negate x</tt> = <tt>fromInteger 0</tt></li>
--   <li><i><b>Associativity of <tt>(<a>*</a>)</tt></b></i> <tt>(x * y) *
--   z</tt> = <tt>x * (y * z)</tt></li>
--   <li><i><b><tt><a>fromInteger</a> 1</tt> is the multiplicative
--   identity</b></i> <tt>x * fromInteger 1</tt> = <tt>x</tt> and
--   <tt>fromInteger 1 * x</tt> = <tt>x</tt></li>
--   <li><i><b>Distributivity of <tt>(<a>*</a>)</tt> with respect to
--   <tt>(<a>+</a>)</tt></b></i> <tt>a * (b + c)</tt> = <tt>(a * b) + (a *
--   c)</tt> and <tt>(b + c) * a</tt> = <tt>(b * a) + (c * a)</tt></li>
--   </ul>
--   
--   Note that it <i>isn't</i> customarily expected that a type instance of
--   both <a>Num</a> and <a>Ord</a> implement an ordered ring. Indeed, in
--   <tt>base</tt> only <a>Integer</a> and <a>Rational</a> do.
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
--   satisfy the law:
--   
--   <pre>
--   abs x * signum x == x
--   </pre>
--   
--   For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
--   <tt>0</tt> (zero) or <tt>1</tt> (positive).
signum :: Num a => a -> a

-- | Conversion from an <a>Integer</a>. An integer literal represents the
--   application of the function <a>fromInteger</a> to the appropriate
--   value of type <a>Integer</a>, so such literals have type
--   <tt>(<a>Num</a> a) =&gt; a</tt>.
fromInteger :: Num a => Integer -> a
infixl 6 -
infixl 6 +
infixl 7 *

-- | The <a>Ord</a> class is used for totally ordered datatypes.
--   
--   Instances of <a>Ord</a> can be derived for any user-defined datatype
--   whose constituent types are in <a>Ord</a>. The declared order of the
--   constructors in the data declaration determines the ordering in
--   derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
--   single comparison to determine the precise ordering of two objects.
--   
--   The Haskell Report defines no laws for <a>Ord</a>. However,
--   <a>&lt;=</a> is customarily expected to implement a non-strict partial
--   order and have the following properties:
--   
--   <ul>
--   <li><i><b>Transitivity</b></i> if <tt>x &lt;= y &amp;&amp; y &lt;=
--   z</tt> = <a>True</a>, then <tt>x &lt;= z</tt> = <a>True</a></li>
--   <li><i><b>Reflexivity</b></i> <tt>x &lt;= x</tt> = <a>True</a></li>
--   <li><i><b>Antisymmetry</b></i> if <tt>x &lt;= y &amp;&amp; y &lt;=
--   x</tt> = <a>True</a>, then <tt>x == y</tt> = <a>True</a></li>
--   </ul>
--   
--   Note that the following operator interactions are expected to hold:
--   
--   <ol>
--   <li><tt>x &gt;= y</tt> = <tt>y &lt;= x</tt></li>
--   <li><tt>x &lt; y</tt> = <tt>x &lt;= y &amp;&amp; x /= y</tt></li>
--   <li><tt>x &gt; y</tt> = <tt>y &lt; x</tt></li>
--   <li><tt>x &lt; y</tt> = <tt>compare x y == LT</tt></li>
--   <li><tt>x &gt; y</tt> = <tt>compare x y == GT</tt></li>
--   <li><tt>x == y</tt> = <tt>compare x y == EQ</tt></li>
--   <li><tt>min x y == if x &lt;= y then x else y</tt> = <a>True</a></li>
--   <li><tt>max x y == if x &gt;= y then x else y</tt> = <a>True</a></li>
--   </ol>
--   
--   Note that (7.) and (8.) do <i>not</i> require <a>min</a> and
--   <a>max</a> to return either of their arguments. The result is merely
--   required to <i>equal</i> one of the arguments in terms of <a>(==)</a>.
--   
--   Minimal complete definition: either <a>compare</a> or <a>&lt;=</a>.
--   Using <a>compare</a> can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a
infix 4 <
infix 4 <=
infix 4 >
infix 4 >=

-- | Parsing of <a>String</a>s, producing values.
--   
--   Derived instances of <a>Read</a> make the following assumptions, which
--   derived instances of <a>Show</a> obey:
--   
--   <ul>
--   <li>If the constructor is defined to be an infix operator, then the
--   derived <a>Read</a> instance will parse only infix applications of the
--   constructor (not the prefix form).</li>
--   <li>Associativity is not used to reduce the occurrence of parentheses,
--   although precedence may be.</li>
--   <li>If the constructor is defined using record syntax, the derived
--   <a>Read</a> will parse only the record-syntax form, and furthermore,
--   the fields must be given in the same order as the original
--   declaration.</li>
--   <li>The derived <a>Read</a> instance allows arbitrary Haskell
--   whitespace between tokens of the input string. Extra parentheses are
--   also allowed.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readsPrec d r =  readParen (d &gt; app_prec)
--                            (\r -&gt; [(Leaf m,t) |
--                                    ("Leaf",s) &lt;- lex r,
--                                    (m,t) &lt;- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d &gt; up_prec)
--                            (\r -&gt; [(u:^:v,w) |
--                                    (u,s) &lt;- readsPrec (up_prec+1) r,
--                                    (":^:",t) &lt;- lex s,
--                                    (v,w) &lt;- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is unused.
--   
--   The derived instance in GHC is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" &lt;- lexP
--                                    m &lt;- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u &lt;- step readPrec
--                                    Symbol ":^:" &lt;- lexP
--                                    v &lt;- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--   </pre>
--   
--   Why do both <a>readsPrec</a> and <a>readPrec</a> exist, and why does
--   GHC opt to implement <a>readPrec</a> in derived <a>Read</a> instances
--   instead of <a>readsPrec</a>? The reason is that <a>readsPrec</a> is
--   based on the <a>ReadS</a> type, and although <a>ReadS</a> is mentioned
--   in the Haskell 2010 Report, it is not a very efficient parser data
--   structure.
--   
--   <a>readPrec</a>, on the other hand, is based on a much more efficient
--   <a>ReadPrec</a> datatype (a.k.a "new-style parsers"), but its
--   definition relies on the use of the <tt>RankNTypes</tt> language
--   extension. Therefore, <a>readPrec</a> (and its cousin,
--   <a>readListPrec</a>) are marked as GHC-only. Nevertheless, it is
--   recommended to use <a>readPrec</a> instead of <a>readsPrec</a>
--   whenever possible for the efficiency improvements it brings.
--   
--   As mentioned above, derived <a>Read</a> instances in GHC will
--   implement <a>readPrec</a> instead of <a>readsPrec</a>. The default
--   implementations of <a>readsPrec</a> (and its cousin, <a>readList</a>)
--   will simply use <a>readPrec</a> under the hood. If you are writing a
--   <a>Read</a> instance by hand, it is recommended to write it like so:
--   
--   <pre>
--   instance <a>Read</a> T where
--     <a>readPrec</a>     = ...
--     <a>readListPrec</a> = <a>readListPrecDefault</a>
--   </pre>
class Read a

-- | attempts to parse a value from the front of the string, returning a
--   list of (parsed value, remaining string) pairs. If there is no
--   successful parse, the returned list is empty.
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
readsPrec :: Read a => Int -> ReadS a

-- | The method <a>readList</a> is provided to allow the programmer to give
--   a specialised way of parsing lists of values. For example, this is
--   used by the predefined <a>Read</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be are expected to use
--   double quotes, rather than square brackets.
readList :: Read a => ReadS [a]
class (Num a, Ord a) => Real a

-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational

-- | Efficient, machine-independent access to the components of a
--   floating-point number.
class (RealFrac a, Floating a) => RealFloat a

-- | a constant function, returning the radix of the representation (often
--   <tt>2</tt>)
floatRadix :: RealFloat a => a -> Integer

-- | a constant function, returning the number of digits of
--   <a>floatRadix</a> in the significand
floatDigits :: RealFloat a => a -> Int

-- | a constant function, returning the lowest and highest values the
--   exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)

-- | The function <a>decodeFloat</a> applied to a real floating-point
--   number returns the significand expressed as an <a>Integer</a> and an
--   appropriately scaled exponent (an <a>Int</a>). If
--   <tt><a>decodeFloat</a> x</tt> yields <tt>(m,n)</tt>, then <tt>x</tt>
--   is equal in value to <tt>m*b^^n</tt>, where <tt>b</tt> is the
--   floating-point radix, and furthermore, either <tt>m</tt> and
--   <tt>n</tt> are both zero or else <tt>b^(d-1) &lt;= <a>abs</a> m &lt;
--   b^d</tt>, where <tt>d</tt> is the value of <tt><a>floatDigits</a>
--   x</tt>. In particular, <tt><a>decodeFloat</a> 0 = (0,0)</tt>. If the
--   type contains a negative zero, also <tt><a>decodeFloat</a> (-0.0) =
--   (0,0)</tt>. <i>The result of</i> <tt><a>decodeFloat</a> x</tt> <i>is
--   unspecified if either of</i> <tt><a>isNaN</a> x</tt> <i>or</i>
--   <tt><a>isInfinite</a> x</tt> <i>is</i> <a>True</a>.
decodeFloat :: RealFloat a => a -> (Integer, Int)

-- | <a>encodeFloat</a> performs the inverse of <a>decodeFloat</a> in the
--   sense that for finite <tt>x</tt> with the exception of <tt>-0.0</tt>,
--   <tt><a>uncurry</a> <a>encodeFloat</a> (<a>decodeFloat</a> x) = x</tt>.
--   <tt><a>encodeFloat</a> m n</tt> is one of the two closest
--   representable floating-point numbers to <tt>m*b^^n</tt> (or
--   <tt>±Infinity</tt> if overflow occurs); usually the closer, but if
--   <tt>m</tt> contains too many bits, the result may be rounded in the
--   wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a

-- | <a>exponent</a> corresponds to the second component of
--   <a>decodeFloat</a>. <tt><a>exponent</a> 0 = 0</tt> and for finite
--   nonzero <tt>x</tt>, <tt><a>exponent</a> x = snd (<a>decodeFloat</a> x)
--   + <a>floatDigits</a> x</tt>. If <tt>x</tt> is a finite floating-point
--   number, it is equal in value to <tt><a>significand</a> x * b ^^
--   <a>exponent</a> x</tt>, where <tt>b</tt> is the floating-point radix.
--   The behaviour is unspecified on infinite or <tt>NaN</tt> values.
exponent :: RealFloat a => a -> Int

-- | The first component of <a>decodeFloat</a>, scaled to lie in the open
--   interval (<tt>-1</tt>,<tt>1</tt>), either <tt>0.0</tt> or of absolute
--   value <tt>&gt;= 1/b</tt>, where <tt>b</tt> is the floating-point
--   radix. The behaviour is unspecified on infinite or <tt>NaN</tt>
--   values.
significand :: RealFloat a => a -> a

-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a

-- | <a>True</a> if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is too small to be represented in
--   normalized format
isDenormalized :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool

-- | a version of arctangent taking two real floating-point arguments. For
--   real floating <tt>x</tt> and <tt>y</tt>, <tt><a>atan2</a> y x</tt>
--   computes the angle (from the positive x-axis) of the vector from the
--   origin to the point <tt>(x,y)</tt>. <tt><a>atan2</a> y x</tt> returns
--   a value in the range [<tt>-pi</tt>, <tt>pi</tt>]. It follows the
--   Common Lisp semantics for the origin when signed zeroes are supported.
--   <tt><a>atan2</a> y 1</tt>, with <tt>y</tt> in a type that is
--   <a>RealFloat</a>, should return the same value as <tt><a>atan</a>
--   y</tt>. A default definition of <a>atan2</a> is provided, but
--   implementors can provide a more accurate implementation.
atan2 :: RealFloat a => a -> a -> a

-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a

-- | The function <a>properFraction</a> takes a real fractional number
--   <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
--   n+f</tt>, and:
--   
--   <ul>
--   <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
--   and</li>
--   <li><tt>f</tt> is a fraction with the same type and sign as
--   <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
--   </ul>
--   
--   The default definitions of the <a>ceiling</a>, <a>floor</a>,
--   <a>truncate</a> and <a>round</a> functions are in terms of
--   <a>properFraction</a>.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)

-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
--   between zero and <tt>x</tt>
truncate :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
--   even integer if <tt>x</tt> is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
--   <tt>x</tt>
ceiling :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
--   <tt>x</tt>
floor :: (RealFrac a, Integral b) => a -> b

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | Convert a value to a readable <a>String</a>.
--   
--   <a>showsPrec</a> should satisfy the law
--   
--   <pre>
--   showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
--   </pre>
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
showsPrec :: Show a => Int -> a -> ShowS

-- | A specialised variant of <a>showsPrec</a>, using precedence context
--   zero, and returning an ordinary <a>String</a>.
show :: Show a => a -> String

-- | The method <a>showList</a> is provided to allow the programmer to give
--   a specialised way of showing lists of values. For example, this is
--   used by the predefined <a>Show</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be shown in double quotes,
--   rather than between square brackets.
showList :: Show a => [a] -> ShowS

-- | When a value is bound in <tt>do</tt>-notation, the pattern on the left
--   hand side of <tt>&lt;-</tt> might not match. In this case, this class
--   provides a function to recover.
--   
--   A <a>Monad</a> without a <a>MonadFail</a> instance may only be used in
--   conjunction with pattern that always match, such as newtypes, tuples,
--   data types with only a single data constructor, and irrefutable
--   patterns (<tt>~pat</tt>).
--   
--   Instances of <a>MonadFail</a> should satisfy the following law:
--   <tt>fail s</tt> should be a left zero for <a>&gt;&gt;=</a>,
--   
--   <pre>
--   fail s &gt;&gt;= f  =  fail s
--   </pre>
--   
--   If your <a>Monad</a> is also <a>MonadPlus</a>, a popular definition is
--   
--   <pre>
--   fail _ = mzero
--   </pre>
class Monad m => MonadFail (m :: Type -> Type)
fail :: MonadFail m => String -> m a

-- | A functor with application, providing operations to
--   
--   <ul>
--   <li>embed pure expressions (<a>pure</a>), and</li>
--   <li>sequence computations and combine their results (<a>&lt;*&gt;</a>
--   and <a>liftA2</a>).</li>
--   </ul>
--   
--   A minimal complete definition must include implementations of
--   <a>pure</a> and of either <a>&lt;*&gt;</a> or <a>liftA2</a>. If it
--   defines both, then they must behave the same as their default
--   definitions:
--   
--   <pre>
--   (<a>&lt;*&gt;</a>) = <a>liftA2</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>liftA2</a> f x y = f <a>&lt;$&gt;</a> x <a>&lt;*&gt;</a> y
--   </pre>
--   
--   Further, any definition must satisfy the following:
--   
--   <ul>
--   <li><i>Identity</i> <pre><a>pure</a> <a>id</a> <a>&lt;*&gt;</a> v =
--   v</pre></li>
--   <li><i>Composition</i> <pre><a>pure</a> (.) <a>&lt;*&gt;</a> u
--   <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v
--   <a>&lt;*&gt;</a> w)</pre></li>
--   <li><i>Homomorphism</i> <pre><a>pure</a> f <a>&lt;*&gt;</a>
--   <a>pure</a> x = <a>pure</a> (f x)</pre></li>
--   <li><i>Interchange</i> <pre>u <a>&lt;*&gt;</a> <a>pure</a> y =
--   <a>pure</a> (<a>$</a> y) <a>&lt;*&gt;</a> u</pre></li>
--   </ul>
--   
--   The other methods have the following default definitions, which may be
--   overridden with equivalent specialized implementations:
--   
--   <ul>
--   <li><pre>u <a>*&gt;</a> v = (<a>id</a> <a>&lt;$</a> u)
--   <a>&lt;*&gt;</a> v</pre></li>
--   <li><pre>u <a>&lt;*</a> v = <a>liftA2</a> <a>const</a> u v</pre></li>
--   </ul>
--   
--   As a consequence of these laws, the <a>Functor</a> instance for
--   <tt>f</tt> will satisfy
--   
--   <ul>
--   <li><pre><a>fmap</a> f x = <a>pure</a> f <a>&lt;*&gt;</a> x</pre></li>
--   </ul>
--   
--   It may be useful to note that supposing
--   
--   <pre>
--   forall x y. p (q x y) = f x . g y
--   </pre>
--   
--   it follows from the above that
--   
--   <pre>
--   <a>liftA2</a> p (<a>liftA2</a> q u v) = <a>liftA2</a> f u . <a>liftA2</a> g v
--   </pre>
--   
--   If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>m1 <a>&lt;*&gt;</a> m2 = m1 <a>&gt;&gt;=</a> (x1 -&gt; m2
--   <a>&gt;&gt;=</a> (x2 -&gt; <a>return</a> (x1 x2)))</pre></li>
--   <li><pre>(<a>*&gt;</a>) = (<a>&gt;&gt;</a>)</pre></li>
--   </ul>
--   
--   (which implies that <a>pure</a> and <a>&lt;*&gt;</a> satisfy the
--   applicative functor laws).
class Functor f => Applicative (f :: Type -> Type)

-- | Lift a value.
pure :: Applicative f => a -> f a

-- | Sequential application.
--   
--   A few functors support an implementation of <a>&lt;*&gt;</a> that is
--   more efficient than the default one.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt>fs <a>&lt;*&gt;</a> as</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do f &lt;- fs
--      a &lt;- as
--      pure (f a)
--   </pre>
(<*>) :: Applicative f => f (a -> b) -> f a -> f b

-- | Sequence actions, discarding the value of the first argument.
--   
--   '<tt>as <a>*&gt;</a> bs</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do as
--      bs
--   </pre>
--   
--   This is a tad complicated for our <tt>ApplicativeDo</tt> extension
--   which will give it a <tt>Monad</tt> constraint. For an
--   <tt>Applicative</tt> constraint we write it of the form
--   
--   <pre>
--   do _ &lt;- as
--      b &lt;- bs
--      pure b
--   </pre>
(*>) :: Applicative f => f a -> f b -> f b

-- | Sequence actions, discarding the value of the second argument.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt>as <a>&lt;*</a> bs</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      bs
--      pure a
--   </pre>
(<*) :: Applicative f => f a -> f b -> f a
infixl 4 <*
infixl 4 *>
infixl 4 <*>

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <pre>
--   length = getSum . foldMap (Sum . const  1)
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: Type -> Type)

-- | Map each element of the structure to a monoid, and combine the
--   results.
foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool

-- | The <a>sum</a> function computes the sum of the numbers of a
--   structure.
sum :: (Foldable t, Num a) => t a -> a

-- | The <a>product</a> function computes the product of the numbers of a
--   structure.
product :: (Foldable t, Num a) => t a -> a
infix 4 `elem`

-- | Functors representing data structures that can be traversed from left
--   to right.
--   
--   A definition of <a>traverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i>Naturality</i> <tt>t . <a>traverse</a> f = <a>traverse</a> (t .
--   f)</tt> for every applicative transformation <tt>t</tt></li>
--   <li><i>Identity</i> <tt><a>traverse</a> <a>Identity</a> =
--   <a>Identity</a></tt></li>
--   <li><i>Composition</i> <tt><a>traverse</a> (<a>Compose</a> .
--   <a>fmap</a> g . f) = <a>Compose</a> . <a>fmap</a> (<a>traverse</a> g)
--   . <a>traverse</a> f</tt></li>
--   </ul>
--   
--   A definition of <a>sequenceA</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i>Naturality</i> <tt>t . <a>sequenceA</a> = <a>sequenceA</a> .
--   <a>fmap</a> t</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i>Identity</i> <tt><a>sequenceA</a> . <a>fmap</a> <a>Identity</a>
--   = <a>Identity</a></tt></li>
--   <li><i>Composition</i> <tt><a>sequenceA</a> . <a>fmap</a>
--   <a>Compose</a> = <a>Compose</a> . <a>fmap</a> <a>sequenceA</a> .
--   <a>sequenceA</a></tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (Applicative f, Applicative g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations, i.e.
--   
--   <pre>
--   t (<a>pure</a> x) = <a>pure</a> x
--   t (f <a>&lt;*&gt;</a> x) = t f <a>&lt;*&gt;</a> t x
--   </pre>
--   
--   and the identity functor <a>Identity</a> and composition functors
--   <a>Compose</a> are from <a>Data.Functor.Identity</a> and
--   <a>Data.Functor.Compose</a>.
--   
--   A result of the naturality law is a purity law for <a>traverse</a>
--   
--   <pre>
--   <a>traverse</a> <a>pure</a> = <a>pure</a>
--   </pre>
--   
--   (The naturality law is implied by parametricity and thus so is the
--   purity law [1, p15].)
--   
--   Instances are similar to <a>Functor</a>, e.g. given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Traversable Tree where
--      traverse f Empty = pure Empty
--      traverse f (Leaf x) = Leaf &lt;$&gt; f x
--      traverse f (Node l k r) = Node &lt;$&gt; traverse f l &lt;*&gt; f k &lt;*&gt; traverse f r
--   </pre>
--   
--   This is suitable even for abstract types, as the laws for
--   <a>&lt;*&gt;</a> imply a form of associativity.
--   
--   The superclass instances should satisfy the following:
--   
--   <ul>
--   <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
--   to traversal with the identity applicative functor
--   (<a>fmapDefault</a>).</li>
--   <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
--   equivalent to traversal with a constant applicative functor
--   (<a>foldMapDefault</a>).</li>
--   </ul>
--   
--   References: [1] The Essence of the Iterator Pattern, Jeremy Gibbons
--   and Bruno C. d. S. Oliveira
class (Functor t, Foldable t) => Traversable (t :: Type -> Type)

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results see <a>traverse_</a>.
traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)

-- | Evaluate each action in the structure from left to right, and collect
--   the results. For a version that ignores the results see
--   <a>sequenceA_</a>.
sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a)

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the following:
--   
--   <ul>
--   <li><i>Associativity</i> <tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) =
--   (x <a>&lt;&gt;</a> y) <a>&lt;&gt;</a> z</tt></li>
--   </ul>
class Semigroup a

-- | An associative operation.
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &lt;&gt; [4,5,6]
--   [1,2,3,4,5,6]
--   </pre>
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following:
--   
--   <ul>
--   <li><i>Right identity</i> <tt>x <a>&lt;&gt;</a> <a>mempty</a> =
--   x</tt></li>
--   <li><i>Left identity</i> <tt><a>mempty</a> <a>&lt;&gt;</a> x =
--   x</tt></li>
--   <li><i>Associativity</i> <tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) =
--   (x <a>&lt;&gt;</a> y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a>
--   law)</li>
--   <li><i>Concatenation</i> <tt><a>mconcat</a> = <a>foldr</a>
--   (<a>&lt;&gt;</a>) <a>mempty</a></tt></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <a>Sum</a> and <a>Product</a>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | Identity of <a>mappend</a>
--   
--   <pre>
--   &gt;&gt;&gt; "Hello world" &lt;&gt; mempty
--   "Hello world"
--   </pre>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = (<a>&lt;&gt;</a>)</tt> since
--   <i>base-4.11.0.0</i>. Should it be implemented manually, since
--   <a>mappend</a> is a synonym for (<a>&lt;&gt;</a>), it is expected that
--   the two functions are defined the same way. In a future GHC release
--   <a>mappend</a> will be removed from <a>Monoid</a>.
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized version can be provided for specific types.
--   
--   <pre>
--   &gt;&gt;&gt; mconcat ["Hello", " ", "Haskell", "!"]
--   "Hello Haskell!"
--   </pre>
mconcat :: Monoid a => [a] -> a
data Bool
False :: Bool
True :: Bool

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <a>ord</a> and
--   <a>chr</a>).
data Char

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <a>minBound</a> and <a>maxBound</a> from the
--   <a>Bounded</a> class.
data Int

-- | Arbitrary precision integers. In contrast with fixed-size integral
--   types such as <a>Int</a>, the <a>Integer</a> type represents the
--   entire infinite range of integers.
--   
--   For more information about this type's representation, see the
--   comments in its implementation.
data Integer

-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
--   <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
--   (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
--   as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
--   errors or exceptional cases without resorting to drastic measures such
--   as <a>error</a>.
--   
--   The <a>Maybe</a> type is also a monad. It is a simple kind of error
--   monad, where all errors are represented by <a>Nothing</a>. A richer
--   error monad can be built using the <a>Either</a> type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering

-- | Arbitrary-precision rational numbers, represented as a ratio of two
--   <a>Integer</a> values. A rational number may be constructed using the
--   <a>%</a> operator.
type Rational = Ratio Integer

-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
--   performed, does some I/O before returning a value of type <tt>a</tt>.
--   
--   There is really only one way to "perform" an I/O action: bind it to
--   <tt>Main.main</tt> in your program. When your program is run, the I/O
--   will be performed. It isn't possible to perform I/O from an arbitrary
--   function, unless that function is itself in the <a>IO</a> monad and
--   called at some point, directly or indirectly, from <tt>Main.main</tt>.
--   
--   <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
--   either the do-notation or the <a>&gt;&gt;</a> and <a>&gt;&gt;=</a>
--   operations from the <a>Monad</a> class.
data IO a

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | The <a>Either</a> type represents values with two possibilities: a
--   value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
--   a</tt> or <tt><a>Right</a> b</tt>.
--   
--   The <a>Either</a> type is sometimes used to represent a value which is
--   either correct or an error; by convention, the <a>Left</a> constructor
--   is used to hold an error value and the <a>Right</a> constructor is
--   used to hold a correct value (mnemonic: "right" also means "correct").
--   
--   <h4><b>Examples</b></h4>
--   
--   The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
--   of values which can be either a <a>String</a> or an <a>Int</a>. The
--   <a>Left</a> constructor can be used only on <a>String</a>s, and the
--   <a>Right</a> constructor can be used only on <a>Int</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; s
--   Left "foo"
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; n
--   Right 3
--   
--   &gt;&gt;&gt; :type s
--   s :: Either String Int
--   
--   &gt;&gt;&gt; :type n
--   n :: Either String Int
--   </pre>
--   
--   The <a>fmap</a> from our <a>Functor</a> instance will ignore
--   <a>Left</a> values, but will apply the supplied function to values
--   contained in a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; fmap (*2) s
--   Left "foo"
--   
--   &gt;&gt;&gt; fmap (*2) n
--   Right 6
--   </pre>
--   
--   The <a>Monad</a> instance for <a>Either</a> allows us to chain
--   together multiple actions which may fail, and fail overall if any of
--   the individual steps failed. First we'll write a function that can
--   either parse an <a>Int</a> from a <a>Char</a>, or fail.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Char ( digitToInt, isDigit )
--   
--   &gt;&gt;&gt; :{
--       let parseEither :: Char -&gt; Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
--   can be parsed as <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither '1'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Right 3
--   </pre>
--   
--   But the following should fail overall, since the first operation where
--   we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither 'm'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Left "parse error"
--   </pre>
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b

-- | A <a>String</a> is a list of characters. String constants in Haskell
--   are values of type <a>String</a>.
--   
--   See <a>Data.List</a> for operations on lists.
type String = [Char]

-- | Identity function.
--   
--   <pre>
--   id x = x
--   </pre>
id :: a -> a

-- | Case analysis for the <a>Either</a> type. If the value is
--   <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
--   is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   We create two values of type <tt><a>Either</a> <a>String</a>
--   <a>Int</a></tt>, one using the <a>Left</a> constructor and another
--   using the <a>Right</a> constructor. Then we apply "either" the
--   <a>length</a> function (if we have a <a>String</a>) or the "times-two"
--   function (if we have an <a>Int</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; either length (*2) s
--   3
--   
--   &gt;&gt;&gt; either length (*2) n
--   6
--   </pre>
either :: (a -> c) -> (b -> c) -> Either a b -> c

-- | The <a>readIO</a> function is similar to <a>read</a> except that it
--   signals parse failure to the <a>IO</a> monad instead of terminating
--   the program.
readIO :: Read a => String -> IO a

-- | The <a>readLn</a> function combines <a>getLine</a> and <a>readIO</a>.
readLn :: Read a => IO a

-- | The computation <a>appendFile</a> <tt>file str</tt> function appends
--   the string <tt>str</tt>, to the file <tt>file</tt>.
--   
--   Note that <a>writeFile</a> and <a>appendFile</a> write a literal
--   string to a file. To write a value of any printable type, as with
--   <a>print</a>, use the <a>show</a> function to convert the value to a
--   string first.
--   
--   <pre>
--   main = appendFile "squares" (show [(x,x*x) | x &lt;- [0,0.1..2]])
--   </pre>
appendFile :: FilePath -> String -> IO ()

-- | The computation <a>writeFile</a> <tt>file str</tt> function writes the
--   string <tt>str</tt>, to the file <tt>file</tt>.
writeFile :: FilePath -> String -> IO ()

-- | The <a>readFile</a> function reads a file and returns the contents of
--   the file as a string. The file is read lazily, on demand, as with
--   <a>getContents</a>.
readFile :: FilePath -> IO String

-- | The <a>interact</a> function takes a function of type
--   <tt>String-&gt;String</tt> as its argument. The entire input from the
--   standard input device is passed to this function as its argument, and
--   the resulting string is output on the standard output device.
interact :: (String -> String) -> IO ()

-- | The <a>getContents</a> operation returns all user input as a single
--   string, which is read lazily as it is needed (same as
--   <a>hGetContents</a> <a>stdin</a>).
getContents :: IO String

-- | The same as <a>putStr</a>, but adds a newline character.
putStrLn :: String -> IO ()

-- | Write a string to the standard output device (same as <a>hPutStr</a>
--   <a>stdout</a>).
putStr :: String -> IO ()

-- | Raise an <a>IOError</a> in the <a>IO</a> monad.
ioError :: IOError -> IO a

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String

-- | Construct an <a>IOError</a> value with a string describing the error.
--   The <tt>fail</tt> method of the <a>IO</a> instance of the <a>Monad</a>
--   class raises a <a>userError</a>, thus:
--   
--   <pre>
--   instance Monad IO where
--     ...
--     fail s = ioError (userError s)
--   </pre>
userError :: String -> IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
--   operation may raise an <a>IOError</a> instead of returning a result.
--   For a more general type of exception, including also those that arise
--   in pure code, see <a>Exception</a>.
--   
--   In Haskell 2010, this is an opaque type.
type IOError = IOException

-- | <a>notElem</a> is the negation of <a>elem</a>.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => (a -> Bool) -> t a -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => (a -> Bool) -> t a -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()

-- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words
--   with separating spaces.
--   
--   <pre>
--   &gt;&gt;&gt; unwords ["Lorem", "ipsum", "dolor"]
--   "Lorem ipsum dolor"
--   </pre>
unwords :: [String] -> String

-- | <a>words</a> breaks a string up into a list of words, which were
--   delimited by white space.
--   
--   <pre>
--   &gt;&gt;&gt; words "Lorem ipsum\ndolor"
--   ["Lorem","ipsum","dolor"]
--   </pre>
words :: String -> [String]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
--   
--   <pre>
--   &gt;&gt;&gt; unlines ["Hello", "World", "!"]
--   "Hello\nWorld\n!\n"
--   </pre>
unlines :: [String] -> String

-- | <a>lines</a> breaks a string up into a list of strings at newline
--   characters. The resulting strings do not contain newlines.
--   
--   Note that after splitting the string at newline characters, the last
--   part of the string is considered a line even if it doesn't end with a
--   newline. For example,
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "\n"
--   [""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n\n"
--   ["one",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo"
--   ["one","two"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo\n"
--   ["one","two"]
--   </pre>
--   
--   Thus <tt><a>lines</a> s</tt> contains at least as many elements as
--   newlines in <tt>s</tt>.
lines :: String -> [String]

-- | The <a>read</a> function reads input from a string, which must be
--   completely consumed by the input process. <a>read</a> fails with an
--   <a>error</a> if the parse is unsuccessful, and it is therefore
--   discouraged from being used in real applications. Use <a>readMaybe</a>
--   or <a>readEither</a> for safe alternatives.
--   
--   <pre>
--   &gt;&gt;&gt; read "123" :: Int
--   123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--   </pre>
read :: Read a => String -> a

-- | equivalent to <a>readsPrec</a> with a precedence of 0.
reads :: Read a => ReadS a

-- | The <a>lex</a> function reads a single lexeme from the input,
--   discarding initial white space, and returning the characters that
--   constitute the lexeme. If the input string contains only white space,
--   <a>lex</a> returns a single successful `lexeme' consisting of the
--   empty string. (Thus <tt><a>lex</a> "" = [("","")]</tt>.) If there is
--   no legal lexeme at the beginning of the input string, <a>lex</a> fails
--   (i.e. returns <tt>[]</tt>).
--   
--   This lexer is not completely faithful to the Haskell lexical syntax in
--   the following respects:
--   
--   <ul>
--   <li>Qualified names are not handled properly</li>
--   <li>Octal and hexadecimal numerics are not recognized as a single
--   token</li>
--   <li>Comments are not treated properly</li>
--   </ul>
lex :: ReadS String

-- | <tt><a>readParen</a> <a>True</a> p</tt> parses what <tt>p</tt> parses,
--   but surrounded with parentheses.
--   
--   <tt><a>readParen</a> <a>False</a> p</tt> parses what <tt>p</tt>
--   parses, but optionally surrounded with parentheses.
readParen :: Bool -> ReadS a -> ReadS a

-- | A parser for a type <tt>a</tt>, represented as a function that takes a
--   <a>String</a> and returns a list of possible parses as
--   <tt>(a,<a>String</a>)</tt> pairs.
--   
--   Note that this kind of backtracking parser is very inefficient;
--   reading a large structure may be quite slow (cf <a>ReadP</a>).
type ReadS a = String -> [(a, String)]

-- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both
--   <tt>x</tt> and <tt>y</tt> divide.
lcm :: Integral a => a -> a -> a

-- | <tt><a>gcd</a> x y</tt> is the non-negative factor of both <tt>x</tt>
--   and <tt>y</tt> of which every common factor of <tt>x</tt> and
--   <tt>y</tt> is also a factor; for example <tt><a>gcd</a> 4 2 = 2</tt>,
--   <tt><a>gcd</a> (-4) 6 = 2</tt>, <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>.
--   <tt><a>gcd</a> 0 0</tt> = <tt>0</tt>. (That is, the common divisor
--   that is "greatest" in the divisibility preordering.)
--   
--   Note: Since for signed fixed-width integer types, <tt><a>abs</a>
--   <a>minBound</a> &lt; 0</tt>, the result may be negative if one of the
--   arguments is <tt><a>minBound</a></tt> (and necessarily is if the other
--   is <tt>0</tt> or <tt><a>minBound</a></tt>) for such types.
gcd :: Integral a => a -> a -> a

-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^

-- | utility function that surrounds the inner show function with
--   parentheses when the <a>Bool</a> parameter is <a>True</a>.
showParen :: Bool -> ShowS -> ShowS

-- | utility function converting a <a>String</a> to a show function that
--   simply prepends the string unchanged.
showString :: String -> ShowS

-- | utility function converting a <a>Char</a> to a show function that
--   simply prepends the character unchanged.
showChar :: Char -> ShowS

-- | equivalent to <a>showsPrec</a> with a precedence of 0.
shows :: Show a => a -> ShowS

-- | The <tt>shows</tt> functions return a function that prepends the
--   output <a>String</a> to an existing <a>String</a>. This allows
--   constant-time concatenation of results using function composition.
type ShowS = String -> String

-- | &lt;math&gt;. <a>lookup</a> <tt>key assocs</tt> looks up a key in an
--   association list.
--   
--   <pre>
--   &gt;&gt;&gt; lookup 2 [(1, "first"), (2, "second"), (3, "third")]
--   Just "second"
--   </pre>
lookup :: Eq a => a -> [(a, b)] -> Maybe b

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: (a -> Bool) -> [a] -> ([a], [a])

-- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>,
--   returns a tuple where first element is longest prefix (possibly empty)
--   of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element
--   is the remainder of the list:
--   
--   <pre>
--   span (&lt; 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
--   span (&lt; 9) [1,2,3] == ([1,2,3],[])
--   span (&lt; 0) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs,
--   <a>dropWhile</a> p xs)</tt>
span :: (a -> Bool) -> [a] -> ([a], [a])

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: (a -> Bool) -> [a] -> [a]

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: (a -> Bool) -> [a] -> [a]

-- | <a>cycle</a> ties a finite list into a circular one, or equivalently,
--   the infinite repetition of the original list. It is the identity on
--   infinite lists.
cycle :: [a] -> [a]

-- | The <a>maybe</a> function takes a default value, a function, and a
--   <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
--   function returns the default value. Otherwise, it applies the function
--   to the value inside the <a>Just</a> and returns the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd Nothing
--   False
--   </pre>
--   
--   Read an integer from a string using <a>readMaybe</a>. If we succeed,
--   return twice the integer; that is, apply <tt>(*2)</tt> to it. If
--   instead we fail to parse an integer, return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "5")
--   10
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "")
--   0
--   </pre>
--   
--   Apply <a>show</a> to a <tt>Maybe Int</tt>. If we have <tt>Just n</tt>,
--   we want to show the underlying <a>Int</a> <tt>n</tt>. But if we have
--   <a>Nothing</a>, we return the empty string instead of (for example)
--   "Nothing":
--   
--   <pre>
--   &gt;&gt;&gt; maybe "" show (Just 5)
--   "5"
--   
--   &gt;&gt;&gt; maybe "" show Nothing
--   ""
--   </pre>
maybe :: b -> (a -> b) -> Maybe a -> b

-- | An infix synonym for <a>fmap</a>.
--   
--   The name of this operator is an allusion to <a>$</a>. Note the
--   similarities between their types:
--   
--   <pre>
--    ($)  ::              (a -&gt; b) -&gt;   a -&gt;   b
--   (&lt;$&gt;) :: Functor f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   </pre>
--   
--   Whereas <a>$</a> is function application, <a>&lt;$&gt;</a> is function
--   application lifted over a <a>Functor</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Convert from a <tt><a>Maybe</a> <a>Int</a></tt> to a <tt><a>Maybe</a>
--   <a>String</a></tt> using <a>show</a>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Nothing
--   Nothing
--   
--   &gt;&gt;&gt; show &lt;$&gt; Just 3
--   Just "3"
--   </pre>
--   
--   Convert from an <tt><a>Either</a> <a>Int</a> <a>Int</a></tt> to an
--   <tt><a>Either</a> <a>Int</a></tt> <a>String</a> using <a>show</a>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Left 17
--   Left 17
--   
--   &gt;&gt;&gt; show &lt;$&gt; Right 17
--   Right "17"
--   </pre>
--   
--   Double each element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; (*2) &lt;$&gt; [1,2,3]
--   [2,4,6]
--   </pre>
--   
--   Apply <a>even</a> to the second element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; even &lt;$&gt; (2,2)
--   (2,True)
--   </pre>
(<$>) :: Functor f => (a -> b) -> f a -> f b
infixl 4 <$>

-- | <a>uncurry</a> converts a curried function to a function on pairs.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry (+) (1,2)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry ($) (show, 1)
--   "1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--   </pre>
uncurry :: (a -> b -> c) -> (a, b) -> c

-- | <a>curry</a> converts an uncurried function to a curried function.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; curry fst 1 2
--   1
--   </pre>
curry :: ((a, b) -> c) -> a -> b -> c

-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
--   
--   Because <tt>-</tt> is treated specially in the Haskell grammar,
--   <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
--   prefix negation. However, <tt>(<a>subtract</a></tt>
--   <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a

-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is
--   usually used as an infix operator, and its typing forces its first
--   argument (which is usually overloaded) to have the same type as the
--   second.
asTypeOf :: a -> a -> a

-- | <tt><a>until</a> p f</tt> yields the result of applying <tt>f</tt>
--   until <tt>p</tt> holds.
until :: (a -> Bool) -> (a -> a) -> a -> a

-- | Strict (call-by-value) application operator. It takes a function and
--   an argument, evaluates the argument to weak head normal form (WHNF),
--   then calls the function with that value.
($!) :: forall (r :: RuntimeRep) a (b :: TYPE r). (a -> b) -> a -> b
infixr 0 $!

-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
--   order of <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; flip (++) "hello" "world"
--   "worldhello"
--   </pre>
flip :: (a -> b -> c) -> b -> a -> c

-- | Function composition.
(.) :: (b -> c) -> (a -> b) -> a -> c
infixr 9 .

-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
--   all inputs.
--   
--   <pre>
--   &gt;&gt;&gt; const 42 "hello"
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (const 42) [0..3]
--   [42,42,42,42]
--   </pre>
const :: a -> b -> a

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => (a -> m b) -> m a -> m b
infixr 1 =<<

-- | A variant of <a>error</a> that does not produce a stack trace.
errorWithoutStackTrace :: forall (r :: RuntimeRep) (a :: TYPE r). [Char] -> a

-- | <a>error</a> stops execution and displays an error message.
error :: forall (r :: RuntimeRep) (a :: TYPE r). HasCallStack => [Char] -> a
(&&) :: Bool -> Bool -> Bool
infixr 3 &&
(||) :: Bool -> Bool -> Bool
infixr 2 ||
not :: Bool -> Bool


-- | Hidden arguments
module Clash.Hidden

-- | A value reflected to, or <i>hiding</i> at, the <i>Constraint</i> level
--   
--   e.g. a function:
--   
--   <pre>
--   f :: Hidden "foo" Int
--     =&gt; Bool
--     -&gt; Int
--   f = ...
--   </pre>
--   
--   has a <i>normal</i> argument of type <tt>Bool</tt>, and a
--   <i>hidden</i> argument called "foo" of type <tt>Int</tt>. In order to
--   apply the <tt>Int</tt> argument we have to use the <a>expose</a>
--   function, so that the <i>hidden</i> argument becomes a normal argument
--   again.
--   
--   <h3><b>Original implementation</b></h3>
--   
--   <a>Hidden</a> used to be implemented by:
--   
--   <pre>
--   class Hidden (x :: Symbol) a | x -&gt; a where
--     hidden :: a
--   </pre>
--   
--   which is equivalent to <i>IP</i>, except that <i>IP</i> has magic
--   inference rules bestowed by GHC so that there's never any ambiguity.
--   We need these magic inference rules so we don't end up in type
--   inference absurdity where asking for the type of an type-annotated
--   value results in a <i>no-instance-in-scope</i> error.
type Hidden (x :: Symbol) a = IP x a

-- | Expose a <a>Hidden</a> argument so that it can be applied normally,
--   e.g.
--   
--   <pre>
--   f :: Hidden "foo" Int
--     =&gt; Bool
--     -&gt; Int
--   f = ...
--   
--   g :: Int -&gt; Bool -&gt; Int
--   g = <a>expose</a> @"foo" f
--   </pre>
expose :: forall x a r. (Hidden x a => r) -> a -> r

-- | Using <i>-XOverloadedLabels</i> and <i>-XRebindableSyntax</i>, we can
--   turn any value into a <i>hidden</i> argument using the <tt>#foo</tt>
--   notation, e.g.:
--   
--   <pre>
--   f :: Int -&gt; Bool -&gt; Int
--   f = ...
--   
--   g :: Hidden "foo" Bool
--     =&gt; Int -&gt; Int
--   g i = f i #foo
--   </pre>
fromLabel :: forall x a. Hidden x a => a


-- | Add inline documentation to types:
--   
--   <pre>
--   fifo
--     :: Clock dom
--     -&gt; Reset dom
--     -&gt; SNat addrSize
--     -&gt; "read request" ::: Signal dom Bool
--     -&gt; "write request" ::: Signal dom (Maybe (BitVector dataSize))
--     -&gt; ( "q"     ::: Signal dom (BitVector dataSize)
--        , "full"  ::: Signal dom Bool
--        , "empty" ::: Signal dom Bool
--        )
--   </pre>
--   
--   which can subsequently be inspected in the interactive environment:
--   
--   <pre>
--   &gt;&gt;&gt; import Clash.Explicit.Prelude
--   
--   &gt;&gt;&gt; :t fifo @System
--   fifo @System
--     :: Clock System
--        -&gt; Reset System
--        -&gt; SNat addrSize
--        -&gt; ("read request" ::: Signal System Bool)
--        -&gt; ("write request" ::: Signal System (Maybe (BitVector dataSize)))
--        -&gt; ("q" ::: Signal System (BitVector dataSize),
--            "full" ::: Signal System Bool, "empty" ::: Signal System Bool)
--   </pre>
module Clash.NamedTypes

-- | Annotate a type with a name
type (name :: k) ::: a = a


module Clash.Promoted.Symbol

-- | Singleton value for a type-level string <tt>s</tt>
data SSymbol (s :: Symbol)
[SSymbol] :: KnownSymbol s => SSymbol s

-- | Create a singleton symbol literal <tt><a>SSymbol</a> s</tt> from a
--   proxy for <i>s</i>
ssymbolProxy :: KnownSymbol s => proxy s -> SSymbol s

-- | Reify the type-level <a>Symbol</a> <tt>s</tt> to it's term-level
--   <a>String</a> representation.
ssymbolToString :: SSymbol s -> String
instance GHC.TypeLits.KnownSymbol s => Language.Haskell.TH.Syntax.Lift (Clash.Promoted.Symbol.SSymbol s)
instance GHC.Show.Show (Clash.Promoted.Symbol.SSymbol s)


-- | Control naming and deduplication in the generated HDL code. Explicitly
--   nameable things include:
--   
--   <ul>
--   <li>Component (VHDL) / module ((System)Verilog) instances</li>
--   <li>Registers</li>
--   <li>Terms</li>
--   </ul>
--   
--   Refer to <a>Clash.Annotations.TopEntity</a> for controlling naming of
--   entities (VHDL) / modules ((System)Verilog) and their ports.
module Clash.Magic

-- | Prefix instance and register names with the given <a>Symbol</a>
prefixName :: forall (name :: Symbol) a. a -> name ::: a

-- | Suffix instance and register names with the given <a>Symbol</a>
suffixName :: forall (name :: Symbol) a. a -> name ::: a

-- | Suffix instance and register names with the given <a>Symbol</a>, but
--   add it in front of other suffixes.
--   
--   When you write
--   
--   <pre>
--   suffixName @"A" (suffixName @"B" f))
--   </pre>
--   
--   you get register and instance names inside <i>f</i> with the suffix:
--   "_B_A"
--   
--   However, if you want them in the other order you can write:
--   
--   <pre>
--   suffixNameP @"A" (suffixName @"B" f))
--   </pre>
--   
--   so that names inside <i>f</i> will have the suffix "_A_B"
suffixNameP :: forall (name :: Symbol) a. a -> name ::: a

-- | Suffix instance and register names with the given <a>Nat</a>
suffixNameFromNat :: forall (name :: Nat) a. a -> name ::: a

-- | Suffix instance and register names with the given <a>Nat</a>, but add
--   it in front of other suffixes.
--   
--   When you write
--   
--   <pre>
--   suffixNameNat @1 (suffixName @"B" f))
--   </pre>
--   
--   you get register and instance names inside <i>f</i> with the suffix:
--   "_B_1"
--   
--   However, if you want them in the other order you can write:
--   
--   <pre>
--   suffixNameNatP @1 (suffixName @"B" f))
--   </pre>
--   
--   so that names inside <i>f</i> will have the suffix "_1_B"
suffixNameFromNatP :: forall (name :: Nat) a. a -> name ::: a

-- | Name the instance or register with the given <a>Symbol</a>, instead of
--   using an auto-generated name. Pre- and suffixes annotated with
--   <a>prefixName</a> and <a>suffixName</a> will be added to both
--   instances and registers named with <a>setName</a> and instances and
--   registers that are auto-named.
setName :: forall (name :: Symbol) a. a -> name ::: a

-- | Name a given term, such as one of type <a>Signal</a>, using the given
--   <a>SSymbol</a>. Results in a declaration with the name used as the
--   identifier in the generated HDL code.
--   
--   Example usage:
--   
--   <pre>
--   nameHint (SSymbol @"identifier") term
--   </pre>
--   
--   <b>NB</b>: The given name should be considered a hint as it may be
--   expanded, e.g. if it collides with existing identifiers.
nameHint :: SSymbol sym -> a -> a

-- | Force deduplication, i.e. share a function or operator between
--   multiple branches.
--   
--   By default Clash converts
--   
--   <pre>
--   case x of
--     A -&gt; 3 * y
--     B -&gt; x * x
--   </pre>
--   
--   to
--   
--   <pre>
--   let f_arg0 = case x of {A -&gt; 3; _ -&gt; x}
--       f_arg1 = case x of {A -&gt; y; _ -&gt; x}
--       f_out  = f_arg0 * f_arg1
--   in  case x of
--         A -&gt; f_out
--         B -&gt; f_out
--   </pre>
--   
--   However, it won't do this for:
--   
--   <pre>
--   case x of
--     A -&gt; 3 + y
--     B -&gt; x + x
--   </pre>
--   
--   Because according to the internal heuristics the multiplexer
--   introduced for the deduplication are more expensive than the addition.
--   This might not be the case for your particular platform.
--   
--   In these cases you can force Clash to deduplicate by:
--   
--   <pre>
--   case x of
--     A -&gt; <a>deDup</a> (3 + y)
--     B -&gt; <a>deDup</a> (x + x)
--   </pre>
deDup :: forall a. a -> a

-- | Do not deduplicate, i.e. <i>keep</i>, an applied function inside a
--   case-alternative; do not try to share the function between multiple
--   branches.
--   
--   By default Clash converts
--   
--   <pre>
--   case x of
--     A -&gt; f 3 y
--     B -&gt; f x x
--     C -&gt; h x
--   </pre>
--   
--   to
--   
--   <pre>
--   let f_arg0 = case x of {A -&gt; 3; _ -&gt; x}
--       f_arg1 = case x of {A -&gt; y; _ -&gt; x}
--       f_out  = f f_arg0 f_arg1
--   in  case x of
--         A -&gt; f_out
--         B -&gt; f_out
--         C -&gt; h x
--   </pre>
--   
--   i.e. it deduplicates functions (and operators such as multiplication)
--   between case-alternatives to save on area. This comes at the cost of
--   multiplexing the arguments for the deduplicated function.
--   
--   There are two reasons you would want to stop Clash from doing this:
--   
--   <ol>
--   <li>The deduplicated function is in the critical path, and the
--   addition of the multiplexers further increased the propagation
--   delay.</li>
--   <li>Clash's heuristics were off, and the addition of the multiplexers
--   actually made the final circuit larger instead of smaller.</li>
--   </ol>
--   
--   In these cases you want to tell Clash not to deduplicate:
--   
--   <pre>
--   case x of
--     A -&gt; <a>noDeDup</a> f 3 y
--     B -&gt; f x x
--     C -&gt; h x
--   </pre>
--   
--   Where the application of <i>f</i> in the <i>A</i>-alternative is now
--   explicitly not deduplicated, and given that the <i>f</i> in the
--   B-alternative is the only remaining application of <i>f</i> in the
--   case-expression it is also not deduplicated.
--   
--   Note that if the <i>C</i>-alternative also had an application of
--   <i>f</i>, then the applications of <i>f</i> in the <i>B</i>- and
--   <i>C</i>-alternatives would have been deduplicated; i.e. the final
--   circuit would have had two application of <i>f</i>.
noDeDup :: forall a. a -> a

-- | <a>True</a> in Haskell/Clash simulation. Replaced by <a>False</a> when
--   generating HDL.
clashSimulation :: Bool

-- | A container for data you only want to have around during simulation
--   and is ignored during synthesis. Useful for carrying around things
--   such as:
--   
--   <ul>
--   <li>A map of simulation/vcd traces</li>
--   <li>Co-simulation state or meta-data</li>
--   <li>etc.</li>
--   </ul>
data SimOnly a
SimOnly :: a -> SimOnly a

-- | Same as <a>error</a> but will make HDL generation fail if included in
--   the final circuit.
--   
--   This is useful for the error case of static assertions.
--   
--   Note that the error message needs to be a literal, and during HDL
--   generation the error message does not include a stack trace, so it had
--   better be descriptive.
clashCompileError :: forall a. HasCallStack => String -> a
instance Data.Traversable.Traversable Clash.Magic.SimOnly
instance Data.Foldable.Foldable Clash.Magic.SimOnly
instance GHC.Classes.Ord a => GHC.Classes.Ord (Clash.Magic.SimOnly a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Magic.SimOnly a)
instance GHC.Base.Functor Clash.Magic.SimOnly
instance GHC.Base.Applicative Clash.Magic.SimOnly
instance GHC.Base.Monad Clash.Magic.SimOnly
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Clash.Magic.SimOnly a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Clash.Magic.SimOnly a)


module Clash.Class.Resize

-- | Coerce a value to be represented by a different number of bits
class Resize (f :: Nat -> Type)

-- | A sign-preserving resize operation
--   
--   <ul>
--   <li>For signed datatypes: Increasing the size of the number replicates
--   the sign bit to the left. Truncating a number to length L keeps the
--   sign bit and the rightmost L-1 bits.</li>
--   <li>For unsigned datatypes: Increasing the size of the number extends
--   with zeros to the left. Truncating a number of length N to a length L
--   just removes the left (most significant) N-L bits.</li>
--   </ul>
resize :: (Resize f, KnownNat a, KnownNat b) => f a -> f b

-- | Perform a <a>zeroExtend</a> for unsigned datatypes, and
--   <a>signExtend</a> for a signed datatypes
extend :: (Resize f, KnownNat a, KnownNat b) => f a -> f (b + a)

-- | Add extra zero bits in front of the MSB
zeroExtend :: (Resize f, KnownNat a, KnownNat b) => f a -> f (b + a)

-- | Add extra sign bits in front of the MSB
signExtend :: (Resize f, KnownNat a, KnownNat b) => f a -> f (b + a)

-- | Remove bits from the MSB
truncateB :: (Resize f, KnownNat a) => f (a + b) -> f a

-- | Like <a>resize</a>, but errors if <i>f a</i> is out of bounds for <i>f
--   b</i>. Useful when you "know" <i>f a</i> can't be out of bounds, but
--   would like to have your assumptions checked.
--   
--   <b>NB</b>: Check only affects simulation. I.e., no checks will be
--   inserted into the generated HDL
checkedResize :: forall a b f. (HasCallStack, Resize f, KnownNat a, Integral (f a), KnownNat b, Integral (f b), Bounded (f b)) => f a -> f b

-- | Like <a>fromIntegral</a>, but errors if <i>a</i> is out of bounds for
--   <i>b</i>. Useful when you "know" <i>a</i> can't be out of bounds, but
--   would like to have your assumptions checked.
--   
--   <ul>
--   <li><b>NB</b>: Check only affects simulation. I.e., no checks will be
--   inserted into the generated HDL</li>
--   <li><b>NB</b>: <a>fromIntegral</a> is not well suited for Clash as it
--   will go through <a>Integer</a> which is arbitrarily bounded in HDL.
--   Instead use <a>bitCoerce</a> and the <a>Resize</a> class.</li>
--   </ul>
checkedFromIntegral :: forall a b. HasCallStack => (Integral a, Integral b, Bounded b) => a -> b

-- | Like <a>truncateB</a>, but errors if <i>f (a + b)</i> is out of bounds
--   for <i>f a</i>. Useful when you "know" <i>f (a + b)</i> can't be out
--   of bounds, but would like to have your assumptions checked.
--   
--   <b>NB</b>: Check only affects simulation. I.e., no checks will be
--   inserted into the generated HDL
checkedTruncateB :: forall a b f. (HasCallStack, Resize f, KnownNat b, Integral (f (a + b)), KnownNat a, Integral (f a), Bounded (f a)) => f (a + b) -> f a


-- | This module contains code from:
--   <a>https://hackage.haskell.org/package/mod</a> and has the following
--   license:
--   
--   Copyright (c) 2019 Andrew Lelechenko
--   
--   Permission is hereby granted, free of charge, to any person obtaining
--   a copy of this software and associated documentation files (the
--   <a>Software</a>), to deal in the Software without restriction,
--   including without limitation the rights to use, copy, modify, merge,
--   publish, distribute, sublicense, and/or sell copies of the Software,
--   and to permit persons to whom the Software is furnished to do so,
--   subject to the following conditions:
--   
--   The above copyright notice and this permission notice shall be
--   included in all copies or substantial portions of the Software.
--   
--   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
--   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
--   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
--   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
--   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
--   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
--   SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
module Clash.Sized.Internal.Mod

-- | modular subtraction
subMod :: Natural -> Natural -> Natural -> Natural

-- | modular addition
addMod :: Natural -> Natural -> Natural -> Natural

-- | modular multiplication
mulMod :: Natural -> Natural -> Natural -> Natural

-- | modular multiplication for powers of 2, takes a mask instead of a
--   wrap-around point
mulMod2 :: Natural -> Natural -> Natural -> Natural

-- | modular negations
negateMod :: Natural -> Natural -> Natural

-- | Given a size in bits, return a function that complements the bits in a
--   <a>Natural</a> up to that size.
complementMod :: Integer -> Natural -> Natural

-- | Keep all the bits up to a certain size
maskMod :: Integer -> Natural -> Natural
bigNatToNat :: BigNat -> Natural
subIfGe :: BigNat -> BigNat -> Natural
brokenInvariant :: a


-- | <a>XException</a>: An exception for uninitialized values
--   
--   <pre>
--   &gt;&gt;&gt; show (errorX "undefined" :: Integer, 4 :: Int)
--   "(*** Exception: X: undefined
--   CallStack (from HasCallStack):
--   ...
--   
--   &gt;&gt;&gt; showX (errorX "undefined" :: Integer, 4 :: Int)
--   "(undefined,4)"
--   </pre>
module Clash.XException.Internal

-- | An exception representing an "uninitialized" value.
newtype XException
XException :: String -> XException

-- | Like <a>shows</a>, but values that normally throw an <a>XException</a>
--   are converted to <tt>undefined</tt>, instead of error'ing out with an
--   exception.
showsX :: ShowX a => a -> ShowS

-- | Use when you want to create a <a>ShowX</a> instance where:
--   
--   <ul>
--   <li>There is no <a>Generic</a> instance for your data type</li>
--   <li>The <a>Generic</a> derived ShowX method would traverse into the
--   (hidden) implementation details of your data type, and you just want
--   to show the entire value as <tt>undefined</tt>.</li>
--   </ul>
--   
--   Can be used like:
--   
--   <pre>
--   data T = ...
--   
--   instance Show T where ...
--   
--   instance ShowX T where
--     showsPrecX = showsPrecXWith showsPrec
--   </pre>
showsPrecXWith :: (Int -> a -> ShowS) -> Int -> a -> ShowS
showXWith :: (a -> ShowS) -> a -> ShowS
class GShowX f
gshowsPrecX :: GShowX f => ShowType -> Int -> f a -> ShowS
isNullary :: GShowX f => f a -> Bool
class GDeepErrorX f
gDeepErrorX :: (GDeepErrorX f, HasCallStack) => String -> f a
class GHasUndefined f
gHasUndefined :: GHasUndefined f => f a -> Bool
class GEnsureSpine f
gEnsureSpine :: GEnsureSpine f => f a -> f a

-- | Hidden internal type-class. Adds a generic implementation for the
--   "NFData" part of <a>NFDataX</a>
class GNFDataX arity f
grnfX :: GNFDataX arity f => RnfArgs arity a -> f a -> ()
data Zero
data One
data ShowType
Rec :: ShowType
Tup :: ShowType
Pref :: ShowType
Inf :: String -> ShowType
data RnfArgs arity a
[RnfArgs0] :: RnfArgs Zero a
[RnfArgs1] :: (a -> ()) -> RnfArgs One a

-- | A class of functors that can be fully evaluated, according to
--   semantics of NFDataX.
class NFDataX1 f

-- | <a>liftRnfX</a> should reduce its argument to normal form (that is,
--   fully evaluate all sub-components), given an argument to reduce
--   <tt>a</tt> arguments, and then return <tt>()</tt>.
--   
--   See <a>rnfX</a> for the generic deriving.
liftRnfX :: NFDataX1 f => (a -> ()) -> f a -> ()

-- | <a>liftRnfX</a> should reduce its argument to normal form (that is,
--   fully evaluate all sub-components), given an argument to reduce
--   <tt>a</tt> arguments, and then return <tt>()</tt>.
--   
--   See <a>rnfX</a> for the generic deriving.
liftRnfX :: (NFDataX1 f, Generic1 f, GNFDataX One (Rep1 f)) => (a -> ()) -> f a -> ()
showListX__ :: (a -> ShowS) -> [a] -> ShowS
genericShowsPrecX :: (Generic a, GShowX (Rep a)) => Int -> a -> ShowS
instance Clash.XException.Internal.GDeepErrorX GHC.Generics.V1
instance Clash.XException.Internal.GDeepErrorX GHC.Generics.U1
instance Clash.XException.Internal.GDeepErrorX a => Clash.XException.Internal.GDeepErrorX (GHC.Generics.M1 m d a)
instance (Clash.XException.Internal.GDeepErrorX f, Clash.XException.Internal.GDeepErrorX g) => Clash.XException.Internal.GDeepErrorX (f GHC.Generics.:*: g)
instance Clash.XException.NFDataX c => Clash.XException.Internal.GDeepErrorX (GHC.Generics.K1 i c)
instance Clash.XException.Internal.GDeepErrorX (f GHC.Generics.:+: g)
instance Clash.XException.Internal.GHasUndefined GHC.Generics.U1
instance Clash.XException.NFDataX a => Clash.XException.Internal.GHasUndefined (GHC.Generics.K1 i a)
instance Clash.XException.Internal.GHasUndefined a => Clash.XException.Internal.GHasUndefined (GHC.Generics.M1 i c a)
instance (Clash.XException.Internal.GHasUndefined a, Clash.XException.Internal.GHasUndefined b) => Clash.XException.Internal.GHasUndefined (a GHC.Generics.:*: b)
instance (Clash.XException.Internal.GHasUndefined a, Clash.XException.Internal.GHasUndefined b) => Clash.XException.Internal.GHasUndefined (a GHC.Generics.:+: b)
instance Clash.XException.Internal.GHasUndefined GHC.Generics.V1
instance Clash.XException.Internal.NFDataX1 f => Clash.XException.Internal.GNFDataX Clash.XException.Internal.One (GHC.Generics.Rec1 f)
instance (Clash.XException.Internal.NFDataX1 f, Clash.XException.Internal.GNFDataX Clash.XException.Internal.One g) => Clash.XException.Internal.GNFDataX Clash.XException.Internal.One (f GHC.Generics.:.: g)
instance Clash.XException.Internal.GEnsureSpine GHC.Generics.U1
instance Clash.XException.NFDataX a => Clash.XException.Internal.GEnsureSpine (GHC.Generics.K1 i a)
instance Clash.XException.Internal.GEnsureSpine a => Clash.XException.Internal.GEnsureSpine (GHC.Generics.M1 i c a)
instance (Clash.XException.Internal.GEnsureSpine a, Clash.XException.Internal.GEnsureSpine b) => Clash.XException.Internal.GEnsureSpine (a GHC.Generics.:*: b)
instance (Clash.XException.Internal.GEnsureSpine a, Clash.XException.Internal.GEnsureSpine b) => Clash.XException.Internal.GEnsureSpine (a GHC.Generics.:+: b)
instance Clash.XException.Internal.GEnsureSpine GHC.Generics.V1
instance Clash.XException.Internal.GNFDataX arity GHC.Generics.V1
instance Clash.XException.Internal.GNFDataX arity GHC.Generics.U1
instance Clash.XException.NFDataX a => Clash.XException.Internal.GNFDataX arity (GHC.Generics.K1 i a)
instance Clash.XException.Internal.GNFDataX arity a => Clash.XException.Internal.GNFDataX arity (GHC.Generics.M1 i c a)
instance (Clash.XException.Internal.GNFDataX arity a, Clash.XException.Internal.GNFDataX arity b) => Clash.XException.Internal.GNFDataX arity (a GHC.Generics.:*: b)
instance (Clash.XException.Internal.GNFDataX arity a, Clash.XException.Internal.GNFDataX arity b) => Clash.XException.Internal.GNFDataX arity (a GHC.Generics.:+: b)
instance Clash.XException.Internal.GNFDataX Clash.XException.Internal.One GHC.Generics.Par1
instance Clash.XException.Internal.GShowX GHC.Generics.U1
instance Clash.XException.ShowX c => Clash.XException.Internal.GShowX (GHC.Generics.K1 i c)
instance (Clash.XException.Internal.GShowX a, GHC.Generics.Constructor c) => Clash.XException.Internal.GShowX (GHC.Generics.M1 GHC.Generics.C c a)
instance (GHC.Generics.Selector s, Clash.XException.Internal.GShowX a) => Clash.XException.Internal.GShowX (GHC.Generics.M1 GHC.Generics.S s a)
instance Clash.XException.Internal.GShowX a => Clash.XException.Internal.GShowX (GHC.Generics.M1 GHC.Generics.D d a)
instance (Clash.XException.Internal.GShowX a, Clash.XException.Internal.GShowX b) => Clash.XException.Internal.GShowX (a GHC.Generics.:+: b)
instance (Clash.XException.Internal.GShowX a, Clash.XException.Internal.GShowX b) => Clash.XException.Internal.GShowX (a GHC.Generics.:*: b)
instance Clash.XException.Internal.GShowX GHC.Generics.UChar
instance Clash.XException.Internal.GShowX GHC.Generics.UDouble
instance Clash.XException.Internal.GShowX GHC.Generics.UFloat
instance Clash.XException.Internal.GShowX GHC.Generics.UInt
instance Clash.XException.Internal.GShowX GHC.Generics.UWord
instance GHC.Show.Show Clash.XException.Internal.XException
instance GHC.Exception.Type.Exception Clash.XException.Internal.XException


module Clash.XException.TH

-- | Creates instances of ShowX for all tuple sizes listed. See
--   <a>mkShowXTupleInstance</a> for more information.
mkShowXTupleInstances :: [Int] -> Q [Dec]
mkNFDataXTupleInstances :: [Int] -> Q [Dec]

-- | Creates an instance of the form:
--   
--   instance (ShowX a0, ShowX a1) =&gt; ShowX (a0, a1)
--   
--   With <i>n</i> number of variables.
mkShowXTupleInstance :: Int -> Dec


-- | <a>XException</a>: An exception for uninitialized values
--   
--   <pre>
--   &gt;&gt;&gt; show (errorX "undefined" :: Integer, 4 :: Int)
--   "(*** Exception: X: undefined
--   CallStack (from HasCallStack):
--   ...
--   
--   &gt;&gt;&gt; showX (errorX "undefined" :: Integer, 4 :: Int)
--   "(undefined,4)"
--   </pre>
module Clash.XException

-- | An exception representing an "uninitialized" value.
newtype XException
XException :: String -> XException

-- | Like <a>error</a>, but throwing an <a>XException</a> instead of an
--   <a>ErrorCall</a>
--   
--   The <a>ShowX</a> methods print these error-values as
--   <tt>undefined</tt>; instead of error'ing out with an exception.
errorX :: HasCallStack => String -> a

-- | Evaluate a value to WHNF, returning <tt><a>Left</a> msg</tt> if is a
--   <a>XException</a>.
--   
--   <pre>
--   isX 42                  = Right 42
--   isX (XException msg)    = Left msg
--   isX (3, XException msg) = Right (3, XException msg)
--   isX (3, _|_)            = Right (3, _|_)
--   isX _|_                 = _|_
--   </pre>
isX :: a -> Either String a

-- | Fully evaluate a value, returning <tt><a>Left</a> msg</tt> if it
--   throws <a>XException</a>. If you want to determine if a value contains
--   undefined parts, use <a>hasUndefined</a> instead.
--   
--   <pre>
--   hasX 42                    = Right 42
--   hasX (XException msg)      = Left msg
--   hasX (3, XException msg)   = Left msg
--   hasX (XException msg, _|_) = _|_
--   hasX (_|_, XException msg) = _|_
--   hasX (3, _|_)              = _|_
--   hasX _|_                   = _|_
--   </pre>
--   
--   If a data structure contains multiple <a>XException</a>s, the "first"
--   message is picked according to the implementation of <a>rnfX</a>.
hasX :: (NFData a, NFDataX a) => a -> Either String a

-- | Evaluate a value to WHNF, returning <a>Nothing</a> if it throws
--   <a>XException</a>.
--   
--   <pre>
--   maybeIsX 42                  = Just 42
--   maybeIsX (XException msg)    = Nothing
--   maybeIsX (3, XException msg) = Just (3, XException msg)
--   maybeIsX (3, _|_)            = Just (3, _|_)
--   maybeIsX _|_                 = _|_
--   </pre>
maybeIsX :: a -> Maybe a

-- | Fully evaluate a value, returning <a>Nothing</a> if it throws
--   <a>XException</a>. Note that non-<a>XException</a> errors take
--   precedence over <a>XException</a> ones.
--   
--   <pre>
--   maybeHasX 42                    = Just 42
--   maybeHasX (XException msg)      = Nothing
--   maybeHasX (3, XException msg)   = Nothing
--   maybeHasX (XException msg, _|_) = _|_
--   maybeHasX (_|_, XException msg) = _|_
--   maybeHasX (3, _|_)              = _|_
--   maybeHasX _|_                   = _|_
--   </pre>
maybeHasX :: (NFData a, NFDataX a) => a -> Maybe a

-- | Same as <a>fromJust</a>, but returns a bottom/undefined value that
--   other Clash constructs are aware of.
fromJustX :: (HasCallStack, NFDataX a) => Maybe a -> a

-- | Call to <a>errorX</a> with default string
undefined :: HasCallStack => a

-- | Convert <a>XException</a> to <a>ErrorCall</a>
--   
--   This is useful when tracking the source of <a>XException</a> that gets
--   eaten up by <a>pack</a> inside of your circuit; since <a>pack</a>
--   translates <a>XException</a> into undefined bits.
--   
--   So for example if you have some large function f:
--   
--   <pre>
--   f a b = ... pack a ... pack b ...
--   </pre>
--   
--   Where it is basically an error if either <i>a</i> or <i>b</i> ever
--   throws an <a>XException</a>, and so you want that to be reported the
--   moment <i>a</i> or <i>b</i> is used, instead of it being thrown when
--   evaluating the result of <i>f</i>, then do:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns #-}
--   f (xToErrorCtx "a is X" -&gt; a) (xToErrorCtx "b is X" -&gt; b) = ...
--   </pre>
--   
--   Where we pass an extra string, for context, to know which argument
--   evaluated to an <a>XException</a>. We can also use BangPatterns to
--   report the potential <a>XException</a> being thrown by <i>a</i> or
--   <i>b</i> even earlier, i.e. when <i>f</i> is applied:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns, BangPatterns #-}
--   f (xToErrorCtx "a is X" -&gt; !a) (xToErrorCtx "b is X" -&gt; !b) = ...
--   </pre>
--   
--   <b>NB</b>: Fully synthesizable, so doesn't have to be removed before
--   synthesis
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :set -XViewPatterns -XDataKinds
--   
--   &gt;&gt;&gt; import Clash.Sized.BitVector
--   
--   &gt;&gt;&gt; import GHC.Stack
--   
--   &gt;&gt;&gt; :{
--   let h, h' :: Bit -&gt; BitVector 8 -&gt; BitVector 8
--       h (xToErrorCtx "a is X" -&gt; a) (xToErrorCtx "b is X" -&gt; b) = slice d7 d0 (pack a ++# b)
--       h' a b = slice d7 d0 (pack a ++# b)
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; h' (errorX "QQ") 3
--   0b0000_0011
--   
--   &gt;&gt;&gt; h (errorX "QQ") 3
--   *** Exception: a is X
--   X: QQ
--   CallStack (from HasCallStack):
--     errorX, called at ...
--   </pre>
xToErrorCtx :: String -> a -> a

-- | Convert <a>XException</a> to <a>ErrorCall</a>
--   
--   This is useful when tracking the source of <a>XException</a> that gets
--   eaten up by <a>pack</a> inside of your circuit; since <a>pack</a>
--   translates <a>XException</a> into undefined bits.
--   
--   So for example if you have some large function f:
--   
--   <pre>
--   f a b = ... pack a ... pack b ...
--   </pre>
--   
--   Where it is basically an error if either <i>a</i> or <i>b</i> ever
--   throws an <a>XException</a>, and so you want that to be reported the
--   moment <i>a</i> or <i>b</i> is used, instead of it being thrown when
--   evaluating the result of <i>f</i>, then do:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns #-}
--   f (xToError -&gt; a) (xToError -&gt; b) = ...
--   </pre>
--   
--   Unlike <a>xToErrorCtx</a>, where we have an extra String argument to
--   distinguish one call to <a>xToError</a> to the other, <a>xToError</a>
--   will use the <a>CallStack</a> mechanism to aid the user in
--   distinguishing different call to <a>xToError</a>. We can also use
--   BangPatterns to report the potential <a>XException</a> being thrown by
--   <i>a</i> or <i>b</i> even earlier, i.e. when <i>f</i> is applied:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns, BangPatterns #-}
--   f (xToError -&gt; !a) (xToError -&gt; !b) = ...
--   </pre>
--   
--   <b>NB</b>: Fully synthesizable, so doesn't have to be removed before
--   synthesis
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :set -XViewPatterns -XDataKinds
--   
--   &gt;&gt;&gt; import Clash.Sized.BitVector
--   
--   &gt;&gt;&gt; import GHC.Stack
--   
--   &gt;&gt;&gt; :{
--   let f, g, h, h' :: HasCallStack =&gt; Bit -&gt; BitVector 8 -&gt; BitVector 8
--       f = g
--       g = h
--       h (xToError -&gt; a) (xToError -&gt; b) = slice d7 d0 (pack a ++# b)
--       h' a b = slice d7 d0 (pack a ++# b)
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; h' (errorX "QQ") 3
--   0b0000_0011
--   
--   &gt;&gt;&gt; f (errorX "QQ") 3
--   *** Exception: CallStack (from HasCallStack):
--     xToError, called at ...
--     h, called at ...
--     g, called at ...
--     f, called at ...
--   X: QQ
--   CallStack (from HasCallStack):
--     errorX, called at ...
--   </pre>
xToError :: HasCallStack => a -> a

-- | Like the <a>Show</a> class, but values that normally throw an
--   <a>XException</a> are converted to <tt>undefined</tt>, instead of
--   error'ing out with an exception.
--   
--   <pre>
--   &gt;&gt;&gt; show (errorX "undefined" :: Integer, 4 :: Int)
--   "(*** Exception: X: undefined
--   CallStack (from HasCallStack):
--   ...
--   
--   &gt;&gt;&gt; showX (errorX "undefined" :: Integer, 4 :: Int)
--   "(undefined,4)"
--   </pre>
--   
--   Can be derived using <a>Generics</a>:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--   
--   import Clash.Prelude
--   import GHC.Generics
--   
--   data T = MkTA Int | MkTB Bool
--     deriving (Show,Generic,ShowX)
--   </pre>
class ShowX a

-- | Like <a>showsPrec</a>, but values that normally throw an
--   <a>XException</a> are converted to <tt>undefined</tt>, instead of
--   error'ing out with an exception.
showsPrecX :: ShowX a => Int -> a -> ShowS

-- | Like <a>show</a>, but values that normally throw an <a>XException</a>
--   are converted to <tt>undefined</tt>, instead of error'ing out with an
--   exception.
showX :: ShowX a => a -> String

-- | Like <a>showList</a>, but values that normally throw an
--   <a>XException</a> are converted to <tt>undefined</tt>, instead of
--   error'ing out with an exception.
showListX :: ShowX a => [a] -> ShowS

-- | Like <a>showsPrec</a>, but values that normally throw an
--   <a>XException</a> are converted to <tt>undefined</tt>, instead of
--   error'ing out with an exception.
showsPrecX :: (ShowX a, Generic a, GShowX (Rep a)) => Int -> a -> ShowS

-- | Like <a>shows</a>, but values that normally throw an <a>XException</a>
--   are converted to <tt>undefined</tt>, instead of error'ing out with an
--   exception.
showsX :: ShowX a => a -> ShowS

-- | Like <a>print</a>, but values that normally throw an <a>XException</a>
--   are converted to <tt>undefined</tt>, instead of error'ing out with an
--   exception
printX :: ShowX a => a -> IO ()

-- | Use when you want to create a <a>ShowX</a> instance where:
--   
--   <ul>
--   <li>There is no <a>Generic</a> instance for your data type</li>
--   <li>The <a>Generic</a> derived ShowX method would traverse into the
--   (hidden) implementation details of your data type, and you just want
--   to show the entire value as <tt>undefined</tt>.</li>
--   </ul>
--   
--   Can be used like:
--   
--   <pre>
--   data T = ...
--   
--   instance Show T where ...
--   
--   instance ShowX T where
--     showsPrecX = showsPrecXWith showsPrec
--   </pre>
showsPrecXWith :: (Int -> a -> ShowS) -> Int -> a -> ShowS

-- | Like <a>seq</a>, however, whereas <a>seq</a> will always do:
--   
--   <pre>
--   seq  _|_              b = _|_
--   </pre>
--   
--   <a>seqX</a> will do:
--   
--   <pre>
--   seqX (XException msg) b = b
--   seqX _|_              b = _|_
--   </pre>
seqX :: a -> b -> b
infixr 0 `seqX`

-- | Like <a>seqX</a>, but will also catch ErrorCall exceptions which are
--   thrown. This should be used with care.
--   
--   <pre>
--   seqErrorX (ErrorCall msg)  b = b
--   seqErrorX (XException msg) b = b
--   seqErrorX _|_              b = _|_
--   </pre>
seqErrorX :: a -> b -> b
infixr 0 `seqErrorX`

-- | a variant of <a>deepseqX</a> that is useful in some circumstances:
--   
--   <pre>
--   forceX x = x `deepseqX` x
--   </pre>
forceX :: NFDataX a => a -> a

-- | <a>deepseqX</a>: fully evaluates the first argument, before returning
--   the second. Does not propagate <a>XException</a>s.
deepseqX :: NFDataX a => a -> b -> b
infixr 0 `deepseqX`

-- | Reduce to weak head normal form
--   
--   Equivalent to <tt>\x -&gt; <a>seqX</a> x ()</tt>.
--   
--   Useful for defining <a>rnfX</a> for types for which NF=WHNF holds.
rwhnfX :: a -> ()

-- | Either <a>seqX</a> or <a>deepseqX</a> depending on the value of the
--   cabal flag '-fsuper-strict'. If enabled, <a>defaultSeqX</a> will be
--   <a>deepseqX</a>, otherwise <a>seqX</a>. Flag defaults to <i>false</i>
--   and thus <a>seqX</a>.
defaultSeqX :: NFDataX a => a -> b -> b
infixr 0 `defaultSeqX`

-- | Like <a>seqX</a> in simulation, but will force its first argument to
--   be rendered in HDL. This is useful for components that need to be
--   rendered in hardware, but otherwise have no meaning in simulation. An
--   example of such a component would be an ILA: a component monitoring an
--   internal signal of a design. The output of such a component (typically
--   a unit) can be passed as the first argument to <a>hwSeqX</a> to ensure
--   the ILA ends up in the generated HDL.
--   
--   <b>NB</b>: The result of <a>hwSeqX</a> must (indirectly) be used at
--   the very top of a design. If it's not, Clash will remove it like it
--   does for any other unused circuit parts.
--   
--   <b>NB</b>: Make sure the blackbox for the component with zero-width
--   results uses <a>RenderVoid</a>
hwSeqX :: a -> b -> b
infixr 0 `hwSeqX`

-- | Class that houses functions dealing with <i>undefined</i> values in
--   Clash. See <a>deepErrorX</a> and <a>rnfX</a>.
class NFDataX a

-- | Create a value where all the elements have an <a>errorX</a>, but the
--   spine is defined.
deepErrorX :: (NFDataX a, HasCallStack) => String -> a

-- | Create a value where all the elements have an <a>errorX</a>, but the
--   spine is defined.
deepErrorX :: (NFDataX a, HasCallStack, Generic a, GDeepErrorX (Rep a)) => String -> a

-- | Determines whether any of parts of a given construct contain undefined
--   parts. Note that a negative answer does not mean its bit
--   representation is fully defined. For example:
--   
--   <pre>
--   &gt;&gt;&gt; m = Nothing :: Maybe Bool
--   
--   &gt;&gt;&gt; hasUndefined m
--   False
--   
--   &gt;&gt;&gt; pack m
--   0b0.
--   
--   &gt;&gt;&gt; hasUndefined (pack m)
--   True
--   </pre>
hasUndefined :: NFDataX a => a -> Bool

-- | Determines whether any of parts of a given construct contain undefined
--   parts. Note that a negative answer does not mean its bit
--   representation is fully defined. For example:
--   
--   <pre>
--   &gt;&gt;&gt; m = Nothing :: Maybe Bool
--   
--   &gt;&gt;&gt; hasUndefined m
--   False
--   
--   &gt;&gt;&gt; pack m
--   0b0.
--   
--   &gt;&gt;&gt; hasUndefined (pack m)
--   True
--   </pre>
hasUndefined :: (NFDataX a, Generic a, GHasUndefined (Rep a)) => a -> Bool

-- | Create a value where at the very least the spine is defined. For
--   example:
--   
--   <pre>
--   &gt;&gt;&gt; spined = ensureSpine (errorX "?" :: (Int, Int))
--   
--   &gt;&gt;&gt; case spined of (_, _) -&gt; 'a'
--   'a'
--   
--   &gt;&gt;&gt; fmap (const 'b') (ensureSpine undefined :: Vec 3 Int)
--   'b' :&gt; 'b' :&gt; 'b' :&gt; Nil
--   
--   &gt;&gt;&gt; fmap (const 'c') (ensureSpine undefined :: RTree 2 Int)
--   &lt;&lt;'c','c'&gt;,&lt;'c','c'&gt;&gt;
--   </pre>
--   
--   For users familiar with <a>lazyV</a>: this is the generalized version
--   of it.
ensureSpine :: NFDataX a => a -> a

-- | Create a value where at the very least the spine is defined. For
--   example:
--   
--   <pre>
--   &gt;&gt;&gt; spined = ensureSpine (errorX "?" :: (Int, Int))
--   
--   &gt;&gt;&gt; case spined of (_, _) -&gt; 'a'
--   'a'
--   
--   &gt;&gt;&gt; fmap (const 'b') (ensureSpine undefined :: Vec 3 Int)
--   'b' :&gt; 'b' :&gt; 'b' :&gt; Nil
--   
--   &gt;&gt;&gt; fmap (const 'c') (ensureSpine undefined :: RTree 2 Int)
--   &lt;&lt;'c','c'&gt;,&lt;'c','c'&gt;&gt;
--   </pre>
--   
--   For users familiar with <a>lazyV</a>: this is the generalized version
--   of it.
ensureSpine :: (NFDataX a, Generic a, GEnsureSpine (Rep a)) => a -> a

-- | Evaluate a value to NF. As opposed to <a>NFData</a>s <a>rnf</a>, it
--   does not bubble up <a>XException</a>s.
rnfX :: NFDataX a => a -> ()

-- | Evaluate a value to NF. As opposed to <a>NFData</a>s <a>rnf</a>, it
--   does not bubble up <a>XException</a>s.
rnfX :: (NFDataX a, Generic a, GNFDataX Zero (Rep a)) => a -> ()
instance (Clash.XException.NFDataX a0, Clash.XException.NFDataX a1) => Clash.XException.NFDataX (a0, a1)
instance (Clash.XException.NFDataX a0, Clash.XException.NFDataX a1, Clash.XException.NFDataX a2) => Clash.XException.NFDataX (a0, a1, a2)
instance (Clash.XException.ShowX a0, Clash.XException.ShowX a1) => Clash.XException.ShowX (a0, a1)
instance (Clash.XException.ShowX a0, Clash.XException.ShowX a1, Clash.XException.ShowX a2) => Clash.XException.ShowX (a0, a1, a2)
instance Clash.XException.NFDataX ()
instance Clash.XException.NFDataX b => Clash.XException.NFDataX (a -> b)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Ord.Down a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.List.Infinite.Internal.Infinite a)
instance Clash.XException.NFDataX GHC.Types.Bool
instance Clash.XException.NFDataX GHC.Types.Ordering
instance Clash.XException.NFDataX a => Clash.XException.NFDataX [a]
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (GHC.Base.NonEmpty a)
instance (Clash.XException.NFDataX a, Clash.XException.NFDataX b) => Clash.XException.NFDataX (Data.Either.Either a b)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (GHC.Maybe.Maybe a)
instance Clash.XException.NFDataX (Data.Proxy.Proxy a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Functor.Identity.Identity a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Functor.Const.Const a b)
instance (Clash.XException.NFDataX (f a), Clash.XException.NFDataX (g a)) => Clash.XException.NFDataX (Data.Functor.Product.Product f g a)
instance (Clash.XException.NFDataX (f a), Clash.XException.NFDataX (g a)) => Clash.XException.NFDataX (Data.Functor.Sum.Sum f g a)
instance Clash.XException.NFDataX (f (g a)) => Clash.XException.NFDataX (Data.Functor.Compose.Compose f g a)
instance Clash.XException.NFDataX GHC.Types.Char
instance Clash.XException.NFDataX GHC.Types.Double
instance Clash.XException.NFDataX GHC.Types.Float
instance Clash.XException.NFDataX GHC.Types.Int
instance Clash.XException.NFDataX GHC.Int.Int8
instance Clash.XException.NFDataX GHC.Int.Int16
instance Clash.XException.NFDataX GHC.Int.Int32
instance Clash.XException.NFDataX GHC.Int.Int64
instance Clash.XException.NFDataX GHC.Integer.Type.Integer
instance Clash.XException.NFDataX GHC.Natural.Natural
instance Clash.XException.NFDataX GHC.Types.Word
instance Clash.XException.NFDataX GHC.Word.Word8
instance Clash.XException.NFDataX GHC.Word.Word16
instance Clash.XException.NFDataX GHC.Word.Word32
instance Clash.XException.NFDataX GHC.Word.Word64
instance Clash.XException.NFDataX Foreign.C.Types.CUShort
instance Clash.XException.NFDataX Numeric.Half.Internal.Half
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Sequence.Internal.Seq a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (GHC.Real.Ratio a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Complex.Complex a)
instance (Clash.XException.NFDataX a, Clash.XException.NFDataX b) => Clash.XException.NFDataX (Data.Semigroup.Arg a b)
instance Clash.XException.NFDataX Data.Semigroup.Internal.All
instance Clash.XException.NFDataX Data.Semigroup.Internal.Any
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Internal.Dual a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Internal.Endo a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.First a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Last a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Max a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Min a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Internal.Product a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Internal.Sum a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Monoid.First a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Monoid.Last a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Data.Semigroup.Option a)
instance Clash.XException.ShowX ()
instance Clash.XException.ShowX (Data.Proxy.Proxy a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Data.Functor.Identity.Identity a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Data.Functor.Const.Const a b)
instance (Clash.XException.ShowX (f a), Clash.XException.ShowX (g a)) => Clash.XException.ShowX (Data.Functor.Product.Product f g a)
instance (Clash.XException.ShowX (f a), Clash.XException.ShowX (g a)) => Clash.XException.ShowX (Data.Functor.Sum.Sum f g a)
instance Clash.XException.ShowX (f (g a)) => Clash.XException.ShowX (Data.Functor.Compose.Compose f g a)
instance Clash.XException.ShowX a => Clash.XException.ShowX [a]
instance Clash.XException.ShowX GHC.Types.Char
instance Clash.XException.ShowX GHC.Types.Bool
instance Clash.XException.ShowX GHC.Types.Double
instance Clash.XException.ShowX a => Clash.XException.ShowX (Data.Ord.Down a)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b) => Clash.XException.ShowX (Data.Either.Either a b)
instance Clash.XException.ShowX GHC.Types.Float
instance Clash.XException.ShowX GHC.Types.Int
instance Clash.XException.ShowX GHC.Int.Int8
instance Clash.XException.ShowX GHC.Int.Int16
instance Clash.XException.ShowX GHC.Int.Int32
instance Clash.XException.ShowX GHC.Int.Int64
instance Clash.XException.ShowX GHC.Integer.Type.Integer
instance Clash.XException.ShowX GHC.Natural.Natural
instance Clash.XException.ShowX GHC.Types.Ordering
instance Clash.XException.ShowX a => Clash.XException.ShowX (Data.Sequence.Internal.Seq a)
instance Clash.XException.ShowX GHC.Types.Word
instance Clash.XException.ShowX GHC.Word.Word8
instance Clash.XException.ShowX GHC.Word.Word16
instance Clash.XException.ShowX GHC.Word.Word32
instance Clash.XException.ShowX GHC.Word.Word64
instance Clash.XException.ShowX a => Clash.XException.ShowX (GHC.Maybe.Maybe a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (GHC.Real.Ratio a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Data.Complex.Complex a)
instance Clash.XException.ShowX GHC.Base.String


-- | Helpers to make <a>XException</a> explicit in the type system. Using
--   these helpers can help programmers account for <a>XException</a>s
--   properly in blackbox models or tests. Note that none of these
--   operations can be translated to HDL.
module Clash.XException.MaybeX

-- | Structure helping programmers to deal with <a>XException</a> values.
--   For safety reasons it can't be constructed directly, but should be
--   constructed using either <a>pure</a> or <a>toMaybeX</a>. After
--   construction, it can be deconstructed using either <a>IsX</a> or
--   <a>IsDefined</a>.
data MaybeX a

-- | Upon construction, <tt>a</tt> evaluated to <a>XException</a>
pattern IsX :: forall a. String -> MaybeX a

-- | Upon construction, <tt>a</tt> evaluated to a non-bottom WHNF
pattern IsDefined :: forall a. a -> MaybeX a

-- | Construct a <a>MaybeX</a> value. If <tt>a</tt> evaluates to
--   <a>XException</a>, this function will return <a>IsX</a>. Otherwise, it
--   will return <a>IsDefined</a>.
toMaybeX :: a -> MaybeX a

-- | Construct a <a>MaybeX</a> value. If <a>hasX</a> evaluates to
--   <a>Left</a>, this function will return <a>IsX</a>. Otherwise, it will
--   return <a>IsDefined</a>.
hasXToMaybeX :: (NFDataX a, NFData a) => a -> MaybeX a

-- | Deconstruct <a>MaybeX</a> into an <tt>a</tt> - the opposite of
--   <a>toMaybeX</a>. Be careful when using this function, because it might
--   return an <a>XException</a> if the argument was <a>IsX</a>.
fromMaybeX :: MaybeX a -> a

-- | Implements <a>&amp;&amp;</a> accounting for X
--   
--   TODO: table
andX :: MaybeX Bool -> MaybeX Bool -> MaybeX Bool
infixr 3 `andX`

-- | Implements <a>||</a> accounting for X
--   
--   TODO: table
orX :: MaybeX Bool -> MaybeX Bool -> MaybeX Bool
infixr 2 `orX`

-- | Map functions over both constructors.
maybeX :: (String -> b) -> (a -> b) -> MaybeX a -> b
instance GHC.Show.Show a => GHC.Show.Show (Clash.XException.MaybeX.MaybeX a)
instance GHC.Base.Functor Clash.XException.MaybeX.MaybeX
instance GHC.Base.Applicative Clash.XException.MaybeX.MaybeX


module Clash.Promoted.Nat

-- | Singleton value for a type-level natural number <tt>n</tt>
--   
--   <ul>
--   <li><a>Clash.Promoted.Nat.Literals</a> contains a list of predefined
--   <a>SNat</a> literals</li>
--   <li><a>Clash.Promoted.Nat.TH</a> has functions to easily create large
--   ranges of new <a>SNat</a> literals</li>
--   </ul>
data SNat (n :: Nat)
[SNat] :: KnownNat n => SNat n

-- | Create an <tt><a>SNat</a> n</tt> from a proxy for <i>n</i>
snatProxy :: KnownNat n => proxy n -> SNat n

-- | Supply a function with a singleton natural <tt>n</tt> according to the
--   context
withSNat :: KnownNat n => (SNat n -> a) -> a

-- | Reify the type-level <a>Nat</a> <tt>n</tt> to it's term-level
--   <a>Integer</a> representation.
snatToInteger :: SNat n -> Integer

-- | Reify the type-level <a>Nat</a> <tt>n</tt> to it's term-level
--   <a>Natural</a>.
snatToNatural :: SNat n -> Natural

-- | Reify the type-level <a>Nat</a> <tt>n</tt> to it's term-level
--   <a>Num</a>ber.
snatToNum :: forall a n. Num a => SNat n -> a

-- | Same as <a>snatToInteger</a> and <a>natVal</a>, but doesn't take term
--   arguments. Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; natToInteger @5
--   5
--   </pre>
natToInteger :: forall n. KnownNat n => Integer

-- | Same as <a>snatToNatural</a> and <a>natVal</a>, but doesn't take term
--   arguments. Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; natToNatural @5
--   5
--   </pre>
natToNatural :: forall n. KnownNat n => Natural

-- | Same as <a>snatToNum</a>, but doesn't take term arguments. Example
--   usage:
--   
--   <pre>
--   &gt;&gt;&gt; natToNum @5 @Int
--   5
--   </pre>
natToNum :: forall n a. (Num a, KnownNat n) => a

-- | Add two singleton natural numbers
addSNat :: SNat a -> SNat b -> SNat (a + b)
infixl 6 `addSNat`

-- | Multiply two singleton natural numbers
mulSNat :: SNat a -> SNat b -> SNat (a * b)
infixl 7 `mulSNat`

-- | Power of two singleton natural numbers
powSNat :: SNat a -> SNat b -> SNat (a ^ b)
infixr 8 `powSNat`
minSNat :: SNat a -> SNat b -> SNat (Min a b)
maxSNat :: SNat a -> SNat b -> SNat (Max a b)

-- | Successor of a singleton natural number
succSNat :: SNat a -> SNat (a + 1)

-- | Subtract two singleton natural numbers
subSNat :: SNat (a + b) -> SNat b -> SNat a
infixl 6 `subSNat`

-- | Division of two singleton natural numbers
divSNat :: 1 <= b => SNat a -> SNat b -> SNat (Div a b)
infixl 7 `divSNat`

-- | Modulo of two singleton natural numbers
modSNat :: 1 <= b => SNat a -> SNat b -> SNat (Mod a b)
infixl 7 `modSNat`

-- | Floor of the logarithm of a natural number
flogBaseSNat :: (2 <= base, 1 <= x) => SNat base -> SNat x -> SNat (FLog base x)

-- | Ceiling of the logarithm of a natural number
clogBaseSNat :: (2 <= base, 1 <= x) => SNat base -> SNat x -> SNat (CLog base x)

-- | Exact integer logarithm of a natural number
--   
--   <b>NB</b>: Only works when the argument is a power of the base
logBaseSNat :: FLog base x ~ CLog base x => SNat base -> SNat x -> SNat (Log base x)

-- | Predecessor of a singleton natural number
predSNat :: SNat (a + 1) -> SNat a

-- | Power of two of a singleton natural number
pow2SNat :: SNat a -> SNat (2 ^ a)

-- | Ordering relation between two Nats
data SNatLE a b
[SNatLE] :: forall a b. a <= b => SNatLE a b
[SNatGT] :: forall a b. (b + 1) <= a => SNatLE a b

-- | Get an ordering relation between two SNats
compareSNat :: forall a b. SNat a -> SNat b -> SNatLE a b

-- | Unary representation of a type-level natural
--   
--   <b>NB</b>: Not synthesizable
data UNat :: Nat -> Type
[UZero] :: UNat 0
[USucc] :: UNat n -> UNat (n + 1)

-- | Convert a singleton natural number to its unary representation
--   
--   <b>NB</b>: Not synthesizable
toUNat :: forall n. SNat n -> UNat n

-- | Convert a unary-encoded natural number to its singleton representation
--   
--   <b>NB</b>: Not synthesizable
fromUNat :: UNat n -> SNat n

-- | Add two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesizable
addUNat :: UNat n -> UNat m -> UNat (n + m)

-- | Multiply two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesizable
mulUNat :: UNat n -> UNat m -> UNat (n * m)

-- | Power of two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesizable
powUNat :: UNat n -> UNat m -> UNat (n ^ m)

-- | Predecessor of a unary-encoded natural number
--   
--   <b>NB</b>: Not synthesizable
predUNat :: UNat (n + 1) -> UNat n

-- | Subtract two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesizable
subUNat :: UNat (m + n) -> UNat n -> UNat m

-- | Base-2 encoded natural number
--   
--   <ul>
--   <li><b>NB</b>: The LSB is the left/outer-most constructor:</li>
--   <li><b>NB</b>: Not synthesizable</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; B0 (B1 (B1 BT))
--   b6
--   </pre>
--   
--   <h2>Constructors</h2>
--   
--   <ul>
--   <li>Starting/Terminating element:<pre><b>BT</b> :: <a>BNat</a> 0
--   </pre></li>
--   </ul>
--   
--   <ul>
--   <li>Append a zero (<i>0</i>):<pre><b>B0</b> :: <a>BNat</a> n -&gt;
--   <a>BNat</a> (2 <a>*</a> n) </pre></li>
--   <li>Append a one (<i>1</i>):<pre><b>B1</b> :: <a>BNat</a> n -&gt;
--   <a>BNat</a> ((2 <a>*</a> n) <a>+</a> 1) </pre></li>
--   </ul>
data BNat :: Nat -> Type
[BT] :: BNat 0
[B0] :: BNat n -> BNat (2 * n)
[B1] :: BNat n -> BNat ((2 * n) + 1)

-- | Convert a singleton natural number to its base-2 representation
--   
--   <b>NB</b>: Not synthesizable
toBNat :: SNat n -> BNat n

-- | Convert a base-2 encoded natural number to its singleton
--   representation
--   
--   <b>NB</b>: Not synthesizable
fromBNat :: BNat n -> SNat n

-- | Show a base-2 encoded natural as a binary literal
--   
--   <b>NB</b>: The LSB is shown as the right-most bit
--   
--   <pre>
--   &gt;&gt;&gt; d789
--   d789
--   
--   &gt;&gt;&gt; toBNat d789
--   b789
--   
--   &gt;&gt;&gt; showBNat (toBNat d789)
--   "0b1100010101"
--   
--   &gt;&gt;&gt; 0b1100010101 :: Integer
--   789
--   </pre>
showBNat :: BNat n -> String

-- | Successor of a base-2 encoded natural number
--   
--   <b>NB</b>: Not synthesizable
succBNat :: BNat n -> BNat (n + 1)

-- | Add two base-2 encoded natural numbers
--   
--   <b>NB</b>: Not synthesizable
addBNat :: BNat n -> BNat m -> BNat (n + m)

-- | Multiply two base-2 encoded natural numbers
--   
--   <b>NB</b>: Not synthesizable
mulBNat :: BNat n -> BNat m -> BNat (n * m)

-- | Power of two base-2 encoded natural numbers
--   
--   <b>NB</b>: Not synthesizable
powBNat :: BNat n -> BNat m -> BNat (n ^ m)

-- | Predecessor of a base-2 encoded natural number
--   
--   <b>NB</b>: Not synthesizable
predBNat :: 1 <= n => BNat n -> BNat (n - 1)

-- | Divide a base-2 encoded natural number by 2
--   
--   <b>NB</b>: Not synthesizable
div2BNat :: BNat (2 * n) -> BNat n

-- | Subtract 1 and divide a base-2 encoded natural number by 2
--   
--   <b>NB</b>: Not synthesizable
div2Sub1BNat :: BNat ((2 * n) + 1) -> BNat n

-- | Get the log2 of a base-2 encoded natural number
--   
--   <b>NB</b>: Not synthesizable
log2BNat :: BNat (2 ^ n) -> BNat n

-- | Strip non-contributing zero's from a base-2 encoded natural number
--   
--   <pre>
--   &gt;&gt;&gt; B1 (B0 (B0 (B0 BT)))
--   b1
--   
--   &gt;&gt;&gt; showBNat (B1 (B0 (B0 (B0 BT))))
--   "0b0001"
--   
--   &gt;&gt;&gt; showBNat (stripZeros (B1 (B0 (B0 (B0 BT)))))
--   "0b1"
--   
--   &gt;&gt;&gt; stripZeros (B1 (B0 (B0 (B0 BT))))
--   b1
--   </pre>
--   
--   <b>NB</b>: Not synthesizable
stripZeros :: BNat n -> BNat n

-- | Change a function that has an argument with an <tt>(n ~ (k + m))</tt>
--   constraint to a function with an argument that has an <tt>(k &lt;=
--   n)</tt> constraint.
--   
--   <h3><b>Examples</b></h3>
--   
--   Example 1
--   
--   <pre>
--   f :: Index (n+1) -&gt; Index (n + 1) -&gt; Bool
--   
--   g :: forall n. (1 <a>&lt;=</a> n) =&gt; Index n -&gt; Index n -&gt; Bool
--   g a b = <a>leToPlus</a> @1 @n (f a b)
--   </pre>
--   
--   Example 2
--   
--   <pre>
--   head :: Vec (n + 1) a -&gt; a
--   
--   head' :: forall n a. (1 <a>&lt;=</a> n) =&gt; Vec n a -&gt; a
--   head' = <a>leToPlus</a> @1 @n head
--   </pre>
leToPlus :: forall (k :: Nat) (n :: Nat) r. k <= n => (forall m. n ~ (k + m) => r) -> r

-- | Same as <a>leToPlus</a> with added <a>KnownNat</a> constraints
leToPlusKN :: forall (k :: Nat) (n :: Nat) r. (k <= n, KnownNat k, KnownNat n) => (forall m. (n ~ (k + m), KnownNat m) => r) -> r
instance GHC.Show.Show (Clash.Promoted.Nat.SNatLE a b)
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Clash.Promoted.Nat.BNat n)
instance GHC.TypeNats.KnownNat n => Clash.XException.ShowX (Clash.Promoted.Nat.BNat n)
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Clash.Promoted.Nat.UNat n)
instance GHC.TypeNats.KnownNat n => Clash.XException.ShowX (Clash.Promoted.Nat.UNat n)
instance Language.Haskell.TH.Syntax.Lift (Clash.Promoted.Nat.SNat n)
instance GHC.Show.Show (Clash.Promoted.Nat.SNat n)
instance Clash.XException.ShowX (Clash.Promoted.Nat.SNat n)


module Clash.Sized.Internal.BitVector

-- | A single bit
--   
--   <b>NB</b>: The usual Haskell method of converting an integral numeric
--   type to another, <a>fromIntegral</a>, is not well suited for Clash as
--   it will go through <a>Integer</a> which is arbitrarily bounded in HDL.
--   Instead use <a>bitCoerce</a> and the <a>Resize</a> class.
data Bit

-- | The constructor, <a>Bit</a>, and the fields, <a>unsafeMask#</a> and
--   <a>unsafeToInteger#</a>, are not synthesizable.
Bit :: {-# UNPACK #-} !Word -> {-# UNPACK #-} !Word -> Bit
[unsafeMask#] :: Bit -> {-# UNPACK #-} !Word
[unsafeToInteger#] :: Bit -> {-# UNPACK #-} !Word

-- | logic '1'
high :: Bit

-- | logic '0'
low :: Bit
eq## :: Bit -> Bit -> Bool
neq## :: Bit -> Bit -> Bool
lt## :: Bit -> Bit -> Bool
ge## :: Bit -> Bit -> Bool
gt## :: Bit -> Bit -> Bool
le## :: Bit -> Bit -> Bool
toEnum## :: Int -> Bit
fromInteger## :: Word# -> Integer -> Bit
and## :: Bit -> Bit -> Bit
or## :: Bit -> Bit -> Bit
xor## :: Bit -> Bit -> Bit
complement## :: Bit -> Bit
pack# :: Bit -> BitVector 1
unpack# :: BitVector 1 -> Bit

-- | A vector of bits
--   
--   <ul>
--   <li>Bit indices are descending</li>
--   <li><a>Num</a> instance performs <i>unsigned</i> arithmetic.</li>
--   </ul>
--   
--   <b>NB</b>: The usual Haskell method of converting an integral numeric
--   type to another, <a>fromIntegral</a>, is not well suited for Clash as
--   it will go through <a>Integer</a> which is arbitrarily bounded in HDL.
--   Instead use <a>bitCoerce</a> and the <a>Resize</a> class.
--   
--   BitVector has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BitVector
--   type role BitVector nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between different sizes of BitVector. To
--   change the size, use the functions in the <a>Resize</a> class.
data BitVector (n :: Nat)

-- | The constructor, <a>BV</a>, and the fields, <a>unsafeMask</a> and
--   <a>unsafeToNatural</a>, are not synthesizable.
BV :: !Natural -> !Natural -> BitVector (n :: Nat)
[unsafeMask] :: BitVector (n :: Nat) -> !Natural
[unsafeToNatural] :: BitVector (n :: Nat) -> !Natural
size# :: KnownNat n => BitVector n -> Int
maxIndex# :: KnownNat n => BitVector n -> Int

-- | Create a binary literal
--   
--   <pre>
--   &gt;&gt;&gt; $(bLit "1001")
--   0b1001
--   </pre>
--   
--   <b>NB</b>: You can also just write:
--   
--   <pre>
--   &gt;&gt;&gt; 0b1001 :: BitVector 4
--   0b1001
--   </pre>
--   
--   The advantage of <a>bLit</a> is that you can use computations to
--   create the string literal:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; $(bLit (List.replicate 4 '1'))
--   0b1111
--   </pre>
--   
--   Also <a>bLit</a> can handle don't care bits:
--   
--   <pre>
--   &gt;&gt;&gt; $(bLit "1.0.")
--   0b1.0.
--   </pre>
--   
--   <b>NB</b>: From Clash 1.6 an onwards <a>bLit</a> will deduce the size
--   of the BitVector from the given string and annotate the splice it
--   produces accordingly.
bLit :: String -> ExpQ

-- | Create a hexadecimal literal
--   
--   <pre>
--   &gt;&gt;&gt; $(hLit "dead")
--   0b1101_1110_1010_1101
--   </pre>
--   
--   Don't care digits set 4 bits:
--   
--   <pre>
--   &gt;&gt;&gt; $(hLit "de..")
--   0b1101_1110_...._....
--   </pre>
hLit :: String -> ExpQ

-- | Create an octal literal
--   
--   <pre>
--   &gt;&gt;&gt; $(oLit "5234")
--   0b1010_1001_1100
--   </pre>
--   
--   Don't care digits set 3 bits:
--   
--   <pre>
--   &gt;&gt;&gt; $(oLit "52..")
--   0b1010_10.._....
--   </pre>
oLit :: String -> ExpQ

-- | Create a BitVector with all its bits undefined
undefined# :: forall n. KnownNat n => BitVector n

-- | Concatenate two <a>BitVector</a>s
(++#) :: KnownNat m => BitVector n -> BitVector m -> BitVector (n + m)
reduceAnd# :: KnownNat n => BitVector n -> Bit
reduceOr# :: KnownNat n => BitVector n -> Bit
reduceXor# :: KnownNat n => BitVector n -> Bit
index# :: KnownNat n => BitVector n -> Int -> Bit
replaceBit# :: KnownNat n => BitVector n -> Int -> Bit -> BitVector n
setSlice# :: forall m i n. SNat ((m + 1) + i) -> BitVector ((m + 1) + i) -> SNat m -> SNat n -> BitVector ((m + 1) - n) -> BitVector ((m + 1) + i)
slice# :: BitVector ((m + 1) + i) -> SNat m -> SNat n -> BitVector ((m + 1) - n)
split# :: forall n m. KnownNat n => BitVector (m + n) -> (BitVector m, BitVector n)

-- | MSB
msb# :: forall n. KnownNat n => BitVector n -> Bit

-- | LSB
lsb# :: BitVector n -> Bit
eq# :: KnownNat n => BitVector n -> BitVector n -> Bool
neq# :: KnownNat n => BitVector n -> BitVector n -> Bool

-- | Check if one BitVector is similar to another, interpreting undefined
--   bits in the second argument as being "don't care" bits. This is a more
--   lenient version of <a>(==)</a>, similar to <tt>std_match</tt> in VHDL
--   or <tt>casez</tt> in Verilog.
--   
--   <pre>
--   &gt;&gt;&gt; let expected = $(bLit "1.")
--   
--   &gt;&gt;&gt; let checked  = $(bLit "11")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; checked  `isLike#` expected
--   True
--   
--   &gt;&gt;&gt; expected `isLike#` checked
--   False
--   </pre>
--   
--   <b>NB</b>: Not synthesizable
isLike# :: forall n. KnownNat n => BitVector n -> BitVector n -> Bool
lt# :: KnownNat n => BitVector n -> BitVector n -> Bool
ge# :: KnownNat n => BitVector n -> BitVector n -> Bool
gt# :: KnownNat n => BitVector n -> BitVector n -> Bool
le# :: KnownNat n => BitVector n -> BitVector n -> Bool
toEnum# :: forall n. KnownNat n => Int -> BitVector n
fromEnum# :: forall n. KnownNat n => BitVector n -> Int
enumFrom# :: forall n. KnownNat n => BitVector n -> [BitVector n]
enumFromThen# :: forall n. KnownNat n => BitVector n -> BitVector n -> [BitVector n]
enumFromTo# :: forall n. KnownNat n => BitVector n -> BitVector n -> [BitVector n]
enumFromThenTo# :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n -> [BitVector n]
minBound# :: BitVector n
maxBound# :: forall n. KnownNat n => BitVector n
(+#) :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
(-#) :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
(*#) :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
negate# :: forall n. KnownNat n => BitVector n -> BitVector n
fromInteger# :: KnownNat n => Natural -> Integer -> BitVector n
plus# :: (KnownNat m, KnownNat n) => BitVector m -> BitVector n -> BitVector (Max m n + 1)
minus# :: forall m n. (KnownNat m, KnownNat n) => BitVector m -> BitVector n -> BitVector (Max m n + 1)
times# :: (KnownNat m, KnownNat n) => BitVector m -> BitVector n -> BitVector (m + n)
quot# :: KnownNat n => BitVector n -> BitVector n -> BitVector n
rem# :: KnownNat n => BitVector n -> BitVector n -> BitVector n
toInteger# :: KnownNat n => BitVector n -> Integer
and# :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
or# :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
xor# :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
complement# :: forall n. KnownNat n => BitVector n -> BitVector n
shiftL# :: forall n. KnownNat n => BitVector n -> Int -> BitVector n
shiftR# :: forall n. KnownNat n => BitVector n -> Int -> BitVector n
rotateL# :: forall n. KnownNat n => BitVector n -> Int -> BitVector n
rotateR# :: forall n. KnownNat n => BitVector n -> Int -> BitVector n
popCountBV :: forall n. KnownNat n => BitVector (n + 1) -> Index (n + 2)
countLeadingZerosBV :: KnownNat n => BitVector n -> Index (n + 1)
countTrailingZerosBV :: KnownNat n => BitVector n -> Index (n + 1)
truncateB# :: forall a b. KnownNat a => BitVector (a + b) -> BitVector a

-- | <a>shrink</a> for sized unsigned types
shrinkSizedUnsigned :: (KnownNat n, Integral (p n)) => p n -> [p n]
undefError :: KnownNat n => String -> [BitVector n] -> a

-- | Implement BitVector undefinedness checking for unpack functions
checkUnpackUndef :: (KnownNat n, Typeable a) => (BitVector n -> a) -> BitVector n -> a

-- | Template Haskell macro for generating a pattern matching on some bits
--   of a value.
--   
--   This macro compiles to an efficient view pattern that matches the bits
--   of a given value against the bits specified in the pattern. The
--   scrutinee can be any type that is an instance of the <a>Num</a>,
--   <a>Bits</a> and <a>Eq</a> typeclasses.
--   
--   The bit pattern is specified by a string which contains:
--   
--   <ul>
--   <li><tt>'0'</tt> or <tt>'1'</tt> for matching a bit</li>
--   <li><tt>'.'</tt> for bits which are not matched (wildcard)</li>
--   <li><tt>'_'</tt> can be used as a separator similar to the
--   NumericUnderscores language extension</li>
--   <li>lowercase alphabetical characters can be used to bind some bits to
--   variables. For example <tt>"0aab11bb"</tt> will bind two variables
--   <tt>aa :: BitVector 2</tt> and <tt>bbb :: BitVector 3</tt> with their
--   values set by the corresponding bits</li>
--   </ul>
--   
--   The following example matches a byte against two bit patterns where
--   some bits are relevant and others are not while binding two variables
--   <tt>aa</tt> and <tt>bb</tt>:
--   
--   <pre>
--   decode :: Unsigned 8 -&gt; Maybe Bool
--   decode $(bitPattern "00.._.110") = Just True
--   decode $(bitPattern "10.._0001") = Just False
--   decode $(bitPattern "aa.._b0b1") = Just (aa + bb &gt; 1)
--   decode _ = Nothing
--   </pre>
bitPattern :: String -> Q Pat
xToBV :: KnownNat n => BitVector n -> BitVector n
instance GHC.Generics.Generic (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.Generics.Generic Clash.Sized.Internal.BitVector.Bit
instance Data.Data.Data Clash.Sized.Internal.BitVector.Bit
instance Control.DeepSeq.NFData Clash.Sized.Internal.BitVector.Bit
instance GHC.Show.Show Clash.Sized.Internal.BitVector.Bit
instance Clash.XException.ShowX Clash.Sized.Internal.BitVector.Bit
instance Clash.XException.NFDataX Clash.Sized.Internal.BitVector.Bit
instance Language.Haskell.TH.Syntax.Lift Clash.Sized.Internal.BitVector.Bit
instance GHC.Classes.Eq Clash.Sized.Internal.BitVector.Bit
instance GHC.Classes.Ord Clash.Sized.Internal.BitVector.Bit
instance GHC.Enum.Enum Clash.Sized.Internal.BitVector.Bit
instance GHC.Enum.Bounded Clash.Sized.Internal.BitVector.Bit
instance Data.Default.Class.Default Clash.Sized.Internal.BitVector.Bit
instance GHC.Num.Num Clash.Sized.Internal.BitVector.Bit
instance GHC.Real.Real Clash.Sized.Internal.BitVector.Bit
instance GHC.Real.Integral Clash.Sized.Internal.BitVector.Bit
instance Data.Bits.Bits Clash.Sized.Internal.BitVector.Bit
instance Data.Bits.FiniteBits Clash.Sized.Internal.BitVector.Bit
instance Control.DeepSeq.NFData (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Clash.XException.ShowX (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Clash.XException.NFDataX (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Classes.Eq (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Classes.Ord (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.BitVector.BitVector n)
instance (GHC.TypeNats.KnownNat m, GHC.TypeNats.KnownNat n) => Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.BitVector.BitVector m) (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Data.Bits.Bits (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Data.Bits.FiniteBits (Clash.Sized.Internal.BitVector.BitVector n)
instance Data.Default.Class.Default (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.BitVector.BitVector
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Internal.BitVector.BitVector n)


module Clash.Sized.BitVector

-- | A single bit
--   
--   <b>NB</b>: The usual Haskell method of converting an integral numeric
--   type to another, <a>fromIntegral</a>, is not well suited for Clash as
--   it will go through <a>Integer</a> which is arbitrarily bounded in HDL.
--   Instead use <a>bitCoerce</a> and the <a>Resize</a> class.
data Bit

-- | logic '1'
high :: Bit

-- | logic '0'
low :: Bit

-- | A vector of bits
--   
--   <ul>
--   <li>Bit indices are descending</li>
--   <li><a>Num</a> instance performs <i>unsigned</i> arithmetic.</li>
--   </ul>
--   
--   <b>NB</b>: The usual Haskell method of converting an integral numeric
--   type to another, <a>fromIntegral</a>, is not well suited for Clash as
--   it will go through <a>Integer</a> which is arbitrarily bounded in HDL.
--   Instead use <a>bitCoerce</a> and the <a>Resize</a> class.
--   
--   BitVector has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BitVector
--   type role BitVector nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between different sizes of BitVector. To
--   change the size, use the functions in the <a>Resize</a> class.
data BitVector (n :: Nat)
size# :: KnownNat n => BitVector n -> Int
maxIndex# :: KnownNat n => BitVector n -> Int

-- | Create a binary literal
--   
--   <pre>
--   &gt;&gt;&gt; $(bLit "1001")
--   0b1001
--   </pre>
--   
--   <b>NB</b>: You can also just write:
--   
--   <pre>
--   &gt;&gt;&gt; 0b1001 :: BitVector 4
--   0b1001
--   </pre>
--   
--   The advantage of <a>bLit</a> is that you can use computations to
--   create the string literal:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; $(bLit (List.replicate 4 '1'))
--   0b1111
--   </pre>
--   
--   Also <a>bLit</a> can handle don't care bits:
--   
--   <pre>
--   &gt;&gt;&gt; $(bLit "1.0.")
--   0b1.0.
--   </pre>
--   
--   <b>NB</b>: From Clash 1.6 an onwards <a>bLit</a> will deduce the size
--   of the BitVector from the given string and annotate the splice it
--   produces accordingly.
bLit :: String -> ExpQ

-- | Create a hexadecimal literal
--   
--   <pre>
--   &gt;&gt;&gt; $(hLit "dead")
--   0b1101_1110_1010_1101
--   </pre>
--   
--   Don't care digits set 4 bits:
--   
--   <pre>
--   &gt;&gt;&gt; $(hLit "de..")
--   0b1101_1110_...._....
--   </pre>
hLit :: String -> ExpQ

-- | Create an octal literal
--   
--   <pre>
--   &gt;&gt;&gt; $(oLit "5234")
--   0b1010_1001_1100
--   </pre>
--   
--   Don't care digits set 3 bits:
--   
--   <pre>
--   &gt;&gt;&gt; $(oLit "52..")
--   0b1010_10.._....
--   </pre>
oLit :: String -> ExpQ

-- | Concatenate two <a>BitVector</a>s
(++#) :: KnownNat m => BitVector n -> BitVector m -> BitVector (n + m)

-- | Shift in a bit from the MSB side of a <a>BitVector</a>. Equal to right
--   shifting the <a>BitVector</a> by one and replacing the MSB with the
--   bit to be shifted in.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +&gt;&gt;. 0b1111_0000 :: BitVector 8
--   0b1111_1000
--   
--   &gt;&gt;&gt; 0 +&gt;&gt;. 0b1111_0000 :: BitVector 8
--   0b0111_1000
--   </pre>
(+>>.) :: forall n. KnownNat n => Bit -> BitVector n -> BitVector n
infixr 4 +>>.

-- | Shift in a bit from the LSB side of a <a>BitVector</a>. Equal to left
--   shifting the <a>BitVector</a> by one and replacing the LSB with the
--   bit to be shifted in.
--   
--   <pre>
--   &gt;&gt;&gt; 0b1111_0000 .&lt;&lt;+ 0 :: BitVector 8
--   0b1110_0000
--   
--   &gt;&gt;&gt; 0b1111_0000 .&lt;&lt;+ 1 :: BitVector 8
--   0b1110_0001
--   </pre>
(.<<+) :: forall n. KnownNat n => BitVector n -> Bit -> BitVector n
infixr 4 .<<+

-- | Template Haskell macro for generating a pattern matching on some bits
--   of a value.
--   
--   This macro compiles to an efficient view pattern that matches the bits
--   of a given value against the bits specified in the pattern. The
--   scrutinee can be any type that is an instance of the <a>Num</a>,
--   <a>Bits</a> and <a>Eq</a> typeclasses.
--   
--   The bit pattern is specified by a string which contains:
--   
--   <ul>
--   <li><tt>'0'</tt> or <tt>'1'</tt> for matching a bit</li>
--   <li><tt>'.'</tt> for bits which are not matched (wildcard)</li>
--   <li><tt>'_'</tt> can be used as a separator similar to the
--   NumericUnderscores language extension</li>
--   <li>lowercase alphabetical characters can be used to bind some bits to
--   variables. For example <tt>"0aab11bb"</tt> will bind two variables
--   <tt>aa :: BitVector 2</tt> and <tt>bbb :: BitVector 3</tt> with their
--   values set by the corresponding bits</li>
--   </ul>
--   
--   The following example matches a byte against two bit patterns where
--   some bits are relevant and others are not while binding two variables
--   <tt>aa</tt> and <tt>bb</tt>:
--   
--   <pre>
--   decode :: Unsigned 8 -&gt; Maybe Bool
--   decode $(bitPattern "00.._.110") = Just True
--   decode $(bitPattern "10.._0001") = Just False
--   decode $(bitPattern "aa.._b0b1") = Just (aa + bb &gt; 1)
--   decode _ = Nothing
--   </pre>
bitPattern :: String -> Q Pat


module Clash.Signal.Internal

-- | Clash has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (dom :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>dom</i> is the <i>clock-</i>
--   (and <i>reset-</i>) domain to which the memory elements manipulating
--   these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>dom</i>, is of the kind <a>Domain</a> - a
--   simple string. That string refers to a single <i>synthesis domain</i>.
--   A synthesis domain describes the behavior of certain aspects of memory
--   elements in it.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   <li><b>NB</b>: For the best compatibility make sure your period is
--   divisible by 2, because some VHDL simulators don't support fractions
--   of picoseconds.</li>
--   <li><b>NB</b>: Whether <a>System</a> has good defaults depends on your
--   target platform. Check out <a>IntelSystem</a> and <a>XilinxSystem</a>
--   too!</li>
--   </ul>
--   
--   Signals have the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Signal
--   type role Signal nominal representational
--   ...
--   </pre>
--   
--   as it is safe to coerce the underlying value of a signal, but not safe
--   to coerce a signal between different synthesis domains.
--   
--   See the module documentation of <a>Clash.Signal</a> for more
--   information about domains.
data Signal (dom :: Domain) a

-- | The constructor, <tt>(<a>:-</a>)</tt>, is <b>not</b> synthesizable.
(:-) :: a -> Signal dom a -> Signal (dom :: Domain) a
infixr 5 :-
head# :: Signal dom a -> a
tail# :: Signal dom a -> Signal dom a
type Domain = Symbol

-- | We either get evidence that this function was instantiated with the
--   same domains, or Nothing.
sameDomain :: forall (domA :: Domain) (domB :: Domain). (KnownDomain domA, KnownDomain domB) => Maybe (domA :~: domB)

-- | A <a>KnownDomain</a> constraint indicates that a circuit's behavior
--   depends on some properties of a domain. See <a>DomainConfiguration</a>
--   for more information.
class (KnownSymbol dom, KnownNat (DomainPeriod dom)) => KnownDomain (dom :: Domain) where {
    type family KnownConf dom :: DomainConfiguration;
}

-- | Returns <a>SDomainConfiguration</a> corresponding to an instance's
--   <a>DomainConfiguration</a>.
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; knownDomain @System
--   SDomainConfiguration {sName = SSymbol @"System", sPeriod = SNat @10000, sActiveEdge = SRising, sResetKind = SAsynchronous, sInitBehavior = SDefined, sResetPolarity = SActiveHigh}
--   </pre>
knownDomain :: KnownDomain dom => SDomainConfiguration dom (KnownConf dom)
type KnownConfiguration dom conf = (KnownDomain dom, KnownConf dom ~ conf)

-- | Version of <a>knownDomain</a> that takes a <a>SSymbol</a>. For
--   example:
--   
--   <pre>
--   &gt;&gt;&gt; knownDomainByName (SSymbol @"System")
--   SDomainConfiguration {sName = SSymbol @"System", sPeriod = SNat @10000, sActiveEdge = SRising, sResetKind = SAsynchronous, sInitBehavior = SDefined, sResetPolarity = SActiveHigh}
--   </pre>
knownDomainByName :: forall dom. KnownDomain dom => SSymbol dom -> SDomainConfiguration dom (KnownConf dom)

-- | Determines clock edge memory elements are sensitive to. Not yet
--   implemented.
data ActiveEdge

-- | Elements are sensitive to the rising edge (low-to-high) of the clock.
Rising :: ActiveEdge

-- | Elements are sensitive to the falling edge (high-to-low) of the clock.
Falling :: ActiveEdge

-- | Singleton version of <a>ActiveEdge</a>
data SActiveEdge (edge :: ActiveEdge)
[SRising] :: SActiveEdge 'Rising
[SFalling] :: SActiveEdge 'Falling
data InitBehavior

-- | Power up value of memory elements is <i>unknown</i>.
Unknown :: InitBehavior

-- | If applicable, power up value of a memory element is defined. Applies
--   to <a>register</a>s for example, but not to <a>blockRam</a>.
Defined :: InitBehavior
data SInitBehavior (init :: InitBehavior)
[SUnknown] :: SInitBehavior 'Unknown
[SDefined] :: SInitBehavior 'Defined
data ResetKind

-- | Elements respond <i>asynchronously</i> to changes in their reset
--   input. This means that they do <i>not</i> wait for the next active
--   clock edge, but respond immediately instead. Common on Intel FPGA
--   platforms.
Asynchronous :: ResetKind

-- | Elements respond <i>synchronously</i> to changes in their reset input.
--   This means that changes in their reset input won't take effect until
--   the next active clock edge. Common on Xilinx FPGA platforms.
Synchronous :: ResetKind

-- | Singleton version of <a>ResetKind</a>
data SResetKind (resetKind :: ResetKind)
[SAsynchronous] :: SResetKind 'Asynchronous
[SSynchronous] :: SResetKind 'Synchronous

-- | Determines the value for which a reset line is considered "active"
data ResetPolarity

-- | Reset is considered active if underlying signal is <a>True</a>.
ActiveHigh :: ResetPolarity

-- | Reset is considered active if underlying signal is <a>False</a>.
ActiveLow :: ResetPolarity

-- | Singleton version of <a>ResetPolarity</a>
data SResetPolarity (polarity :: ResetPolarity)
[SActiveHigh] :: SResetPolarity 'ActiveHigh
[SActiveLow] :: SResetPolarity 'ActiveLow

-- | A domain with a name (<tt>Domain</tt>). Configures the behavior of
--   various aspects of a circuits. See the documentation of this record's
--   field types for more information on the options.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
data DomainConfiguration
DomainConfiguration :: Domain -> Nat -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> DomainConfiguration

-- | Domain name
[_name] :: DomainConfiguration -> Domain

-- | Period of clock in <i>ps</i>
[_period] :: DomainConfiguration -> Nat

-- | Active edge of the clock
[_activeEdge] :: DomainConfiguration -> ActiveEdge

-- | Whether resets are synchronous (edge-sensitive) or asynchronous
--   (level-sensitive)
[_resetKind] :: DomainConfiguration -> ResetKind

-- | Whether the initial (or "power up") value of memory elements is
--   unknown/undefined, or configurable to a specific value
[_initBehavior] :: DomainConfiguration -> InitBehavior

-- | Whether resets are active high or active low
[_resetPolarity] :: DomainConfiguration -> ResetPolarity

-- | Singleton version of <a>DomainConfiguration</a>
data SDomainConfiguration (dom :: Domain) (conf :: DomainConfiguration)
[SDomainConfiguration] :: {sName :: SSymbol dom " Domain name", sPeriod :: SNat period " Period of clock in /ps/", sActiveEdge :: SActiveEdge edge " Active edge of the clock (not yet implemented)", sResetKind :: SResetKind reset " Whether resets are synchronous (edge-sensitive) or asynchronous (level-sensitive)", sInitBehavior :: SInitBehavior init " Whether the initial (or "power up") value of memory elements is unknown/undefined, or configurable to a specific value", sResetPolarity :: SResetPolarity polarity " Whether resets are active high or active low"} -> SDomainConfiguration dom ('DomainConfiguration dom period edge reset init polarity)

-- | Convenience type to help to extract a period from a domain. Example
--   usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainPeriod dom ~ 6000) =&gt; ...
--   </pre>
type DomainPeriod (dom :: Domain) = DomainConfigurationPeriod (KnownConf dom)

-- | Convenience type to help to extract the active edge from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainActiveEdge dom ~ 'Rising) =&gt; ...
--   </pre>
type DomainActiveEdge (dom :: Domain) = DomainConfigurationActiveEdge (KnownConf dom)

-- | Convenience type to help to extract the reset synchronicity from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetKind dom ~ 'Synchronous) =&gt; ...
--   </pre>
type DomainResetKind (dom :: Domain) = DomainConfigurationResetKind (KnownConf dom)

-- | Convenience type to help to extract the initial value behavior from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainInitBehavior dom ~ 'Defined) =&gt; ...
--   </pre>
type DomainInitBehavior (dom :: Domain) = DomainConfigurationInitBehavior (KnownConf dom)

-- | Convenience type to help to extract the reset polarity from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetPolarity dom ~ 'ActiveHigh) =&gt; ...
--   </pre>
type DomainResetPolarity (dom :: Domain) = DomainConfigurationResetPolarity (KnownConf dom)

-- | Helper type family for <a>DomainPeriod</a>
type family DomainConfigurationPeriod (config :: DomainConfiguration) :: Nat

-- | Helper type family for <a>DomainActiveEdge</a>
type family DomainConfigurationActiveEdge (config :: DomainConfiguration) :: ActiveEdge

-- | Helper type family for <a>DomainResetKind</a>
type family DomainConfigurationResetKind (config :: DomainConfiguration) :: ResetKind

-- | Helper type family for <a>DomainInitBehavior</a>
type family DomainConfigurationInitBehavior (config :: DomainConfiguration) :: InitBehavior

-- | Helper type family for <a>DomainResetPolarity</a>
type family DomainConfigurationResetPolarity (config :: DomainConfiguration) :: ResetPolarity

-- | Convenience type to constrain a domain to have synchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasSynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasSynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Synchronous)

-- | Convenience type to constrain a domain to have asynchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasAsynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasAsynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Asynchronous)

-- | Convenience type to constrain a domain to have initial values. Example
--   usage:
--   
--   <pre>
--   myFunc :: HasDefinedInitialValues dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   Note that there is no <tt>UnknownInitialValues dom</tt> as a component
--   that works without initial values will also work if it does have them.
--   
--   <a>Click here for usage hints</a>
type HasDefinedInitialValues (dom :: Domain) = (KnownDomain dom, DomainInitBehavior dom ~ 'Defined)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type System = ("System" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and synchronously to
--   changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type XilinxSystem = ("XilinxSystem" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type IntelSystem = ("IntelSystem" :: Domain)

-- | Convenience value to allow easy "subclassing" of System domain. Should
--   be used in combination with <a>createDomain</a>. For example, if you
--   just want to change the period but leave all other settings intact
--   use:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
vSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of IntelSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vIntelSystem{vName="Intel10", vPeriod=10}
--   </pre>
vIntelSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of XilinxSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vXilinxSystem{vName="Xilinx10", vPeriod=10}
--   </pre>
vXilinxSystem :: VDomainConfiguration

-- | Same as SDomainConfiguration but allows for easy updates through
--   record update syntax. Should be used in combination with
--   <a>vDomain</a> and <a>createDomain</a>. Example:
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
data VDomainConfiguration
VDomainConfiguration :: String -> Natural -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> VDomainConfiguration

-- | Corresponds to <a>_name</a> on <a>DomainConfiguration</a>
[vName] :: VDomainConfiguration -> String

-- | Corresponds to <a>_period</a> on <a>DomainConfiguration</a>
[vPeriod] :: VDomainConfiguration -> Natural

-- | Corresponds to <a>_activeEdge</a> on <a>DomainConfiguration</a>
[vActiveEdge] :: VDomainConfiguration -> ActiveEdge

-- | Corresponds to <a>_resetKind</a> on <a>DomainConfiguration</a>
[vResetKind] :: VDomainConfiguration -> ResetKind

-- | Corresponds to <a>_initBehavior</a> on <a>DomainConfiguration</a>
[vInitBehavior] :: VDomainConfiguration -> InitBehavior

-- | Corresponds to <a>_resetPolarity</a> on <a>DomainConfiguration</a>
[vResetPolarity] :: VDomainConfiguration -> ResetPolarity

-- | Convert <a>SDomainConfiguration</a> to <a>VDomainConfiguration</a>.
--   Should be used in combination with <a>createDomain</a> only.
vDomain :: SDomainConfiguration dom conf -> VDomainConfiguration

-- | Convenience method to express new domains in terms of others.
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
--   
--   The function will create two extra identifiers. The first:
--   
--   <pre>
--   type System10 = ..
--   </pre>
--   
--   You can use that as the dom to Clocks/Resets/Enables/Signals. For
--   example: <tt>Signal System10 Int</tt>. Additionally, it will create a
--   <a>VDomainConfiguration</a> that you can use in later calls to
--   <a>createDomain</a>:
--   
--   <pre>
--   vSystem10 = knownVDomain @System10
--   </pre>
--   
--   It will also make <tt>System10</tt> an instance of <a>KnownDomain</a>.
--   
--   If either identifier is already in scope it will not be generated a
--   second time. Note: This can be useful for example when documenting a
--   new domain:
--   
--   <pre>
--   -- | Here is some documentation for CustomDomain
--   type CustomDomain = ("CustomDomain" :: Domain)
--   
--   -- | Here is some documentation for vCustomDomain
--   createDomain vSystem{vName="CustomDomain"}
--   </pre>
createDomain :: VDomainConfiguration -> Q [Dec]

-- | A clock signal belonging to a domain named <i>dom</i>.
data Clock (dom :: Domain)
Clock :: SSymbol dom -> Maybe (Signal dom Femtoseconds) -> Clock (dom :: Domain)

-- | Domain associated with the clock
[clockTag] :: Clock (dom :: Domain) -> SSymbol dom

-- | Periods of the clock. This is an experimental feature used to simulate
--   clock frequency correction mechanisms. Currently, all ways to contruct
--   such a clock are hidden from the public API.
[clockPeriods] :: Clock (dom :: Domain) -> Maybe (Signal dom Femtoseconds)

-- | The negative or inverted phase of a differential clock signal. HDL
--   generation will treat it the same as <a>Clock</a>, except that no
--   <tt>create_clock</tt> command is issued in the SDC file for
--   <a>ClockN</a>. Used in <a>DiffClock</a>.
newtype ClockN (dom :: Domain)
ClockN :: SSymbol dom -> ClockN (dom :: Domain)
[clockNTag] :: ClockN (dom :: Domain) -> SSymbol dom

-- | A differential clock signal belonging to a domain named <i>dom</i>.
--   The clock input of a design with such an input has two ports which are
--   in antiphase. The first input is the positive phase, the second the
--   negative phase. When using <a>makeTopEntity</a>, the names of the
--   inputs will end in <tt>_p</tt> and <tt>_n</tt> respectively.
--   
--   To create a differential clock in a test bench, you can use
--   <a>clockToDiffClock</a>.
data DiffClock (dom :: Domain)
DiffClock :: ("p" ::: Clock dom) -> ("n" ::: ClockN dom) -> DiffClock (dom :: Domain)

-- | Calculate the period in <b>ps</b>, given a frequency in <b>Hz</b>
--   
--   I.e., to calculate the clock period for a circuit to run at 240 MHz we
--   get
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod 240e6
--   4166
--   </pre>
--   
--   If the value <tt>hzToPeriod</tt> is applied to is not of the type
--   <a>Ratio</a> <a>Natural</a>, you can use <tt>hzToPeriod
--   (<a>realToFrac</a> f)</tt>. Note that if <tt>f</tt> is negative,
--   <tt>realToFrac</tt> will give an <tt><a>Underflow</a> ::
--   <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Natural</a>. To
--   get the old behavior of this function, use a type application:
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod @Natural 240e6
--   4166
--   </pre>
--   
--   <ul>
--   <li><b>NB</b>: This function is not synthesizable</li>
--   <li><b>NB</b>: This function is lossy. I.e., <tt>periodToHz .
--   hzToPeriod /= id</tt>.</li>
--   </ul>
hzToPeriod :: (HasCallStack, Integral a) => Ratio Natural -> a

-- | Calculate the frequency in <b>Hz</b>, given the period in <b>ps</b>
--   
--   I.e., to calculate the clock frequency of a clock with a period of
--   5000 ps:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz 5000
--   2.0e8
--   </pre>
--   
--   Note that if <tt>p</tt> in <tt>periodToHz (<a>fromIntegral</a> p)</tt>
--   is negative, <tt>fromIntegral</tt> will give an <tt><a>Underflow</a>
--   :: <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Ratio</a>
--   <a>Natural</a>. To get the old behavior of this function, use a type
--   application:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz @(Ratio Natural) 5000
--   200000000 % 1
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
periodToHz :: (HasCallStack, Fractional a) => Natural -> a
data ClockAB

-- | Clock edge A produced
ClockA :: ClockAB

-- | Clock edge B produced
ClockB :: ClockAB

-- | Clock edges coincided
ClockAB :: ClockAB

-- | Given two clocks, produce a list of clock ticks indicating which clock
--   (or both) ticked. Can be used in components handling multiple clocks,
--   such as <tt>unsafeSynchronizer</tt> or dual clock FIFOs.
--   
--   If your primitive does not care about coincided clock edges, it should
--   - by convention - replace it by <tt>ClockB:ClockA:</tt>.
clockTicks :: (KnownDomain domA, KnownDomain domB) => Clock domA -> Clock domB -> [ClockAB]

-- | Given two clock periods, produce a list of clock ticks indicating
--   which clock (or both) ticked. Can be used in components handling
--   multiple clocks, such as <tt>unsafeSynchronizer</tt> or dual clock
--   FIFOs.
--   
--   If your primitive does not care about coincided clock edges, it should
--   - by convention - replace it by <tt>ClockB:ClockA:</tt>.
clockTicksEither :: Either Int64 (Signal domA Int64) -> Either Int64 (Signal domB Int64) -> [ClockAB]

-- | A signal of booleans, indicating whether a component is enabled. No
--   special meaning is implied, it's up to the component itself to decide
--   how to respond to its enable line. It is used throughout Clash as a
--   global enable signal.
data Enable dom
Enable :: Signal dom Bool -> Enable dom

-- | Convert a signal of bools to an <a>Enable</a> construct
toEnable :: Signal dom Bool -> Enable dom

-- | Convert <a>Enable</a> construct to its underlying representation: a
--   signal of bools.
fromEnable :: Enable dom -> Signal dom Bool

-- | Enable generator for some domain. Is simply always True.
enableGen :: Enable dom

-- | A reset signal belonging to a domain called <i>dom</i>.
--   
--   The underlying representation of resets is <a>Bool</a>.
data Reset (dom :: Domain)
Reset :: Signal dom Bool -> Reset (dom :: Domain)

-- | <a>unsafeToReset</a> is unsafe. For asynchronous resets it is unsafe
--   because it can introduce combinatorial loops. In case of synchronous
--   resets it can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeFromActiveLow</a> or
--   <a>unsafeFromActiveHigh</a>.
unsafeToReset :: KnownDomain dom => Signal dom Bool -> Reset dom

-- | <a>unsafeFromReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeToActiveLow</a> or
--   <a>unsafeToActiveHigh</a>.
unsafeFromReset :: Reset dom -> Signal dom Bool

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveHigh :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveLow :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveHigh :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveLow :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Invert reset signal
invertReset :: KnownDomain dom => Reset dom -> Reset dom
delay# :: forall dom a. (KnownDomain dom, NFDataX a) => Clock dom -> Enable dom -> a -> Signal dom a -> Signal dom a

-- | A register with a power up and reset value. Power up values are not
--   supported on all platforms, please consult the manual of your target
--   platform and check the notes below.
--   
--   Xilinx: power up values and reset values MUST be the same. If they are
--   not, the Xilinx tooling <b>will ignore the reset value</b> and use the
--   power up value instead. Source: MIA
--   
--   Intel: power up values and reset values MUST be the same. If they are
--   not, the Intel tooling <b>will ignore the power up value</b> and use
--   the reset value instead. Source:
--   <a>https://www.intel.com/content/www/us/en/programmable/support/support-resources/knowledge-base/solutions/rd01072011_91.html</a>
register# :: forall dom a. (KnownDomain dom, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> a -> a -> Signal dom a -> Signal dom a

-- | Version of <a>register#</a> that simulates a register on an
--   asynchronous domain. Is synthesizable.
asyncRegister# :: forall dom a. (KnownDomain dom, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> a -> a -> Signal dom a -> Signal dom a

-- | Version of <a>register#</a> that simulates a register on a synchronous
--   domain. Not synthesizable.
syncRegister# :: forall dom a. (KnownDomain dom, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> a -> a -> Signal dom a -> Signal dom a

-- | Acts like <a>id</a> if given domain allows powerup values, but returns
--   a value constructed with <a>deepErrorX</a> otherwise.
registerPowerup# :: forall dom a. (KnownDomain dom, NFDataX a, HasCallStack) => Clock dom -> a -> a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>mux</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a
--   </pre>
--   
--   A multiplexer. Given "<tt><a>mux</a> b t f</tt>", output <tt>t</tt>
--   when <tt>b</tt> is <a>True</a>, and <tt>f</tt> when <tt>b</tt> is
--   <a>False</a>.
mux :: Applicative f => f Bool -> f a -> f a -> f a

-- | Clock generator for simulations. Do <b>not</b> use this clock
--   generator for the <i>testBench</i> function, use <a>tbClockGen</a>
--   instead.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem = clockGen @System
--   </pre>
--   
--   See <a>DomainConfiguration</a> for more information on how to use
--   synthesis domains.
clockGen :: KnownDomain dom => Clock dom

-- | Clock generator to be used in the <i>testBench</i> function.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem en = tbClockGen @System en
--   </pre>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   module Example where
--   
--   import <a>Clash.Explicit.Prelude</a>
--   import <a>Clash.Explicit.Testbench</a>
--   
--   -- Fast domain: twice as fast as "Slow"
--   <a>createDomain</a> <a>vSystem</a>{vName="Fast", vPeriod=10}
--   
--   -- Slow domain: twice as slow as "Fast"
--   <a>createDomain</a> <a>vSystem</a>{vName="Slow", vPeriod=20}
--   
--   topEntity
--     :: <a>Clock</a> "Fast"
--     -&gt; <a>Reset</a> "Fast"
--     -&gt; <a>Enable</a> "Fast"
--     -&gt; <a>Clock</a> "Slow"
--     -&gt; <a>Signal</a> "Fast" (Unsigned 8)
--     -&gt; <a>Signal</a> "Slow" (Unsigned 8, Unsigned 8)
--   topEntity clk1 rst1 en1 clk2 i =
--     let h = register clk1 rst1 en1 0 (register clk1 rst1 en1 0 i)
--         l = register clk1 rst1 en1 0 i
--     in  unsafeSynchronizer clk1 clk2 (bundle (h, l))
--   
--   testBench
--     :: <a>Signal</a> "Slow" Bool
--   testBench = done
--     where
--       testInput      = <a>stimuliGenerator</a> clkA1 rstA1 $(<a>listToVecTH</a> [1::Unsigned 8,2,3,4,5,6,7,8])
--       expectedOutput = <a>outputVerifier</a>   clkB2 rstB2 $(<a>listToVecTH</a> [(0,0) :: (Unsigned 8, Unsigned 8),(1,2),(3,4),(5,6),(7,8)])
--       done           = expectedOutput (topEntity clkA1 rstA1 enableGen clkB2 testInput)
--       notDone        = not &lt;$&gt; done
--       clkA1          = <a>tbClockGen</a> @"Fast" (unsafeSynchronizer clkB2 clkA1 notDone)
--       clkB2          = <a>tbClockGen</a> @"Slow" notDone
--       rstA1          = <a>resetGen</a> @"Fast"
--       rstB2          = <a>resetGen</a> @"Slow"
--   </pre>
tbClockGen :: KnownDomain testDom => Signal testDom Bool -> Clock testDom

-- | Femtoseconds expressed as an <a>Int64</a>. Is a newtype to prevent
--   accidental mixups with picoseconds - the unit used in
--   <a>DomainConfiguration</a>.
newtype Femtoseconds
Femtoseconds :: Int64 -> Femtoseconds

-- | Calculate the frequency in <b>Hz</b>, given the period in <b>fs</b>
--   
--   I.e., to calculate the clock frequency of a clock with a period of
--   5000 fs:
--   
--   <pre>
--   &gt;&gt;&gt; fsToHz (Femtoseconds 5000)
--   2.0e11
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fsToHz :: (HasCallStack, Fractional a) => Femtoseconds -> a

-- | Calculate the period in <b>fs</b>, given a frequency in <b>Hz</b>
--   
--   I.e., to calculate the clock period for a circuit to run at 240 MHz we
--   get
--   
--   <pre>
--   &gt;&gt;&gt; hzToFs 240e6
--   Femtoseconds 4166666
--   </pre>
--   
--   If the value <tt>hzToFs</tt> is applied to is not of the type
--   <a>Ratio</a> <a>Natural</a>, you can use <tt>hzToFs (<a>realToFrac</a>
--   f)</tt>. Note that if <tt>f</tt> is negative, <tt>realToFrac</tt> will
--   give an <tt><a>Underflow</a> :: <a>ArithException</a></tt> without a
--   call stack, making debugging cumbersome.
--   
--   <ul>
--   <li><b>NB</b>: This function is not synthesizable</li>
--   <li><b>NB</b>: This function is lossy. I.e., <tt>fsToHz . hzToFs /=
--   id</tt>.</li>
--   </ul>
hzToFs :: HasCallStack => Ratio Natural -> Femtoseconds

-- | Strip newtype wrapper <a>Femtoseconds</a>
unFemtoseconds :: Femtoseconds -> Int64

-- | Map <a>Int64</a> fields in <a>Femtoseconds</a>
mapFemtoseconds :: (Int64 -> Int64) -> Femtoseconds -> Femtoseconds

-- | Clock generator with dynamic clock periods for simulations. This is an
--   experimental feature and hence not part of the public API. Like
--   <a>tbClockGen</a>
--   
--   To be used like:
--   
--   <pre>
--   clkSystem = dynamicClockGen @System
--   </pre>
--   
--   See <a>DomainConfiguration</a> for more information on how to use
--   synthesis domains.
tbDynamicClockGen :: KnownDomain dom => Signal dom Femtoseconds -> Signal dom Bool -> Clock dom

-- | Clock generator with dynamic clock periods for simulations. This is an
--   experimental feature and hence not part of the public API.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem = dynamicClockGen @System
--   </pre>
--   
--   See <a>DomainConfiguration</a> for more information on how to use
--   synthesis domains.
dynamicClockGen :: KnownDomain dom => Signal dom Femtoseconds -> Clock dom

-- | Reset generator for simulation purposes. Asserts the reset for a
--   single cycle.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem = resetGen @System
--   </pre>
--   
--   See <a>tbClockGen</a> for example usage.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGen :: forall dom. KnownDomain dom => Reset dom

-- | Reset generator for simulation purposes. Asserts the reset for the
--   first <i>n</i> cycles.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem5 = resetGen @System d5
--   </pre>
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (unsafeToActiveHigh (resetGenN @System d3))
--   [True,True,True,False,False,False,False]
--   </pre>
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGenN :: forall dom n. (KnownDomain dom, 1 <= n) => SNat n -> Reset dom

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&amp;&amp;.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&amp;&amp;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.&&.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 3 .&&.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.||.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>||</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.||.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 2 .||.

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen resetGen enableGen 8) [1, 1, 2, 3]
--   [8,8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulate :: (NFDataX a, NFDataX b) => (Signal dom1 a -> Signal dom2 b) -> [a] -> [b]

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen resetGen enableGen 8) [1, 1, 2, 3]
--   [8,8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulate_lazy :: (Signal dom1 a -> Signal dom2 b) -> [a] -> [b]

-- | Build an <a>Automaton</a> from a function over <a>Signal</a>s.
--   
--   <b>NB</b>: Consumption of continuation of the <a>Automaton</a> must be
--   affine; that is, you can only apply the continuation associated with a
--   particular element at most once.
signalAutomaton :: forall dom a b. (Signal dom a -> Signal dom b) -> Automaton (->) a b

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sample :: (Foldable f, NFDataX a) => f a -> [a]

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sampleN :: (Foldable f, NFDataX a) => Int -> f a -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList :: NFDataX a => [a] -> Signal dom a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sample_lazy :: Foldable f => f a -> [a]

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sampleN_lazy :: Foldable f => Int -> f a -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5] :: Signal System Int)
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList_lazy :: [a] -> Signal dom a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>testFor</b> :: <a>Int</a> -&gt; <a>Signal</a> Bool -&gt; <a>Property</a>
--   </pre>
--   
--   <tt>testFor n s</tt> tests the signal <tt>s</tt> for <tt>n</tt>
--   cycles.
--   
--   <b>NB</b>: This function is not synthesizable
testFor :: Foldable f => Int -> f Bool -> Property

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.==.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>==</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.==.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 .==.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(./=.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>/=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(./=.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 ./=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>.
mapSignal# :: forall a b dom. (a -> b) -> Signal dom a -> Signal dom b
signal# :: a -> Signal dom a
appSignal# :: Signal dom (a -> b) -> Signal dom a -> Signal dom b

-- | <b>NB</b>: Not synthesizable
--   
--   <b>NB</b>: In "<tt><a>foldr#</a> f z s</tt>":
--   
--   <ul>
--   <li>The function <tt>f</tt> should be <i>lazy</i> in its second
--   argument.</li>
--   <li>The <tt>z</tt> element will never be used.</li>
--   </ul>
foldr# :: (a -> b -> b) -> b -> Signal dom a -> b
traverse# :: Applicative f => (a -> f b) -> Signal dom a -> f (Signal dom b)

-- | <b>WARNING: EXTREMELY EXPERIMENTAL</b>
--   
--   The circuit semantics of this operation are unclear and/or
--   non-existent. There is a good reason there is no <a>Monad</a> instance
--   for <a>Signal</a>.
--   
--   Is currently treated as <a>id</a> by the Clash compiler.
joinSignal# :: Signal dom (Signal dom a) -> Signal dom a

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromHighPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromLowPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToHighPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToLowPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool
instance Data.Binary.Class.Binary Clash.Signal.Internal.ActiveEdge
instance Data.Hashable.Class.Hashable Clash.Signal.Internal.ActiveEdge
instance Data.Data.Data Clash.Signal.Internal.ActiveEdge
instance Control.DeepSeq.NFData Clash.Signal.Internal.ActiveEdge
instance GHC.Generics.Generic Clash.Signal.Internal.ActiveEdge
instance GHC.Classes.Ord Clash.Signal.Internal.ActiveEdge
instance GHC.Classes.Eq Clash.Signal.Internal.ActiveEdge
instance GHC.Read.Read Clash.Signal.Internal.ActiveEdge
instance GHC.Show.Show Clash.Signal.Internal.ActiveEdge
instance Data.Binary.Class.Binary Clash.Signal.Internal.ResetKind
instance Data.Hashable.Class.Hashable Clash.Signal.Internal.ResetKind
instance Data.Data.Data Clash.Signal.Internal.ResetKind
instance Control.DeepSeq.NFData Clash.Signal.Internal.ResetKind
instance GHC.Generics.Generic Clash.Signal.Internal.ResetKind
instance GHC.Classes.Ord Clash.Signal.Internal.ResetKind
instance GHC.Classes.Eq Clash.Signal.Internal.ResetKind
instance GHC.Read.Read Clash.Signal.Internal.ResetKind
instance GHC.Show.Show Clash.Signal.Internal.ResetKind
instance Data.Binary.Class.Binary Clash.Signal.Internal.ResetPolarity
instance Data.Hashable.Class.Hashable Clash.Signal.Internal.ResetPolarity
instance Data.Data.Data Clash.Signal.Internal.ResetPolarity
instance Control.DeepSeq.NFData Clash.Signal.Internal.ResetPolarity
instance GHC.Generics.Generic Clash.Signal.Internal.ResetPolarity
instance GHC.Read.Read Clash.Signal.Internal.ResetPolarity
instance GHC.Show.Show Clash.Signal.Internal.ResetPolarity
instance GHC.Classes.Ord Clash.Signal.Internal.ResetPolarity
instance GHC.Classes.Eq Clash.Signal.Internal.ResetPolarity
instance Data.Binary.Class.Binary Clash.Signal.Internal.InitBehavior
instance Data.Hashable.Class.Hashable Clash.Signal.Internal.InitBehavior
instance Data.Data.Data Clash.Signal.Internal.InitBehavior
instance Control.DeepSeq.NFData Clash.Signal.Internal.InitBehavior
instance GHC.Generics.Generic Clash.Signal.Internal.InitBehavior
instance GHC.Classes.Ord Clash.Signal.Internal.InitBehavior
instance GHC.Classes.Eq Clash.Signal.Internal.InitBehavior
instance GHC.Read.Read Clash.Signal.Internal.InitBehavior
instance GHC.Show.Show Clash.Signal.Internal.InitBehavior
instance Data.Binary.Class.Binary Clash.Signal.Internal.VDomainConfiguration
instance GHC.Read.Read Clash.Signal.Internal.VDomainConfiguration
instance GHC.Show.Show Clash.Signal.Internal.VDomainConfiguration
instance Control.DeepSeq.NFData Clash.Signal.Internal.VDomainConfiguration
instance GHC.Generics.Generic Clash.Signal.Internal.VDomainConfiguration
instance GHC.Classes.Eq Clash.Signal.Internal.VDomainConfiguration
instance GHC.Classes.Ord Clash.Signal.Internal.Femtoseconds
instance Language.Haskell.TH.Syntax.Lift Clash.Signal.Internal.Femtoseconds
instance Control.DeepSeq.NFData Clash.Signal.Internal.Femtoseconds
instance Clash.XException.NFDataX Clash.Signal.Internal.Femtoseconds
instance GHC.Generics.Generic Clash.Signal.Internal.Femtoseconds
instance GHC.Classes.Eq Clash.Signal.Internal.Femtoseconds
instance GHC.Show.Show Clash.Signal.Internal.Femtoseconds
instance Clash.XException.NFDataX Clash.Signal.Internal.ClockAB
instance Control.DeepSeq.NFData Clash.Signal.Internal.ClockAB
instance GHC.Show.Show Clash.Signal.Internal.ClockAB
instance GHC.Classes.Eq Clash.Signal.Internal.ClockAB
instance GHC.Generics.Generic Clash.Signal.Internal.ClockAB
instance GHC.Show.Show (Clash.Signal.Internal.SDomainConfiguration dom conf)
instance GHC.Show.Show (Clash.Signal.Internal.DiffClock dom)
instance GHC.Show.Show (Clash.Signal.Internal.Clock dom)
instance GHC.Show.Show (Clash.Signal.Internal.ClockN dom)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Signal.Internal.Signal dom a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Signal.Internal.Signal dom a)
instance Data.Default.Class.Default a => Data.Default.Class.Default (Clash.Signal.Internal.Signal dom a)
instance GHC.Base.Functor (Clash.Signal.Internal.Signal dom)
instance GHC.Base.Applicative (Clash.Signal.Internal.Signal dom)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Clash.Signal.Internal.Signal domain a)
instance GHC.Num.Num a => GHC.Num.Num (Clash.Signal.Internal.Signal dom a)
instance Data.Foldable.Foldable (Clash.Signal.Internal.Signal dom)
instance Data.Traversable.Traversable (Clash.Signal.Internal.Signal dom)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Clash.Signal.Internal.Signal dom a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Signal.Internal.Signal dom a)
instance Test.QuickCheck.Arbitrary.CoArbitrary a => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Signal.Internal.Signal dom a)
instance Clash.Signal.Internal.KnownDomain Clash.Signal.Internal.System
instance Clash.Signal.Internal.KnownDomain Clash.Signal.Internal.XilinxSystem
instance Clash.Signal.Internal.KnownDomain Clash.Signal.Internal.IntelSystem
instance GHC.Show.Show (Clash.Signal.Internal.SInitBehavior init)
instance GHC.Show.Show (Clash.Signal.Internal.SResetPolarity polarity)
instance GHC.Show.Show (Clash.Signal.Internal.SResetKind reset)
instance GHC.Show.Show (Clash.Signal.Internal.SActiveEdge edge)


-- | Verification
module Clash.Verification.Internal

-- | A result of some property. Besides carrying the actual boolean result,
--   it carries some properties used to make reports.
data AssertionResult
AssertionResult :: !String -> !Bool -> AssertionResult

-- | Name of property belonging to this result
[cvPropName] :: AssertionResult -> !String

-- | False whenever property is violated, True otherwise
[cvPass] :: AssertionResult -> !Bool

-- | A property is a temporal or basic assertion that's specified to either
--   used as an _assert_ or _cover_ statement. See <a>assert</a> and
--   <a>cover</a>.
newtype Property (dom :: Domain)
Property :: Property' (Maybe Text, Signal dom Bool) -> Property (dom :: Domain)
data Assertion (dom :: Domain)
Assertion :: IsTemporal -> Assertion' (Maybe Text, Signal dom Bool) -> Assertion (dom :: Domain)

-- | Render target for HDL
data RenderAs

-- | Property Specification Language
PSL :: RenderAs

-- | SystemVerilog Assertions
SVA :: RenderAs

-- | Use SVA for SystemVerilog, PSL for others
AutoRenderAs :: RenderAs

-- | Yosys Formal Extensions for Verilog and SystemVerilog. See:
--   <a>https://symbiyosys.readthedocs.io/en/latest/verilog.html</a> and
--   <a>https://symbiyosys.readthedocs.io/en/latest/verific.html</a>
--   
--   Falls back to PSL for VHDL, however currently Clash's PSL syntax isn't
--   suported by GHDL+SymbiYosys;
YosysFormal :: RenderAs
data IsTemporal
IsNotTemporal :: IsTemporal
IsTemporal :: IsTemporal

-- | An AssertionValue is a bool-like value or stream that can be used in
--   property specifications. Clash implements two: a stream of booleans
--   (Signal dom Bool), and the result of a property expression (Assertion
--   dom).
class AssertionValue dom a | a -> dom

-- | Convert given type into a Assertion.
toAssertionValue :: AssertionValue dom a => a -> Assertion dom

-- | Internal version of <a>Assertion</a>.
data Assertion' a

-- | (Bootstrapping) signal of booleans
CvPure :: a -> Assertion' a

-- | Tag to force a non-temporal assertion to a temporal one
CvToTemporal :: Assertion' a -> Assertion' a

-- | Boolean literal
CvLit :: Bool -> Assertion' a

-- | Logical not
CvNot :: Assertion' a -> Assertion' a

-- | Logical and
CvAnd :: Assertion' a -> Assertion' a -> Assertion' a

-- | Logical or
CvOr :: Assertion' a -> Assertion' a -> Assertion' a

-- | Logical implies
CvImplies :: Assertion' a -> Assertion' a -> Assertion' a

-- | Moves start point of assertion <i>n</i> cycles forward
CvNext :: Word -> Assertion' a -> Assertion' a

-- | Before <tt>CvBefore a b</tt> is the same as <tt>CvAnd a (CvNext 1
--   b)</tt>
CvBefore :: Assertion' a -> Assertion' a -> Assertion' a

-- | Temporal implies <tt>CvTemporalImplies n a b</tt>:
--   
--   n | n == 0 -&gt; same as <tt>CvImplies a b</tt> | otherwise -&gt; same
--   as <tt>CvImplies a (CvNextN n b)</tt>
CvTemporalImplies :: Word -> Assertion' a -> Assertion' a -> Assertion' a

-- | Assertion should _always_ hold
CvAlways :: Assertion' a -> Assertion' a

-- | Assertion should _never_ hold (not supported by SVA)
CvNever :: Assertion' a -> Assertion' a

-- | Assertion should _eventually_ hold
CvEventually :: Assertion' a -> Assertion' a

-- | Internal version of <a>Property</a>. All user facing will instantiate
--   <tt>a</tt> with <tt>(Maybe Text, Signal dom Bool)</tt>. Blackboxes
--   will instantiate it with <tt>(Maybe Text, Term)</tt> instead.
data Property' a
CvAssert :: Assertion' a -> Property' a
CvCover :: Assertion' a -> Property' a
CvAssume :: Assertion' a -> Property' a
toTemporal :: Assertion dom -> Assertion' (Maybe Text, Signal dom Bool)
isTemporal :: Assertion dom -> IsTemporal
assertion :: Assertion dom -> Assertion' (Maybe Text, Signal dom Bool)
instance GHC.Classes.Eq Clash.Verification.Internal.RenderAs
instance GHC.Show.Show Clash.Verification.Internal.RenderAs
instance GHC.Classes.Ord Clash.Verification.Internal.IsTemporal
instance GHC.Classes.Eq Clash.Verification.Internal.IsTemporal
instance Data.Traversable.Traversable Clash.Verification.Internal.Assertion'
instance Data.Foldable.Foldable Clash.Verification.Internal.Assertion'
instance GHC.Base.Functor Clash.Verification.Internal.Assertion'
instance GHC.Show.Show a => GHC.Show.Show (Clash.Verification.Internal.Assertion' a)
instance Data.Traversable.Traversable Clash.Verification.Internal.Property'
instance Data.Foldable.Foldable Clash.Verification.Internal.Property'
instance GHC.Base.Functor Clash.Verification.Internal.Property'
instance GHC.Show.Show a => GHC.Show.Show (Clash.Verification.Internal.Property' a)
instance GHC.Classes.Eq Clash.Verification.Internal.AssertionResult
instance Clash.Verification.Internal.AssertionValue dom (Clash.Signal.Internal.Signal dom GHC.Types.Bool)
instance Clash.Verification.Internal.AssertionValue dom (Clash.Verification.Internal.Assertion dom)

module Clash.Signal.Internal.Ambiguous

-- | Like 'knownDomain but yields a <a>VDomainConfiguration</a>. Should
--   only be used in combination with <a>createDomain</a>.
knownVDomain :: forall dom. KnownDomain dom => VDomainConfiguration

-- | Get the clock period from a KnownDomain context
clockPeriod :: forall dom period. (KnownDomain dom, DomainPeriod dom ~ period) => SNat period

-- | Get <a>ActiveEdge</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case activeEdge @dom of
--       SRising -&gt; foo
--       SFalling -&gt; bar
--   </pre>
activeEdge :: forall dom edge. (KnownDomain dom, DomainActiveEdge dom ~ edge) => SActiveEdge edge

-- | Get <a>ResetKind</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetKind @dom of
--       SAsynchronous -&gt; foo
--       SSynchronous -&gt; bar
--   </pre>
resetKind :: forall dom sync. (KnownDomain dom, DomainResetKind dom ~ sync) => SResetKind sync

-- | Get <a>InitBehavior</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case initBehavior @dom of
--       SDefined -&gt; foo
--       SUnknown -&gt; bar
--   </pre>
initBehavior :: forall dom init. (KnownDomain dom, DomainInitBehavior dom ~ init) => SInitBehavior init

-- | Get <a>ResetPolarity</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetPolarity @dom of
--       SActiveHigh -&gt; foo
--       SActiveLow -&gt; bar
--   </pre>
resetPolarity :: forall dom polarity. (KnownDomain dom, DomainResetPolarity dom ~ polarity) => SResetPolarity polarity


-- | Verification primitives for Clash. Currently implements PSL (Property
--   Specification Language) and SVA (SystemVerilog Assertions). For a good
--   overview of PSL and an introduction to the concepts of property
--   checking, read
--   <a>https://standards.ieee.org/standard/62531-2012.html</a>.
--   
--   The verification API is currently experimental and subject to change.
module Clash.Explicit.Verification
data Assertion (dom :: Domain)

-- | A property is a temporal or basic assertion that's specified to either
--   used as an _assert_ or _cover_ statement. See <a>assert</a> and
--   <a>cover</a>.
data Property (dom :: Domain)

-- | An AssertionValue is a bool-like value or stream that can be used in
--   property specifications. Clash implements two: a stream of booleans
--   (Signal dom Bool), and the result of a property expression (Assertion
--   dom).
class AssertionValue dom a | a -> dom

-- | Render target for HDL
data RenderAs

-- | Property Specification Language
PSL :: RenderAs

-- | SystemVerilog Assertions
SVA :: RenderAs

-- | Use SVA for SystemVerilog, PSL for others
AutoRenderAs :: RenderAs

-- | Yosys Formal Extensions for Verilog and SystemVerilog. See:
--   <a>https://symbiyosys.readthedocs.io/en/latest/verilog.html</a> and
--   <a>https://symbiyosys.readthedocs.io/en/latest/verific.html</a>
--   
--   Falls back to PSL for VHDL, however currently Clash's PSL syntax isn't
--   suported by GHDL+SymbiYosys;
YosysFormal :: RenderAs

-- | Convert a signal to a cv expression with a name hint. Clash will try
--   its best to use this name in the rendered assertion, but might run
--   into collisions. You can skip using <a>name</a> altogether. Clash will
--   then try its best to get a readable name from context.
name :: Text -> Signal dom Bool -> Assertion dom

-- | For using a literal (either True or False) in assertions
lit :: Bool -> Assertion dom

-- | Truth table for <a>not</a>:
--   
--   <pre>
--   a     | not a
--   ------------
--   True  | False
--   False | True
--   </pre>
not :: AssertionValue dom a => a -> Assertion dom

-- | Truth table for <a>and</a>:
--   
--   <pre>
--   a     | b     | a `and` b
--   --------------|----------
--   False | False | False
--   False | True  | False
--   True  | False | False
--   True  | True  | True
--   </pre>
and :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Truth table for <a>or</a>:
--   
--   <pre>
--   a     | b     | a `or` b
--   --------------|---------
--   False | False | False
--   False | True  | True
--   True  | False | True
--   True  | True  | True
--   </pre>
or :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Truth table for <a>implies</a>:
--   
--   <pre>
--   a     | b     | a `implies` b
--   --------------|--------------
--   False | False | True
--   False | True  | True
--   True  | False | False
--   True  | True  | True
--   </pre>
implies :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Truth table for <a>next</a>:
--   
--   <pre>
--   a[n]  | a[n+1] | a `implies` next a
--   ---------------|-------------------
--   False | False  | True
--   False | True   | True
--   True  | False  | False
--   True  | True   | True
--   </pre>
--   
--   where a[n] represents the value of <tt>a</tt> at cycle <tt>n</tt> and
--   <tt>a[n+1]</tt> represents the value of <tt>a</tt> at cycle
--   <tt>n+1</tt>. Cycle n is an arbitrary cycle.
next :: AssertionValue dom a => a -> Assertion dom

-- | Truth table for <a>nextN</a>:
--   
--   <pre>
--   a[n]  | a[n+m] | a `implies` next m a
--   ---------------|---------------------
--   False | False  | True
--   False | True   | True
--   True  | False  | False
--   True  | True   | True
--   </pre>
--   
--   where a[n] represents the value of <tt>a</tt> at cycle <tt>n</tt> and
--   a[n+m] represents the value of <tt>a</tt> at cycle <tt>n+m</tt>. Cycle
--   n is an arbitrary cycle.
nextN :: AssertionValue dom a => Word -> a -> Assertion dom

-- | Same as <tt>a &amp;&amp; next b</tt> but with a nice syntax. E.g.,
--   <tt>a &amp;&amp; next b</tt> could be written as <tt>a <a>before</a>
--   b</tt>. Might be read as "a happens one cycle before b".
before :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Same as <tt>a <a>implies</a> next b</tt> but with a nice syntax. E.g.,
--   <tt>a <a>implies</a> next b</tt> could be written as <tt>a
--   <a>timplies</a> b</tt>. Might be read as "a at cycle n implies b at
--   cycle n+1".
timplies :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Same as <a>implies</a> but strictly temporal.
timpliesOverlapping :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Specify assertion should _always_ hold
always :: AssertionValue dom a => a -> Assertion dom

-- | Specify assertion should _never_ hold (not supported by SVA)
never :: AssertionValue dom a => a -> Assertion dom

-- | Specify assertion should _eventually_ hold
eventually :: AssertionValue dom a => a -> Assertion dom

-- | Check whether given assertion always holds. Results can be collected
--   with <a>check</a>.
assert :: AssertionValue dom a => a -> Property dom

-- | Check whether given assertion holds for at least a single cycle.
--   Results can be collected with <a>check</a>.
cover :: AssertionValue dom a => a -> Property dom

-- | Inform the prover that this property is true. This is the same as
--   <a>assert</a> for simulations.
assume :: AssertionValue dom a => a -> Property dom

-- | Print property as PSL/SVA in HDL. Clash simulation support not yet
--   implemented.
check :: KnownDomain dom => Clock dom -> Reset dom -> Text -> RenderAs -> Property dom -> Signal dom AssertionResult

-- | Same as <a>check</a>, but doesn't require a design to explicitly
--   carried to top-level.
checkI :: KnownDomain dom => Clock dom -> Reset dom -> Text -> RenderAs -> Property dom -> Signal dom a -> Signal dom a

-- | Print assertions in HDL
hideAssertion :: Signal dom AssertionResult -> Signal dom a -> Signal dom a


module Clash.Signal.Delayed.Internal

-- | A synchronized signal with samples of type <tt>a</tt>, synchronized to
--   clock <tt>clk</tt>, that has accumulated <tt>delay</tt> amount of
--   samples delay along its path.
--   
--   DSignal has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i DSignal
--   type role DSignal nominal nominal representational
--   ...
--   </pre>
--   
--   as it is safe to coerce the values in the signal, but not safe to
--   coerce the synthesis domain or delay in the signal.
newtype DSignal (dom :: Domain) (delay :: Nat) a
DSignal :: Signal dom a -> DSignal (dom :: Domain) (delay :: Nat) a

-- | Strip a <a>DSignal</a> of its delay information.
[toSignal] :: DSignal (dom :: Domain) (delay :: Nat) a -> Signal dom a

-- | Feed the delayed result of a function back to its input:
--   
--   <pre>
--   mac
--     :: forall dom
--      . KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--   mac clk rst en x y = <a>feedback</a> (mac' x y)
--     where
--       mac'
--         :: <a>DSignal</a> dom 0 Int
--         -&gt; <a>DSignal</a> dom 0 Int
--         -&gt; <a>DSignal</a> dom 0 Int
--         -&gt; (<a>DSignal</a> dom 0 Int, <a>DSignal</a> dom 1 Int)
--       mac' a b acc = let acc' = a * b + acc
--                      in  (acc, <a>delayedI</a> clk rst en 0 acc')
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (toSignal (mac systemClockGen systemResetGen enableGen (dfromList [0..]) (dfromList [0..])))
--   [0,0,1,5,14,30,55]
--   </pre>
feedback :: (DSignal dom n a -> (DSignal dom n a, DSignal dom ((n + m) + 1) a)) -> DSignal dom n a

-- | <a>Signal</a>s are not delayed
fromSignal :: Signal dom a -> DSignal dom 0 a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (toSignal (dfromList [1,2,3,4,5]))
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
dfromList :: NFDataX a => [a] -> DSignal dom 0 a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (toSignal (dfromList [1,2,3,4,5]))
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
dfromList_lazy :: [a] -> DSignal dom 0 a

-- | <b>EXPERIMENTAL</b>
--   
--   <b>Unsafely</b> convert a <a>Signal</a> to a <a>DSignal</a> with an
--   arbitrary <tt>delay</tt>.
--   
--   <b>NB</b>: Should only be used to interface with functions specified
--   in terms of <a>Signal</a>.
unsafeFromSignal :: Signal dom a -> DSignal dom n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal from the future in the present. Often
--   required When writing a circuit that requires feedback from itself.
--   
--   <pre>
--   mac
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--   mac clk rst en x y = acc'
--     where
--       acc' = (x * y) + <a>antiDelay</a> d1 acc
--       acc  = <a>delayedI</a> clk rst en 0 acc'
--   </pre>
antiDelay :: SNat d -> DSignal dom (n + d) a -> DSignal dom n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal from the past in the present. In
--   contrast with <a>delayed</a> and friends forward does not insert any
--   logic. This means using this function violates the delay invariant of
--   <a>DSignal</a>. This is sometimes useful when combining unrelated
--   delayed signals where inserting logic is not wanted or when
--   abstracting over internal delayed signals where the internal delay
--   information should not be leaked.
--   
--   For example, the circuit below returns a sequence of numbers as a pair
--   but the internal delay information between the elements of the pair
--   should not leak into the type.
--   
--   <pre>
--   numbers
--     :: forall dom
--      . KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 5 (Int, Int)
--   numbers clk rst en = DB.bundle (forward d1 s1, s2)
--     where
--       s1 :: <a>DSignal</a> dom 4 Int
--       s1 = <a>delayed</a> clk rst en (100 :&gt; 10 :&gt; 5 :&gt; 1 :&gt; Nil) (pure 200)
--       s2 :: <a>DSignal</a> dom 5 Int
--       s2 = fmap (2*) $ <a>delayN</a> d1 0 en clk s1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 8 (toSignal (numbers systemClockGen systemResetGen enableGen))
--   [(1,0),(1,2),(5,2),(10,10),(100,20),(200,200),(200,400),(200,400)]
--   </pre>
forward :: SNat d -> DSignal dom n a -> DSignal dom (n + d) a
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Signal.Delayed.Internal.DSignal dom delay a)
instance Test.QuickCheck.Arbitrary.CoArbitrary a => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Signal.Delayed.Internal.DSignal dom delay a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Signal.Delayed.Internal.DSignal dom delay a)
instance Data.Traversable.Traversable (Clash.Signal.Delayed.Internal.DSignal dom delay)
instance Data.Foldable.Foldable (Clash.Signal.Delayed.Internal.DSignal dom delay)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Clash.Signal.Delayed.Internal.DSignal dom delay a)
instance GHC.Num.Num a => GHC.Num.Num (Clash.Signal.Delayed.Internal.DSignal dom delay a)
instance GHC.Base.Applicative (Clash.Signal.Delayed.Internal.DSignal dom delay)
instance GHC.Base.Functor (Clash.Signal.Delayed.Internal.DSignal dom delay)
instance Data.Default.Class.Default a => Data.Default.Class.Default (Clash.Signal.Delayed.Internal.DSignal dom delay a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Signal.Delayed.Internal.DSignal dom delay a)


module Clash.Promoted.Nat.Unsafe

-- | I hope you know what you're doing
unsafeSNat :: Integer -> SNat k


module Clash.Promoted.Nat.TH

-- | Create an <a>SNat</a> literal
--   
--   <pre>
--   $(decLiteralD 1111)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t d1111
--   d1111 :: SNat 1111
--   </pre>
decLiteralD :: Integer -> Q [Dec]

-- | Create a range of <a>SNat</a> literals
--   
--   <pre>
--   $(decLiteralsD 1200 1202)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t d1200
--   d1200 :: SNat 1200
--   
--   &gt;&gt;&gt; :t d1201
--   d1201 :: SNat 1201
--   
--   &gt;&gt;&gt; :t d1202
--   d1202 :: SNat 1202
--   </pre>
decLiteralsD :: Integer -> Integer -> Q [Dec]


-- | Predefined <a>SNat</a> singleton literals in the range [0 .. 1024]
--   
--   Defines:
--   
--   <pre>
--   d0 = SNat :: SNat 0
--   d1 = SNat :: SNat 1
--   d2 = SNat :: SNat 2
--   ...
--   d1024 = SNat :: SNat 1024
--   </pre>
--   
--   You can generate more <a>SNat</a> literals using <a>decLiteralsD</a>
--   from <a>Clash.Promoted.Nat.TH</a>
module Clash.Promoted.Nat.Literals


module Clash.Class.HasDomain.CodeGen
mkTryDomainTuples :: Name -> Name -> Q [Dec]
mkHasDomainTuples :: Name -> Name -> Q [Dec]


module Clash.Class.BitPack.Internal.TH

-- | Contruct all the tuple (starting at size 3) instances for BitPack.
deriveBitPackTuples :: Name -> Name -> Name -> Name -> DecsQ


module Clash.Class.BitPack.Internal

-- | Convert data to/from a <a>BitVector</a>. This allows functions to be
--   defined on the underlying representation of data, while exposing a
--   nicer API using <a>pack</a> / <a>unpack</a> at the boundaries. For
--   example:
--   
--   <pre>
--   f :: forall a b. (BitPack a, BitPack b) =&gt; a -&gt; b
--   f = unpack . go . pack
--    where
--     go :: BitVector (BitSize a) -&gt; BitVector (BitSize b)
--     go = _ -- A function on the underlying bit vector
--   </pre>
--   
--   A type should only implement this class if it has a statically known
--   size, as otherwise it is not possible to determine how many bits are
--   needed to represent values. This means that types such as <tt>[a]</tt>
--   cannot have <tt>BitPack</tt> instances, as even if <tt>a</tt> has a
--   statically known size, the length of the list cannot be known in
--   advance.
--   
--   It is not possible to give data a custom bit representation by
--   providing a <tt>BitPack</tt> instance. A <tt>BitPack</tt> instance
--   allows no creativity and should always accurately reflect the bit
--   representation of the data in HDL. You should always <tt>derive
--   (<a>Generic</a>, BitPack)</tt> unless you use a custom data
--   representation, in which case you should use <a>deriveBitPack</a>.
--   Custom encodings can be created with
--   <a>Clash.Annotations.BitRepresentation</a> and
--   <a>Clash.Annotations.BitRepresentation.Deriving</a>.
--   
--   If the <tt>BitPack</tt> instance does not accurately match the bit
--   representation of the data in HDL, Clash designs will exhibit
--   incorrect behavior in various places.
--   
--   Clash provides some generic functions on packable types in the
--   prelude, such as indexing into packable stuctures (see
--   <a>Clash.Class.BitPack.BitIndex</a>) and bitwise reduction of packable
--   data (see <a>Clash.Class.BitPack.BitReduction</a>).
class KnownNat (BitSize a) => BitPack a where {
    
    -- | Number of <a>Bit</a>s needed to represents elements of type <tt>a</tt>
    --   
    --   Can be derived using <a>Generics</a>:
    --   
    --   <pre>
    --   import Clash.Prelude
    --   import GHC.Generics
    --   
    --   data MyProductType = MyProductType { a :: Int, b :: Bool }
    --     deriving (Generic, BitPack)
    --   </pre>
    type family BitSize a :: Nat;
    type BitSize a = (CLog 2 (GConstructorCount (Rep a))) + (GFieldSize (Rep a));
}

-- | Convert element of type <tt>a</tt> to a <a>BitVector</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   </pre>
pack :: BitPack a => a -> BitVector (BitSize a)

-- | Convert element of type <tt>a</tt> to a <a>BitVector</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   </pre>
pack :: (BitPack a, Generic a, GBitPack (Rep a), KnownNat (BitSize a), KnownNat constrSize, KnownNat fieldSize, constrSize ~ CLog 2 (GConstructorCount (Rep a)), fieldSize ~ GFieldSize (Rep a), (constrSize + fieldSize) ~ BitSize a) => a -> BitVector (BitSize a)

-- | Convert a <a>BitVector</a> to an element of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; let x = pack (-5 :: Signed 6)
--   
--   &gt;&gt;&gt; unpack x :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   0b11_1011
--   </pre>
unpack :: BitPack a => BitVector (BitSize a) -> a

-- | Convert a <a>BitVector</a> to an element of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; let x = pack (-5 :: Signed 6)
--   
--   &gt;&gt;&gt; unpack x :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   0b11_1011
--   </pre>
unpack :: (BitPack a, Generic a, GBitPack (Rep a), KnownNat constrSize, KnownNat fieldSize, constrSize ~ CLog 2 (GConstructorCount (Rep a)), fieldSize ~ GFieldSize (Rep a), (constrSize + fieldSize) ~ BitSize a) => BitVector (BitSize a) -> a
packXWith :: KnownNat n => (a -> BitVector n) -> a -> BitVector n

-- | Pack both arguments to a <a>BitVector</a> and use <a>isLike#</a> to
--   compare them. This is a more lentiant comparison than <a>(==)</a>,
--   behaving more like (but not necessarily exactly the same as)
--   <tt>std_match</tt> in VHDL or <tt>casez</tt> in Verilog.
--   
--   Unlike <a>(==)</a>, isLike is not symmetric. The reason for this is
--   that a defined bit is said to be like an undefined bit, but not
--   vice-versa:
--   
--   <pre>
--   &gt;&gt;&gt; isLike (12 :: Signed 8) undefined
--   True
--   
--   &gt;&gt;&gt; isLike undefined (12 :: Signed 8)
--   False
--   </pre>
--   
--   However, it is still trivially reflexive and transitive:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTemplateHaskell
--   
--   &gt;&gt;&gt; let x1 = $(bLit "0010")
--   
--   &gt;&gt;&gt; let x2 = $(bLit "0.10")
--   
--   &gt;&gt;&gt; let x3 = $(bLit "0.1.")
--   
--   &gt;&gt;&gt; isLike x1 x1
--   True
--   
--   &gt;&gt;&gt; isLike x1 x2
--   True
--   
--   &gt;&gt;&gt; isLike x2 x3
--   True
--   
--   &gt;&gt;&gt; isLike x1 x3
--   True
--   </pre>
--   
--   <b>NB</b>: Not synthesizable
isLike :: BitPack a => a -> a -> Bool

-- | Coerce a value from one type to another through its bit
--   representation.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; bitCoerce (-5 :: Signed 6) :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   0b11_1011
--   </pre>
bitCoerce :: (BitPack a, BitPack b, BitSize a ~ BitSize b) => a -> b

-- | Map a value by first coercing to another type through its bit
--   representation.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 32)
--   0b1111_1111_1111_1111_1111_1111_1111_1011
--   
--   &gt;&gt;&gt; bitCoerceMap @(Vec 4 (BitVector 8)) (replace 1 0) (-5 :: Signed 32)
--   -16711685
--   
--   &gt;&gt;&gt; pack (-16711685 :: Signed 32)
--   0b1111_1111_0000_0000_1111_1111_1111_1011
--   </pre>
bitCoerceMap :: forall a b. (BitPack a, BitPack b, BitSize a ~ BitSize b) => (a -> a) -> b -> b
packFloat# :: Float -> BitVector 32
unpackFloat# :: BitVector 32 -> Float
packDouble# :: Double -> BitVector 64
unpackDouble# :: BitVector 64 -> Double
class GBitPack f where {
    
    -- | Size of fields. If multiple constructors exist, this is the maximum of
    --   the sum of each of the constructors fields.
    type family GFieldSize f :: Nat;
    
    -- | Number of constructors this type has. Indirectly indicates how many
    --   bits are needed to represent the constructor.
    type family GConstructorCount f :: Nat;
}

-- | Pack fields of a type. Caller should pack and prepend the constructor
--   bits.
gPackFields :: GBitPack f => Int -> f a -> (Int, BitVector (GFieldSize f))

-- | Unpack whole type.
gUnpack :: GBitPack f => Int -> Int -> BitVector (GFieldSize f) -> f a

-- | Zero-extend a <a>Bool</a>ean value to a <a>BitVector</a> of the
--   appropriate size.
--   
--   <pre>
--   &gt;&gt;&gt; boolToBV True :: BitVector 6
--   0b00_0001
--   
--   &gt;&gt;&gt; boolToBV False :: BitVector 6
--   0b00_0000
--   </pre>
boolToBV :: KnownNat n => Bool -> BitVector (n + 1)

-- | Convert a Bool to a Bit
boolToBit :: Bool -> Bit

-- | Convert a Bit to a Bool
bitToBool :: Bit -> Bool
instance (Clash.Class.BitPack.Internal.BitPack a1, GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.BitSize a1), Clash.Class.BitPack.Internal.BitPack (a2, a3), GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.BitSize (a2, a3))) => Clash.Class.BitPack.Internal.BitPack (a1, a2, a3)
instance Clash.Class.BitPack.Internal.BitPack GHC.Types.Bool
instance GHC.TypeNats.KnownNat n => Clash.Class.BitPack.Internal.BitPack (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Class.BitPack.Internal.BitPack Clash.Sized.Internal.BitVector.Bit
instance Clash.Class.BitPack.Internal.BitPack GHC.Types.Int
instance Clash.Class.BitPack.Internal.BitPack GHC.Int.Int8
instance Clash.Class.BitPack.Internal.BitPack GHC.Int.Int16
instance Clash.Class.BitPack.Internal.BitPack GHC.Int.Int32
instance Clash.Class.BitPack.Internal.BitPack GHC.Int.Int64
instance Clash.Class.BitPack.Internal.BitPack GHC.Types.Word
instance Clash.Class.BitPack.Internal.BitPack GHC.Word.Word8
instance Clash.Class.BitPack.Internal.BitPack GHC.Word.Word16
instance Clash.Class.BitPack.Internal.BitPack GHC.Word.Word32
instance Clash.Class.BitPack.Internal.BitPack GHC.Word.Word64
instance Clash.Class.BitPack.Internal.BitPack GHC.Types.Float
instance Clash.Class.BitPack.Internal.BitPack GHC.Types.Double
instance Clash.Class.BitPack.Internal.BitPack Foreign.C.Types.CUShort
instance Clash.Class.BitPack.Internal.BitPack Numeric.Half.Internal.Half
instance Clash.Class.BitPack.Internal.BitPack ()
instance (Clash.Class.BitPack.Internal.BitPack a, Clash.Class.BitPack.Internal.BitPack b) => Clash.Class.BitPack.Internal.BitPack (a, b)
instance Clash.Class.BitPack.Internal.BitPack c => Clash.Class.BitPack.Internal.GBitPack (GHC.Generics.K1 i c)
instance Clash.Class.BitPack.Internal.BitPack GHC.Types.Ordering
instance (Clash.Class.BitPack.Internal.BitPack a, Clash.Class.BitPack.Internal.BitPack b) => Clash.Class.BitPack.Internal.BitPack (Data.Either.Either a b)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (GHC.Maybe.Maybe a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Data.Complex.Complex a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Data.Ord.Down a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Data.Functor.Identity.Identity a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Data.Functor.Const.Const a b)
instance (Clash.Class.BitPack.Internal.BitPack (f a), Clash.Class.BitPack.Internal.BitPack (g a)) => Clash.Class.BitPack.Internal.BitPack (Data.Functor.Product.Product f g a)
instance (Clash.Class.BitPack.Internal.BitPack (f a), Clash.Class.BitPack.Internal.BitPack (g a)) => Clash.Class.BitPack.Internal.BitPack (Data.Functor.Sum.Sum f g a)
instance Clash.Class.BitPack.Internal.BitPack (f (g a)) => Clash.Class.BitPack.Internal.BitPack (Data.Functor.Compose.Compose f g a)
instance Clash.Class.BitPack.Internal.GBitPack a => Clash.Class.BitPack.Internal.GBitPack (GHC.Generics.M1 m d a)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.GFieldSize g), GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.GFieldSize f), GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.GConstructorCount f), Clash.Class.BitPack.Internal.GBitPack f, Clash.Class.BitPack.Internal.GBitPack g) => Clash.Class.BitPack.Internal.GBitPack (f GHC.Generics.:+: g)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.GFieldSize g), GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.GFieldSize f), Clash.Class.BitPack.Internal.GBitPack f, Clash.Class.BitPack.Internal.GBitPack g) => Clash.Class.BitPack.Internal.GBitPack (f GHC.Generics.:*: g)
instance Clash.Class.BitPack.Internal.GBitPack GHC.Generics.U1


module Clash.Explicit.BlockRam.Internal

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)
[MemBlob] :: (KnownNat n, KnownNat m) => {memBlobRunsLen :: !Int, memBlobRuns :: Addr#, memBlobEndsLen :: !Int, memBlobEnds :: Addr#} -> MemBlob n m

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]
unpackMemBlob0 :: forall n m. MemBlob n m -> IO [BitVector m]
packBVs :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> Either String (Int, ByteString, ByteString)
packAsNats :: forall a f. Foldable f => Int -> (a -> Natural) -> f a -> (ByteString, ByteString)
unpackNats :: Int -> Int -> ByteString -> ByteString -> [Natural]
unpackW64s :: ByteString -> [Word64]
unpackEnds :: Int -> Int -> [Word64] -> [Natural]
instance GHC.Show.Show (Clash.Explicit.BlockRam.Internal.MemBlob n m)


module Clash.Class.BitPack.BitReduction

-- | Are all bits set to '1'?
--   
--   <pre>
--   &gt;&gt;&gt; pack (-2 :: Signed 6)
--   0b11_1110
--   
--   &gt;&gt;&gt; reduceAnd (-2 :: Signed 6)
--   0
--   
--   &gt;&gt;&gt; pack (-1 :: Signed 6)
--   0b11_1111
--   
--   &gt;&gt;&gt; reduceAnd (-1 :: Signed 6)
--   1
--   </pre>
--   
--   Zero width types will evaluate to '1':
--   
--   <pre>
--   &gt;&gt;&gt; reduceAnd (0 :: Unsigned 0)
--   1
--   </pre>
reduceAnd :: BitPack a => a -> Bit

-- | Is there at least one bit set to '1'?
--   
--   <pre>
--   &gt;&gt;&gt; pack (5 :: Signed 6)
--   0b00_0101
--   
--   &gt;&gt;&gt; reduceOr (5 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (0 :: Signed 6)
--   0b00_0000
--   
--   &gt;&gt;&gt; reduceOr (0 :: Signed 6)
--   0
--   </pre>
--   
--   Zero width types will evaluate to '0':
--   
--   <pre>
--   &gt;&gt;&gt; reduceOr (0 :: Unsigned 0)
--   0
--   </pre>
reduceOr :: BitPack a => a -> Bit

-- | Is the number of bits set to '1' uneven?
--   
--   <pre>
--   &gt;&gt;&gt; pack (5 :: Signed 6)
--   0b00_0101
--   
--   &gt;&gt;&gt; reduceXor (5 :: Signed 6)
--   0
--   
--   &gt;&gt;&gt; pack (28 :: Signed 6)
--   0b01_1100
--   
--   &gt;&gt;&gt; reduceXor (28 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; reduceXor (-5 :: Signed 6)
--   1
--   </pre>
--   
--   Zero width types will evaluate to '0':
--   
--   <pre>
--   &gt;&gt;&gt; reduceXor (0 :: Unsigned 0)
--   0
--   </pre>
reduceXor :: BitPack a => a -> Bit


module Clash.Class.BitPack.BitIndex

-- | Get the bit at the specified bit index.
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   0b00_0111
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 1
--   1
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 5
--   0
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 6
--   *** Exception: (!): 6 is out of range [0..5]
--   ...
--   </pre>
(!) :: (BitPack a, Enum i) => a -> i -> Bit

-- | Get a slice between bit index <tt>m</tt> and and bit index <tt>n</tt>.
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   0b00_0111
--   
--   &gt;&gt;&gt; slice d4 d2 (7 :: Unsigned 6)
--   0b001
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; slice d6 d4 (7 :: Unsigned 6)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘7 + i0’ with ‘6’
--           arising from a use of ‘slice’
--         The type variable ‘i0’ is ambiguous
--       • In the expression: slice d6 d4 (7 :: Unsigned 6)
--         In an equation for ‘it’: it = slice d6 d4 (7 :: Unsigned 6)
--   </pre>
slice :: (BitPack a, BitSize a ~ ((m + 1) + i)) => SNat m -> SNat n -> a -> BitVector ((m + 1) - n)

-- | Split a value of a bit size <tt>m + n</tt> into a tuple of values with
--   size <tt>m</tt> and size <tt>n</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   0b00_0111
--   
--   &gt;&gt;&gt; split (7 :: Unsigned 6) :: (BitVector 2, BitVector 4)
--   (0b00,0b0111)
--   </pre>
split :: (BitPack a, BitSize a ~ (m + n), KnownNat n) => a -> (BitVector m, BitVector n)

-- | Set the bit at the specified index
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; replaceBit 4 0 (-5 :: Signed 6)
--   -21
--   
--   &gt;&gt;&gt; pack (-21 :: Signed 6)
--   0b10_1011
--   
--   &gt;&gt;&gt; replaceBit 5 0 (-5 :: Signed 6)
--   27
--   
--   &gt;&gt;&gt; pack (27 :: Signed 6)
--   0b01_1011
--   
--   &gt;&gt;&gt; replaceBit 6 0 (-5 :: Signed 6)
--   *** Exception: replaceBit: 6 is out of range [0..5]
--   ...
--   </pre>
replaceBit :: (BitPack a, Enum i) => i -> Bit -> a -> a

-- | Set the bits between bit index <tt>m</tt> and bit index <tt>n</tt>.
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; setSlice d4 d3 0 (-5 :: Signed 6)
--   -29
--   
--   &gt;&gt;&gt; pack (-29 :: Signed 6)
--   0b10_0011
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; setSlice d6 d5 0 (-5 :: Signed 6)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘7 + i0’ with ‘6’
--           arising from a use of ‘setSlice’
--         The type variable ‘i0’ is ambiguous
--       • In the expression: setSlice d6 d5 0 (- 5 :: Signed 6)
--         In an equation for ‘it’: it = setSlice d6 d5 0 (- 5 :: Signed 6)
--   </pre>
setSlice :: (BitPack a, BitSize a ~ ((m + 1) + i)) => SNat m -> SNat n -> BitVector ((m + 1) - n) -> a -> a

-- | Get the most significant bit.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-4 :: Signed 6)
--   0b11_1100
--   
--   &gt;&gt;&gt; msb (-4 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (4 :: Signed 6)
--   0b00_0100
--   
--   &gt;&gt;&gt; msb (4 :: Signed 6)
--   0
--   </pre>
msb :: BitPack a => a -> Bit

-- | Get the least significant bit.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-9 :: Signed 6)
--   0b11_0111
--   
--   &gt;&gt;&gt; lsb (-9 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (-8 :: Signed 6)
--   0b11_1000
--   
--   &gt;&gt;&gt; lsb (-8 :: Signed 6)
--   0
--   </pre>
lsb :: BitPack a => a -> Bit


module Clash.Class.BitPack

-- | Convert data to/from a <a>BitVector</a>. This allows functions to be
--   defined on the underlying representation of data, while exposing a
--   nicer API using <a>pack</a> / <a>unpack</a> at the boundaries. For
--   example:
--   
--   <pre>
--   f :: forall a b. (BitPack a, BitPack b) =&gt; a -&gt; b
--   f = unpack . go . pack
--    where
--     go :: BitVector (BitSize a) -&gt; BitVector (BitSize b)
--     go = _ -- A function on the underlying bit vector
--   </pre>
--   
--   A type should only implement this class if it has a statically known
--   size, as otherwise it is not possible to determine how many bits are
--   needed to represent values. This means that types such as <tt>[a]</tt>
--   cannot have <tt>BitPack</tt> instances, as even if <tt>a</tt> has a
--   statically known size, the length of the list cannot be known in
--   advance.
--   
--   It is not possible to give data a custom bit representation by
--   providing a <tt>BitPack</tt> instance. A <tt>BitPack</tt> instance
--   allows no creativity and should always accurately reflect the bit
--   representation of the data in HDL. You should always <tt>derive
--   (<a>Generic</a>, BitPack)</tt> unless you use a custom data
--   representation, in which case you should use <a>deriveBitPack</a>.
--   Custom encodings can be created with
--   <a>Clash.Annotations.BitRepresentation</a> and
--   <a>Clash.Annotations.BitRepresentation.Deriving</a>.
--   
--   If the <tt>BitPack</tt> instance does not accurately match the bit
--   representation of the data in HDL, Clash designs will exhibit
--   incorrect behavior in various places.
--   
--   Clash provides some generic functions on packable types in the
--   prelude, such as indexing into packable stuctures (see
--   <a>Clash.Class.BitPack.BitIndex</a>) and bitwise reduction of packable
--   data (see <a>Clash.Class.BitPack.BitReduction</a>).
class KnownNat (BitSize a) => BitPack a where {
    
    -- | Number of <a>Bit</a>s needed to represents elements of type <tt>a</tt>
    --   
    --   Can be derived using <a>Generics</a>:
    --   
    --   <pre>
    --   import Clash.Prelude
    --   import GHC.Generics
    --   
    --   data MyProductType = MyProductType { a :: Int, b :: Bool }
    --     deriving (Generic, BitPack)
    --   </pre>
    type family BitSize a :: Nat;
    type BitSize a = (CLog 2 (GConstructorCount (Rep a))) + (GFieldSize (Rep a));
}

-- | Convert element of type <tt>a</tt> to a <a>BitVector</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   </pre>
pack :: BitPack a => a -> BitVector (BitSize a)

-- | Convert element of type <tt>a</tt> to a <a>BitVector</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   </pre>
pack :: (BitPack a, Generic a, GBitPack (Rep a), KnownNat (BitSize a), KnownNat constrSize, KnownNat fieldSize, constrSize ~ CLog 2 (GConstructorCount (Rep a)), fieldSize ~ GFieldSize (Rep a), (constrSize + fieldSize) ~ BitSize a) => a -> BitVector (BitSize a)

-- | Convert a <a>BitVector</a> to an element of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; let x = pack (-5 :: Signed 6)
--   
--   &gt;&gt;&gt; unpack x :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   0b11_1011
--   </pre>
unpack :: BitPack a => BitVector (BitSize a) -> a

-- | Convert a <a>BitVector</a> to an element of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; let x = pack (-5 :: Signed 6)
--   
--   &gt;&gt;&gt; unpack x :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   0b11_1011
--   </pre>
unpack :: (BitPack a, Generic a, GBitPack (Rep a), KnownNat constrSize, KnownNat fieldSize, constrSize ~ CLog 2 (GConstructorCount (Rep a)), fieldSize ~ GFieldSize (Rep a), (constrSize + fieldSize) ~ BitSize a) => BitVector (BitSize a) -> a

-- | Pack both arguments to a <a>BitVector</a> and use <a>isLike#</a> to
--   compare them. This is a more lentiant comparison than <a>(==)</a>,
--   behaving more like (but not necessarily exactly the same as)
--   <tt>std_match</tt> in VHDL or <tt>casez</tt> in Verilog.
--   
--   Unlike <a>(==)</a>, isLike is not symmetric. The reason for this is
--   that a defined bit is said to be like an undefined bit, but not
--   vice-versa:
--   
--   <pre>
--   &gt;&gt;&gt; isLike (12 :: Signed 8) undefined
--   True
--   
--   &gt;&gt;&gt; isLike undefined (12 :: Signed 8)
--   False
--   </pre>
--   
--   However, it is still trivially reflexive and transitive:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTemplateHaskell
--   
--   &gt;&gt;&gt; let x1 = $(bLit "0010")
--   
--   &gt;&gt;&gt; let x2 = $(bLit "0.10")
--   
--   &gt;&gt;&gt; let x3 = $(bLit "0.1.")
--   
--   &gt;&gt;&gt; isLike x1 x1
--   True
--   
--   &gt;&gt;&gt; isLike x1 x2
--   True
--   
--   &gt;&gt;&gt; isLike x2 x3
--   True
--   
--   &gt;&gt;&gt; isLike x1 x3
--   True
--   </pre>
--   
--   <b>NB</b>: Not synthesizable
isLike :: BitPack a => a -> a -> Bool

-- | Coerce a value from one type to another through its bit
--   representation.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; bitCoerce (-5 :: Signed 6) :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   0b11_1011
--   </pre>
bitCoerce :: (BitPack a, BitPack b, BitSize a ~ BitSize b) => a -> b

-- | Map a value by first coercing to another type through its bit
--   representation.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 32)
--   0b1111_1111_1111_1111_1111_1111_1111_1011
--   
--   &gt;&gt;&gt; bitCoerceMap @(Vec 4 (BitVector 8)) (replace 1 0) (-5 :: Signed 32)
--   -16711685
--   
--   &gt;&gt;&gt; pack (-16711685 :: Signed 32)
--   0b1111_1111_0000_0000_1111_1111_1111_1011
--   </pre>
bitCoerceMap :: forall a b. (BitPack a, BitPack b, BitSize a ~ BitSize b) => (a -> a) -> b -> b

-- | Zero-extend a <a>Bool</a>ean value to a <a>BitVector</a> of the
--   appropriate size.
--   
--   <pre>
--   &gt;&gt;&gt; boolToBV True :: BitVector 6
--   0b00_0001
--   
--   &gt;&gt;&gt; boolToBV False :: BitVector 6
--   0b00_0000
--   </pre>
boolToBV :: KnownNat n => Bool -> BitVector (n + 1)

-- | Convert a Bool to a Bit
boolToBit :: Bool -> Bit

-- | Convert a Bit to a Bool
bitToBool :: Bit -> Bool
packXWith :: KnownNat n => (a -> BitVector n) -> a -> BitVector n

-- | Get the bit at the specified bit index.
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   0b00_0111
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 1
--   1
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 5
--   0
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 6
--   *** Exception: (!): 6 is out of range [0..5]
--   ...
--   </pre>
(!) :: (BitPack a, Enum i) => a -> i -> Bit

-- | Get a slice between bit index <tt>m</tt> and and bit index <tt>n</tt>.
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   0b00_0111
--   
--   &gt;&gt;&gt; slice d4 d2 (7 :: Unsigned 6)
--   0b001
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; slice d6 d4 (7 :: Unsigned 6)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘7 + i0’ with ‘6’
--           arising from a use of ‘slice’
--         The type variable ‘i0’ is ambiguous
--       • In the expression: slice d6 d4 (7 :: Unsigned 6)
--         In an equation for ‘it’: it = slice d6 d4 (7 :: Unsigned 6)
--   </pre>
slice :: (BitPack a, BitSize a ~ ((m + 1) + i)) => SNat m -> SNat n -> a -> BitVector ((m + 1) - n)

-- | Split a value of a bit size <tt>m + n</tt> into a tuple of values with
--   size <tt>m</tt> and size <tt>n</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   0b00_0111
--   
--   &gt;&gt;&gt; split (7 :: Unsigned 6) :: (BitVector 2, BitVector 4)
--   (0b00,0b0111)
--   </pre>
split :: (BitPack a, BitSize a ~ (m + n), KnownNat n) => a -> (BitVector m, BitVector n)

-- | Set the bit at the specified index
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; replaceBit 4 0 (-5 :: Signed 6)
--   -21
--   
--   &gt;&gt;&gt; pack (-21 :: Signed 6)
--   0b10_1011
--   
--   &gt;&gt;&gt; replaceBit 5 0 (-5 :: Signed 6)
--   27
--   
--   &gt;&gt;&gt; pack (27 :: Signed 6)
--   0b01_1011
--   
--   &gt;&gt;&gt; replaceBit 6 0 (-5 :: Signed 6)
--   *** Exception: replaceBit: 6 is out of range [0..5]
--   ...
--   </pre>
replaceBit :: (BitPack a, Enum i) => i -> Bit -> a -> a

-- | Set the bits between bit index <tt>m</tt> and bit index <tt>n</tt>.
--   
--   <b>NB</b>: Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; setSlice d4 d3 0 (-5 :: Signed 6)
--   -29
--   
--   &gt;&gt;&gt; pack (-29 :: Signed 6)
--   0b10_0011
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; setSlice d6 d5 0 (-5 :: Signed 6)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘7 + i0’ with ‘6’
--           arising from a use of ‘setSlice’
--         The type variable ‘i0’ is ambiguous
--       • In the expression: setSlice d6 d5 0 (- 5 :: Signed 6)
--         In an equation for ‘it’: it = setSlice d6 d5 0 (- 5 :: Signed 6)
--   </pre>
setSlice :: (BitPack a, BitSize a ~ ((m + 1) + i)) => SNat m -> SNat n -> BitVector ((m + 1) - n) -> a -> a

-- | Get the most significant bit.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-4 :: Signed 6)
--   0b11_1100
--   
--   &gt;&gt;&gt; msb (-4 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (4 :: Signed 6)
--   0b00_0100
--   
--   &gt;&gt;&gt; msb (4 :: Signed 6)
--   0
--   </pre>
msb :: BitPack a => a -> Bit

-- | Get the least significant bit.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-9 :: Signed 6)
--   0b11_0111
--   
--   &gt;&gt;&gt; lsb (-9 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (-8 :: Signed 6)
--   0b11_1000
--   
--   &gt;&gt;&gt; lsb (-8 :: Signed 6)
--   0
--   </pre>
lsb :: BitPack a => a -> Bit

-- | Are all bits set to '1'?
--   
--   <pre>
--   &gt;&gt;&gt; pack (-2 :: Signed 6)
--   0b11_1110
--   
--   &gt;&gt;&gt; reduceAnd (-2 :: Signed 6)
--   0
--   
--   &gt;&gt;&gt; pack (-1 :: Signed 6)
--   0b11_1111
--   
--   &gt;&gt;&gt; reduceAnd (-1 :: Signed 6)
--   1
--   </pre>
--   
--   Zero width types will evaluate to '1':
--   
--   <pre>
--   &gt;&gt;&gt; reduceAnd (0 :: Unsigned 0)
--   1
--   </pre>
reduceAnd :: BitPack a => a -> Bit

-- | Is there at least one bit set to '1'?
--   
--   <pre>
--   &gt;&gt;&gt; pack (5 :: Signed 6)
--   0b00_0101
--   
--   &gt;&gt;&gt; reduceOr (5 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (0 :: Signed 6)
--   0b00_0000
--   
--   &gt;&gt;&gt; reduceOr (0 :: Signed 6)
--   0
--   </pre>
--   
--   Zero width types will evaluate to '0':
--   
--   <pre>
--   &gt;&gt;&gt; reduceOr (0 :: Unsigned 0)
--   0
--   </pre>
reduceOr :: BitPack a => a -> Bit

-- | Is the number of bits set to '1' uneven?
--   
--   <pre>
--   &gt;&gt;&gt; pack (5 :: Signed 6)
--   0b00_0101
--   
--   &gt;&gt;&gt; reduceXor (5 :: Signed 6)
--   0
--   
--   &gt;&gt;&gt; pack (28 :: Signed 6)
--   0b01_1100
--   
--   &gt;&gt;&gt; reduceXor (28 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   0b11_1011
--   
--   &gt;&gt;&gt; reduceXor (-5 :: Signed 6)
--   1
--   </pre>
--   
--   Zero width types will evaluate to '0':
--   
--   <pre>
--   &gt;&gt;&gt; reduceXor (0 :: Unsigned 0)
--   0
--   </pre>
reduceXor :: BitPack a => a -> Bit


module Clash.Class.Parity

-- | Determine whether value is odd or even
class Parity a

-- | Check if value is even
--   
--   <pre>
--   &gt;&gt;&gt; even (4 :: Unsigned 4)
--   True
--   </pre>
even :: Parity a => a -> Bool

-- | Check if value is odd
--   
--   <pre>
--   &gt;&gt;&gt; odd (4 :: Unsigned 4)
--   False
--   </pre>
odd :: Parity a => a -> Bool
instance Clash.Class.Parity.Parity GHC.Integer.Type.Integer
instance GHC.TypeNats.KnownNat n => Clash.Class.Parity.Parity (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Class.Parity.Parity GHC.Types.Bool
instance Clash.Class.Parity.Parity Foreign.C.Types.CUShort
instance Clash.Class.Parity.Parity GHC.Types.Word
instance Clash.Class.Parity.Parity GHC.Word.Word8
instance Clash.Class.Parity.Parity GHC.Word.Word16
instance Clash.Class.Parity.Parity GHC.Word.Word32
instance Clash.Class.Parity.Parity GHC.Word.Word64
instance Clash.Class.Parity.Parity GHC.Types.Int
instance Clash.Class.Parity.Parity GHC.Int.Int8
instance Clash.Class.Parity.Parity GHC.Int.Int16
instance Clash.Class.Parity.Parity GHC.Int.Int32
instance Clash.Class.Parity.Parity GHC.Int.Int64


module Clash.Sized.Internal.Unsigned

-- | Arbitrary-width unsigned integer represented by <tt>n</tt> bits
--   
--   Given <tt>n</tt> bits, an <a>Unsigned</a> <tt>n</tt> number has a
--   range of: [0 .. 2^<tt>n</tt>-1]
--   
--   <ul>
--   <li><b>NB</b>: The usual Haskell method of converting an integral
--   numeric type to another, <a>fromIntegral</a>, is not well suited for
--   Clash as it will go through <a>Integer</a> which is arbitrarily
--   bounded in HDL. Instead use <a>bitCoerce</a> and the <a>Resize</a>
--   class.</li>
--   <li><b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt>
--   on overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; minBound :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Unsigned 3)) :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Unsigned 3
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; 1 - 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `mul` (4 :: Unsigned 3) :: Unsigned 6
--   8
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `add` (6 :: Unsigned 3) :: Unsigned 4
--   8
--   
--   &gt;&gt;&gt; satAdd SatSymmetric 2 6 :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; satSub SatSymmetric 2 3 :: Unsigned 3
--   0
--   </pre>
--   
--   Unsigned has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Unsigned
--   type role Unsigned nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between different width Unsigned. To
--   change the width, use the functions in the <a>Resize</a> class.
newtype Unsigned (n :: Nat)

-- | The constructor, <a>U</a>, and the field, <a>unsafeToNatural</a>, are
--   not synthesizable.
U :: Natural -> Unsigned (n :: Nat)
[unsafeToNatural] :: Unsigned (n :: Nat) -> Natural
size# :: KnownNat n => Unsigned n -> Int
pack# :: Unsigned n -> BitVector n
unpack# :: KnownNat n => BitVector n -> Unsigned n
eq# :: Unsigned n -> Unsigned n -> Bool
neq# :: Unsigned n -> Unsigned n -> Bool
lt# :: Unsigned n -> Unsigned n -> Bool
ge# :: Unsigned n -> Unsigned n -> Bool
gt# :: Unsigned n -> Unsigned n -> Bool
le# :: Unsigned n -> Unsigned n -> Bool
toEnum# :: forall n. KnownNat n => Int -> Unsigned n
fromEnum# :: forall n. KnownNat n => Unsigned n -> Int
enumFrom# :: forall n. KnownNat n => Unsigned n -> [Unsigned n]
enumFromThen# :: forall n. KnownNat n => Unsigned n -> Unsigned n -> [Unsigned n]
enumFromTo# :: forall n. KnownNat n => Unsigned n -> Unsigned n -> [Unsigned n]
enumFromThenTo# :: forall n. KnownNat n => Unsigned n -> Unsigned n -> Unsigned n -> [Unsigned n]
minBound# :: Unsigned n
maxBound# :: forall n. KnownNat n => Unsigned n
(+#) :: forall n. KnownNat n => Unsigned n -> Unsigned n -> Unsigned n
(-#) :: forall n. KnownNat n => Unsigned n -> Unsigned n -> Unsigned n
(*#) :: forall n. KnownNat n => Unsigned n -> Unsigned n -> Unsigned n
negate# :: forall n. KnownNat n => Unsigned n -> Unsigned n
fromInteger# :: forall n. KnownNat n => Integer -> Unsigned n
plus# :: Unsigned m -> Unsigned n -> Unsigned (Max m n + 1)
minus# :: forall m n. (KnownNat m, KnownNat n) => Unsigned m -> Unsigned n -> Unsigned (Max m n + 1)
times# :: Unsigned m -> Unsigned n -> Unsigned (m + n)
quot# :: Unsigned n -> Unsigned n -> Unsigned n
rem# :: Unsigned n -> Unsigned n -> Unsigned n
toInteger# :: Unsigned n -> Integer
and# :: Unsigned n -> Unsigned n -> Unsigned n
or# :: Unsigned n -> Unsigned n -> Unsigned n
xor# :: Unsigned n -> Unsigned n -> Unsigned n
complement# :: forall n. KnownNat n => Unsigned n -> Unsigned n
shiftL# :: forall n. KnownNat n => Unsigned n -> Int -> Unsigned n
shiftR# :: forall n. KnownNat n => Unsigned n -> Int -> Unsigned n
rotateL# :: forall n. KnownNat n => Unsigned n -> Int -> Unsigned n
rotateR# :: forall n. KnownNat n => Unsigned n -> Int -> Unsigned n
resize# :: forall n m. KnownNat m => Unsigned n -> Unsigned m
unsignedToWord :: Unsigned 64 -> Word
unsigned8toWord8 :: Unsigned 8 -> Word8
unsigned16toWord16 :: Unsigned 16 -> Word16
unsigned32toWord32 :: Unsigned 32 -> Word32
instance GHC.Generics.Generic (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Control.DeepSeq.NFData (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.Show.Show (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.XException.ShowX (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.XException.NFDataX (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Read.Read (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Clash.Class.BitPack.Internal.BitPack (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.Classes.Eq (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.Classes.Ord (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.Unsigned.Unsigned n)
instance (GHC.TypeNats.KnownNat m, GHC.TypeNats.KnownNat n) => Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.Unsigned.Unsigned m) (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Text.Printf.PrintfArg (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Parity.Parity (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Data.Bits.Bits (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Data.Bits.FiniteBits (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.Unsigned.Unsigned
instance Data.Default.Class.Default (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Ix.Ix (Clash.Sized.Internal.Unsigned.Unsigned n)


module Clash.Sized.Unsigned

-- | Arbitrary-width unsigned integer represented by <tt>n</tt> bits
--   
--   Given <tt>n</tt> bits, an <a>Unsigned</a> <tt>n</tt> number has a
--   range of: [0 .. 2^<tt>n</tt>-1]
--   
--   <ul>
--   <li><b>NB</b>: The usual Haskell method of converting an integral
--   numeric type to another, <a>fromIntegral</a>, is not well suited for
--   Clash as it will go through <a>Integer</a> which is arbitrarily
--   bounded in HDL. Instead use <a>bitCoerce</a> and the <a>Resize</a>
--   class.</li>
--   <li><b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt>
--   on overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; minBound :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Unsigned 3)) :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Unsigned 3
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; 1 - 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `mul` (4 :: Unsigned 3) :: Unsigned 6
--   8
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `add` (6 :: Unsigned 3) :: Unsigned 4
--   8
--   
--   &gt;&gt;&gt; satAdd SatSymmetric 2 6 :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; satSub SatSymmetric 2 3 :: Unsigned 3
--   0
--   </pre>
--   
--   Unsigned has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Unsigned
--   type role Unsigned nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between different width Unsigned. To
--   change the width, use the functions in the <a>Resize</a> class.
data Unsigned (n :: Nat)


module Clash.Sized.Internal.Signed

-- | Arbitrary-width signed integer represented by <tt>n</tt> bits,
--   including the sign bit
--   
--   Uses standard 2-complements representation. Meaning that, given
--   <tt>n</tt> bits, a <a>Signed</a> <tt>n</tt> number has a range of:
--   [-(2^(<tt>n</tt>-1)) .. 2^(<tt>n</tt>-1)-1] for <tt>n &gt; 0</tt>.
--   When <tt>n = 0</tt>, both the min and max bound are 0.
--   
--   <ul>
--   <li><b>NB</b>: The usual Haskell method of converting an integral
--   numeric type to another, <a>fromIntegral</a>, is not well suited for
--   Clash as it will go through <a>Integer</a> which is arbitrarily
--   bounded in HDL. Instead use <a>bitCoerce</a> and the <a>Resize</a>
--   class.</li>
--   <li><b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt>
--   on overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Signed 3
--   3
--   
--   &gt;&gt;&gt; minBound :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; read (show (minBound :: Signed 3)) :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; 1 + 2 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 + 3 :: Signed 3
--   -3
--   
--   &gt;&gt;&gt; (-2) + (-3) :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 * 3 :: Signed 4
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Signed 4
--   -8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `mul` (4 :: Signed 4) :: Signed 7
--   8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `add` (3 :: Signed 3) :: Signed 4
--   5
--   
--   &gt;&gt;&gt; (-2 :: Signed 3) `add` (-3 :: Signed 3) :: Signed 4
--   -5
--   
--   &gt;&gt;&gt; satAdd SatSymmetric 2 3 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; satAdd SatSymmetric (-2) (-3) :: Signed 3
--   -3
--   </pre>
--   
--   Signed has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Signed
--   type role Signed nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between different width Signed. To change
--   the width, use the functions in the <a>Resize</a> class.
newtype Signed (n :: Nat)

-- | The constructor, <a>S</a>, and the field, <a>unsafeToInteger</a>, are
--   not synthesizable.
S :: Integer -> Signed (n :: Nat)
[unsafeToInteger] :: Signed (n :: Nat) -> Integer
size# :: KnownNat n => Signed n -> Int
pack# :: forall n. KnownNat n => Signed n -> BitVector n
unpack# :: forall n. KnownNat n => BitVector n -> Signed n
eq# :: Signed n -> Signed n -> Bool
neq# :: Signed n -> Signed n -> Bool
lt# :: Signed n -> Signed n -> Bool
ge# :: Signed n -> Signed n -> Bool
gt# :: Signed n -> Signed n -> Bool
le# :: Signed n -> Signed n -> Bool
toEnum# :: forall n. KnownNat n => Int -> Signed n
fromEnum# :: forall n. KnownNat n => Signed n -> Int
enumFrom# :: forall n. KnownNat n => Signed n -> [Signed n]
enumFromThen# :: forall n. KnownNat n => Signed n -> Signed n -> [Signed n]
enumFromTo# :: forall n. KnownNat n => Signed n -> Signed n -> [Signed n]
enumFromThenTo# :: forall n. KnownNat n => Signed n -> Signed n -> Signed n -> [Signed n]
minBound# :: forall n. KnownNat n => Signed n
maxBound# :: forall n. KnownNat n => Signed n
(+#) :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
(-#) :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
(*#) :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
negate# :: forall n. KnownNat n => Signed n -> Signed n
abs# :: forall n. KnownNat n => Signed n -> Signed n
fromInteger# :: forall n. KnownNat n => Integer -> Signed (n :: Nat)
plus# :: Signed m -> Signed n -> Signed (Max m n + 1)
minus# :: Signed m -> Signed n -> Signed (Max m n + 1)
times# :: Signed m -> Signed n -> Signed (m + n)
quot# :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
rem# :: Signed n -> Signed n -> Signed n
div# :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
mod# :: Signed n -> Signed n -> Signed n
toInteger# :: Signed n -> Integer
and# :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
or# :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
xor# :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
complement# :: forall n. KnownNat n => Signed n -> Signed n
shiftL# :: forall n. KnownNat n => Signed n -> Int -> Signed n
shiftR# :: forall n. KnownNat n => Signed n -> Int -> Signed n
rotateL# :: forall n. KnownNat n => Signed n -> Int -> Signed n
rotateR# :: forall n. KnownNat n => Signed n -> Int -> Signed n
resize# :: forall m n. (KnownNat n, KnownNat m) => Signed n -> Signed m
truncateB# :: forall m n. KnownNat m => Signed (m + n) -> Signed m
minBoundSym# :: KnownNat n => Signed n
instance GHC.Generics.Generic (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.Signed.Signed n)
instance Clash.XException.NFDataX (Clash.Sized.Internal.Signed.Signed n)
instance Control.DeepSeq.NFData (Clash.Sized.Internal.Signed.Signed n)
instance GHC.Show.Show (Clash.Sized.Internal.Signed.Signed n)
instance Clash.XException.ShowX (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Read.Read (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Clash.Class.BitPack.Internal.BitPack (Clash.Sized.Internal.Signed.Signed n)
instance GHC.Classes.Eq (Clash.Sized.Internal.Signed.Signed n)
instance GHC.Classes.Ord (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.Signed.Signed m) (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Text.Printf.PrintfArg (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Parity.Parity (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Data.Bits.Bits (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Data.Bits.FiniteBits (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.Signed.Signed
instance GHC.TypeNats.KnownNat n => Data.Default.Class.Default (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Ix.Ix (Clash.Sized.Internal.Signed.Signed n)


module Clash.Sized.Signed

-- | Arbitrary-width signed integer represented by <tt>n</tt> bits,
--   including the sign bit
--   
--   Uses standard 2-complements representation. Meaning that, given
--   <tt>n</tt> bits, a <a>Signed</a> <tt>n</tt> number has a range of:
--   [-(2^(<tt>n</tt>-1)) .. 2^(<tt>n</tt>-1)-1] for <tt>n &gt; 0</tt>.
--   When <tt>n = 0</tt>, both the min and max bound are 0.
--   
--   <ul>
--   <li><b>NB</b>: The usual Haskell method of converting an integral
--   numeric type to another, <a>fromIntegral</a>, is not well suited for
--   Clash as it will go through <a>Integer</a> which is arbitrarily
--   bounded in HDL. Instead use <a>bitCoerce</a> and the <a>Resize</a>
--   class.</li>
--   <li><b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt>
--   on overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Signed 3
--   3
--   
--   &gt;&gt;&gt; minBound :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; read (show (minBound :: Signed 3)) :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; 1 + 2 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 + 3 :: Signed 3
--   -3
--   
--   &gt;&gt;&gt; (-2) + (-3) :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 * 3 :: Signed 4
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Signed 4
--   -8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `mul` (4 :: Signed 4) :: Signed 7
--   8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `add` (3 :: Signed 3) :: Signed 4
--   5
--   
--   &gt;&gt;&gt; (-2 :: Signed 3) `add` (-3 :: Signed 3) :: Signed 4
--   -5
--   
--   &gt;&gt;&gt; satAdd SatSymmetric 2 3 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; satAdd SatSymmetric (-2) (-3) :: Signed 3
--   -3
--   </pre>
--   
--   Signed has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Signed
--   type role Signed nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between different width Signed. To change
--   the width, use the functions in the <a>Resize</a> class.
data Signed (n :: Nat)


-- | Fixed point numbers
--   
--   <ul>
--   <li>The <a>Num</a> operators for the given types saturate on overflow,
--   and use truncation as the rounding method.</li>
--   <li><a>Fixed</a> has an instance for <a>Fractional</a> meaning you use
--   fractional literals <tt>(3.75 :: <a>SFixed</a> 4 18)</tt>.</li>
--   <li>Both integer literals and fractional literals are clipped to
--   <a>minBound</a> and <a>maxBound</a>. <b>NB</b>: Needs the
--   `-XNegativeLiterals` language extension to work for signed
--   numbers.</li>
--   <li>There is no <a>Floating</a> instance for <a>Fixed</a>, but you can
--   use <tt>$$(<a>fLit</a> d)</tt> to create <a>Fixed</a> point literal
--   from <a>Double</a> constant at compile-time.</li>
--   <li>Use <a>Constraint synonyms</a> when writing type signatures for
--   polymorphic functions that use <a>Fixed</a> point numbers.</li>
--   </ul>
--   
--   BEWARE: rounding by truncation can introduce errors larger than
--   naively assumed; e.g. for <i>Fixed 16 1</i>, rounding by truncation
--   turns the real number 4.99 to 4.5, not 5.0, i.e. an error or 0.49
--   instead of 0.01
--   
--   BEWARE: rounding by truncation introduces a sign bias!
--   
--   <ul>
--   <li>Truncation for positive numbers effectively results in: round
--   towards zero.</li>
--   <li>Truncation for negative numbers effectively results in: round
--   towards -infinity.</li>
--   </ul>
--   
--   <h2>Reasoning about precision</h2>
--   
--   Givens the real numbers <i>A</i> and <i>B</i>, and the corresponding
--   fixed point numbers <i>FA+-da</i> and <i>FB+db</i>, where <i>da</i>
--   and <i>db</i> denote the (potential) error introduced by truncation
--   w.r.t. the original <i>A</i> and <i>B</i>, the arithmetic operators on
--   fixed point numbers have the following error propagation properties:
--   
--   <ul>
--   <li>Addition: <i>da + db</i></li>
--   <li>Subtraction: <i>da - db</i></li>
--   <li>Multiplication: <i>FA*db + FB*da + da*db</i></li>
--   <li>Division: <i>(FA+da)/(FB+db) - FA/FB</i></li>
--   </ul>
--   
--   <h3>Additional error from truncation</h3>
--   
--   Given:
--   
--   <pre>
--   &gt;&gt;&gt; 4.13 :: UFixed 16 3
--   4.125
--   
--   &gt;&gt;&gt; 20.9 :: UFixed 16 3
--   20.875
--   </pre>
--   
--   The expected error that we would get from multiplication is:
--   <i>20.875*0.005 + 4.125*0.025 + 0.025*0.005 = 0.207625</i>
--   
--   <pre>
--   &gt;&gt;&gt; 4.13 * 20.9 :: Double
--   86.317
--   
--   &gt;&gt;&gt; (4.13 :: UFixed 16 3) `mul` (20.9 :: UFixed 16 3) :: UFixed 32 6
--   86.109375
--   
--   &gt;&gt;&gt; 86.109375 + 0.207625 :: Double
--   86.317
--   </pre>
--   
--   However the <i>0.109375</i> is smaller than <i>2^-3</i>, so the
--   regular multiplication operator that uses truncation introduces an
--   additional error of <i>0.109375</i>:
--   
--   <pre>
--   &gt;&gt;&gt; (4.13 :: UFixed 16 3) * (20.9 :: UFixed 16 3) :: UFixed 16 3
--   86.0
--   </pre>
module Clash.Sized.Fixed

-- | Signed <a>Fixed</a>-point number, with <tt>int</tt> integer bits
--   (including sign-bit) and <tt>frac</tt> fractional bits.
--   
--   <ul>
--   <li>The range <a>SFixed</a> <tt>int</tt> <tt>frac</tt> numbers is:
--   [-(2^(<tt>int</tt> -1)) .. 2^(<tt>int</tt>-1) - 2^-<tt>frac</tt>
--   ]</li>
--   <li>The resolution of <a>SFixed</a> <tt>int</tt> <tt>frac</tt> numbers
--   is: 2^<tt>frac</tt></li>
--   <li>The <a>Num</a> operators for this type saturate on overflow, and
--   use truncation as the rounding method.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: SFixed 3 4
--   3.9375
--   
--   &gt;&gt;&gt; minBound :: SFixed 3 4
--   -4.0
--   
--   &gt;&gt;&gt; read (show (maxBound :: SFixed 3 4)) :: SFixed 3 4
--   3.9375
--   
--   &gt;&gt;&gt; 1 + 2 :: SFixed 3 4
--   3.0
--   
--   &gt;&gt;&gt; 2 + 3 :: SFixed 3 4
--   3.9375
--   
--   &gt;&gt;&gt; (-2) + (-3) :: SFixed 3 4
--   -4.0
--   
--   &gt;&gt;&gt; 1.375 * (-0.8125) :: SFixed 3 4
--   -1.125
--   
--   &gt;&gt;&gt; (1.375 :: SFixed 3 4) `mul` (-0.8125 :: SFixed 3 4) :: SFixed 6 8
--   -1.1171875
--   
--   &gt;&gt;&gt; (2 :: SFixed 3 4) `add` (3 :: SFixed 3 4) :: SFixed 4 4
--   5.0
--   
--   &gt;&gt;&gt; (-2 :: SFixed 3 4) `add` (-3 :: SFixed 3 4) :: SFixed 4 4
--   -5.0
--   </pre>
type SFixed = Fixed Signed

-- | Treat a <a>Signed</a> integer as a <tt>Signed</tt>
--   <a>Fixed</a>-<tt>point</tt> integer
--   
--   <pre>
--   &gt;&gt;&gt; sf d4 (-22 :: Signed 7)
--   -1.375
--   </pre>
sf :: SNat frac -> Signed (int + frac) -> SFixed int frac

-- | See the underlying representation of a Signed Fixed-point integer
unSF :: SFixed int frac -> Signed (int + frac)

-- | Unsigned <a>Fixed</a>-point number, with <tt>int</tt> integer bits and
--   <tt>frac</tt> fractional bits
--   
--   <ul>
--   <li>The range <a>UFixed</a> <tt>int</tt> <tt>frac</tt> numbers is: [0
--   .. 2^<tt>int</tt> - 2^-<tt>frac</tt> ]</li>
--   <li>The resolution of <a>UFixed</a> <tt>int</tt> <tt>frac</tt> numbers
--   is: 2^<tt>frac</tt></li>
--   <li>The <a>Num</a> operators for this type saturate on overflow, and
--   use truncation as the rounding method.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: UFixed 3 4
--   7.9375
--   
--   &gt;&gt;&gt; minBound :: UFixed 3 4
--   0.0
--   
--   &gt;&gt;&gt; 1 + 2 :: UFixed 3 4
--   3.0
--   
--   &gt;&gt;&gt; 2 + 6 :: UFixed 3 4
--   7.9375
--   
--   &gt;&gt;&gt; 1 - 3 :: UFixed 3 4
--   0.0
--   
--   &gt;&gt;&gt; 1.375 * 0.8125 :: UFixed 3 4
--   1.0625
--   
--   &gt;&gt;&gt; (1.375 :: UFixed 3 4) `mul` (0.8125 :: UFixed 3 4) :: UFixed 6 8
--   1.1171875
--   
--   &gt;&gt;&gt; (2 :: UFixed 3 4) `add` (6 :: UFixed 3 4) :: UFixed 4 4
--   8.0
--   </pre>
--   
--   However, <a>sub</a> does not saturate to <a>minBound</a> on underflow:
--   
--   <pre>
--   &gt;&gt;&gt; (1 :: UFixed 3 4) `sub` (3 :: UFixed 3 4) :: UFixed 4 4
--   14.0
--   </pre>
type UFixed = Fixed Unsigned

-- | Treat an <a>Unsigned</a> integer as a <tt>Unsigned</tt>
--   <a>Fixed</a>-<tt>point</tt> number
--   
--   <pre>
--   &gt;&gt;&gt; uf d4 (92 :: Unsigned 7)
--   5.75
--   </pre>
uf :: SNat frac -> Unsigned (int + frac) -> UFixed int frac

-- | See the underlying representation of an Unsigned Fixed-point integer
unUF :: UFixed int frac -> Unsigned (int + frac)

-- | Fixed point division
--   
--   When used in a polymorphic setting, use the following <a>Constraint
--   synonyms</a> for less verbose type signatures:
--   
--   <ul>
--   <li><tt><a>DivideC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>Fixed</a> rep int1 frac1 -&gt; <a>Fixed</a> rep int2 frac2
--   -&gt; <a>Fixed</a> rep (int1 + frac2 + 1) (int2 + frac1)</tt></li>
--   <li><tt><a>DivideSC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>SFixed</a> int1 frac1 -&gt; <a>SFixed</a> int2 frac2 -&gt;
--   <a>SFixed</a> (int1 + frac2 + 1) (int2 + frac1)</tt></li>
--   <li><tt><a>DivideUC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>UFixed</a> int1 frac1 -&gt; <a>UFixed</a> int2 frac2 -&gt;
--   <a>UFixed</a> (int1 + frac2 + 1) (int2 + frac1)</tt></li>
--   </ul>
divide :: DivideC rep int1 frac1 int2 frac2 => Fixed rep int1 frac1 -> Fixed rep int2 frac2 -> Fixed rep ((int1 + frac2) + 1) (int2 + frac1)

-- | Convert, at compile-time, a <a>Double</a> <i>constant</i> to a
--   <a>Fixed</a>-point <i>literal</i>. The conversion saturates on
--   overflow, and uses truncation as its rounding method.
--   
--   So when you type:
--   
--   <pre>
--   n = $$(<a>fLit</a> pi) :: <a>SFixed</a> 4 4
--   </pre>
--   
--   The compiler sees:
--   
--   <pre>
--   n = <a>Fixed</a> (fromInteger 50) :: <a>SFixed</a> 4 4
--   </pre>
--   
--   Upon evaluation you see that the value is rounded / truncated in
--   accordance to the fixed point representation:
--   
--   <pre>
--   &gt;&gt;&gt; n
--   3.125
--   </pre>
--   
--   Further examples:
--   
--   <pre>
--   &gt;&gt;&gt; sin 0.5 :: Double
--   0.479425538604203
--   
--   &gt;&gt;&gt; $$(fLit (sin 0.5)) :: SFixed 1 8
--   0.4765625
--   
--   &gt;&gt;&gt; atan 0.2 :: Double
--   0.19739555984988078
--   
--   &gt;&gt;&gt; $$(fLit (atan 0.2)) :: SFixed 1 8
--   0.1953125
--   
--   &gt;&gt;&gt; $$(fLit (atan 0.2)) :: SFixed 1 20
--   0.19739532470703125
--   </pre>
fLit :: forall rep int frac size. (size ~ (int + frac), KnownNat frac, Bounded (rep size), Integral (rep size)) => Double -> Q (TExp (Fixed rep int frac))

-- | Convert, at run-time, a <a>Double</a> to a <a>Fixed</a>-point.
--   
--   <b>NB</b>: This function is <i>not</i> synthesizable
--   
--   <h1>Creating data-files </h1>
--   
--   An example usage of this function is to convert a data file containing
--   <a>Double</a>s to a data file with ASCII-encoded binary numbers to be
--   used by a synthesizable function like <a>asyncRomFile</a>. For
--   example, consider a file <tt>Data.txt</tt> containing:
--   
--   <pre>
--   1.2 2.0 3.0 4.0
--   -1.0 -2.0 -3.5 -4.0
--   </pre>
--   
--   which we want to put in a ROM, interpreting them as <tt>8.8</tt>
--   signed fixed point numbers. What we do is that we first create a
--   conversion utility, <tt>createRomFile</tt>, which uses <a>fLitR</a>:
--   
--   <tt>createRomFile.hs</tt>:
--   
--   <pre>
--   module Main where
--   
--   import Clash.Prelude
--   import Clash.Prelude.ROM.File
--   import System.Environment
--   import qualified Data.List as L
--   
--   createRomFile
--     :: BitPack a
--     =&gt; (Double -&gt; a)
--     -&gt; FilePath
--     -&gt; FilePath
--     -&gt; IO ()
--   createRomFile convert fileR fileW = do
--     f &lt;- readFile fileR
--     let ds :: [Double]
--         ds = L.concat . (L.map . L.map) read . L.map words $ lines f
--         fes = L.map convert ds
--     writeFile fileW (<a>memFile</a> Nothing fes)
--   
--   toSFixed8_8 :: Double -&gt; SFixed 8 8
--   toSFixed8_8 = <a>fLitR</a>
--   
--   main :: IO ()
--   main = do
--     [fileR,fileW] &lt;- getArgs
--     createRomFile toSFixed8_8 fileR fileW
--   </pre>
--   
--   We then compile this to an executable:
--   
--   <pre>
--   $ clash --make createRomFile.hs
--   </pre>
--   
--   We can then use this utility to convert our <tt>Data.txt</tt> file
--   which contains <a>Double</a>s to a <tt>Data.bin</tt> file which will
--   containing the desired ASCII-encoded binary data:
--   
--   <pre>
--   $ ./createRomFile Data.txt Data.bin
--   </pre>
--   
--   Which results in a <tt>Data.bin</tt> file containing:
--   
--   <pre>
--   0000000100110011
--   0000001000000000
--   0000001100000000
--   0000010000000000
--   1111111100000000
--   1111111000000000
--   1111110010000000
--   1111110000000000
--   </pre>
--   
--   We can then use this <tt>Data.bin</tt> file in for our ROM:
--   
--   <pre>
--   romF :: Unsigned 3 -&gt; Unsigned 3 -&gt; SFixed 8 8
--   romF rowAddr colAddr = <a>unpack</a>
--                        $ <a>asyncRomFile</a> d8 "Data.bin" ((rowAddr * 4) + colAddr)
--   </pre>
--   
--   And see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; romF 1 2</b>
--   -3.5
--   <b>&gt;&gt;&gt; romF 0 0</b>
--   1.19921875
--   </pre>
--   
--   <h2>Using Template Haskell</h2>
--   
--   For those of us who like to live on the edge, another option is to
--   convert our <tt>Data.txt</tt> at compile-time using <a>Template
--   Haskell</a>. For this we first create a module
--   <tt>CreateRomFileTH.hs</tt>:
--   
--   <pre>
--   module CreateRomFileTH (romDataFromFile) where
--   
--   import Clash.Prelude
--   import Clash.Prelude.ROM.File
--   import qualified Data.List as L
--   import Language.Haskell.TH (ExpQ, litE, stringL)
--   import Language.Haskell.TH.Syntax (qRunIO)
--   
--   createRomFile :: BitPack a =&gt; (Double -&gt; a)
--                 -&gt; FilePath -&gt; FilePath -&gt; IO ()
--   createRomFile convert fileR fileW = do
--     f &lt;- readFile fileR
--     let ds :: [Double]
--         ds = L.concat . (L.map . L.map) read . L.map words $ lines f
--         fes = L.map convert ds
--     writeFile fileW (<a>memFile</a> Nothing fes)
--   
--   romDataFromFile :: BitPack a =&gt; (Double -&gt; a) -&gt; String -&gt; ExpQ
--   romDataFromFile convert fileR = do
--     let fileW = fileR L.++ ".bin"
--     qRunIO (createRomFile convert fileR fileW)
--     litE (stringL fileW)
--   </pre>
--   
--   Instead of first converting <tt>Data.txt</tt> to <tt>Data.bin</tt>, we
--   will now use the <tt>romDataFromFile</tt> function to convert
--   <tt>Data.txt</tt> to a new file in the proper format at compile-time
--   of our new <tt>romF'</tt> function:
--   
--   <pre>
--   import Clash.Prelude
--   import CreateRomFileTH
--   
--   romF' :: Unsigned 3 -&gt; Unsigned 3 -&gt; SFixed 8 8
--   romF' rowAddr colAddr = unpack $
--     asyncRomFile d8
--                  $(romDataFromFile (fLitR :: Double -&gt; SFixed 8 8) "Data.txt") -- Template Haskell splice
--                  ((rowAddr * 4) + colAddr)
--   </pre>
--   
--   And see that it works just like the <tt>romF</tt> function from
--   earlier:
--   
--   <pre>
--   <b>&gt;&gt;&gt; romF' 1 2</b>
--   -3.5
--   <b>&gt;&gt;&gt; romF' 0 0</b>
--   1.19921875
--   </pre>
fLitR :: forall rep int frac size. (size ~ (int + frac), KnownNat frac, Bounded (rep size), Integral (rep size)) => Double -> Fixed rep int frac

-- | <a>Fixed</a>-point number
--   
--   Where:
--   
--   <ul>
--   <li><tt>rep</tt> is the underlying representation</li>
--   <li><tt>int</tt> is the number of bits used to represent the integer
--   part</li>
--   <li><tt>frac</tt> is the number of bits used to represent the
--   fractional part</li>
--   </ul>
--   
--   The <a>Num</a> operators for this type saturate to <a>maxBound</a> on
--   overflow and <a>minBound</a> on underflow, and use truncation as the
--   rounding method.
--   
--   Fixed has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Fixed
--   type role Fixed representational nominal nominal
--   ...
--   </pre>
--   
--   as it is safe to coerce between different compatible underlying types,
--   but not necessasrily safe to coerce between different widths of this
--   type. To change the width, use the functions in the <a>Resize</a>
--   class.
newtype Fixed (rep :: Nat -> Type) (int :: Nat) (frac :: Nat)
Fixed :: rep (int + frac) -> Fixed (rep :: Nat -> Type) (int :: Nat) (frac :: Nat)
[unFixed] :: Fixed (rep :: Nat -> Type) (int :: Nat) (frac :: Nat) -> rep (int + frac)

-- | Saturating resize operation, truncates for rounding
--   
--   <pre>
--   &gt;&gt;&gt; 0.8125 :: SFixed 3 4
--   0.8125
--   
--   &gt;&gt;&gt; resizeF (0.8125 :: SFixed 3 4) :: SFixed 2 3
--   0.75
--   
--   &gt;&gt;&gt; 3.4 :: SFixed 3 4
--   3.375
--   
--   &gt;&gt;&gt; resizeF (3.4 :: SFixed 3 4) :: SFixed 2 3
--   1.875
--   
--   &gt;&gt;&gt; maxBound :: SFixed 2 3
--   1.875
--   </pre>
--   
--   When used in a polymorphic setting, use the following <a>Constraint
--   synonyms</a> for less verbose type signatures:
--   
--   <ul>
--   <li><tt><a>ResizeFC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>Fixed</a> rep int1 frac1 -&gt; <a>Fixed</a> rep int2
--   frac2</tt></li>
--   <li><tt><a>ResizeSFC</a> int1 frac1 int2 frac2</tt> for:
--   <tt><a>SFixed</a> int1 frac1 -&gt; <a>SFixed</a> int2 frac2</tt></li>
--   <li><tt><a>ResizeUFC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>UFixed</a> int1 frac1 -&gt; <a>UFixed</a> int2 frac2</tt></li>
--   </ul>
resizeF :: forall rep int1 frac1 int2 frac2. ResizeFC rep int1 frac1 int2 frac2 => Fixed rep int1 frac1 -> Fixed rep int2 frac2

-- | Get the position of the virtual <tt>point</tt> of a
--   <a>Fixed</a>-<tt>point</tt> number
fracShift :: KnownNat frac => Fixed rep int frac -> Int

-- | Constraint for the <a>Num</a> instance of <a>SFixed</a>
type NumSFixedC int frac = (KnownNat ((int + int) + (frac + frac)), KnownNat (frac + frac), KnownNat (int + int), KnownNat (int + frac), KnownNat frac, KnownNat int)

-- | Constraint for the <a>ExtendingNum</a> instance of <a>SFixed</a>
type ENumSFixedC int1 frac1 int2 frac2 = (KnownNat (int2 + frac2), KnownNat (1 + Max int1 int2 + Max frac1 frac2), KnownNat (Max frac1 frac2), KnownNat (1 + Max int1 int2), KnownNat (int1 + frac1), KnownNat frac2, KnownNat int2, KnownNat frac1, KnownNat int1)

-- | Constraint for the <a>Fractional</a> instance of <a>SFixed</a>
type FracSFixedC int frac = (NumSFixedC int frac, KnownNat ((int + frac + 1) + (int + frac)))

-- | Constraint for the <a>resizeF</a> function, specialized for
--   <a>SFixed</a>
type ResizeSFC int1 frac1 int2 frac2 = (KnownNat int1, KnownNat frac1, KnownNat int2, KnownNat frac2, KnownNat (int2 + frac2), KnownNat (int1 + frac1))

-- | Constraint for the <a>divide</a> function, specialized for
--   <a>SFixed</a>
type DivideSC int1 frac1 int2 frac2 = (KnownNat (((int1 + frac2) + 1) + (int2 + frac1)), KnownNat frac2, KnownNat int2, KnownNat frac1, KnownNat int1)

-- | Constraint for the <a>Num</a> instance of <a>UFixed</a>
type NumUFixedC int frac = NumSFixedC int frac

-- | Constraint for the <a>ExtendingNum</a> instance of <a>UFixed</a>
type ENumUFixedC int1 frac1 int2 frac2 = ENumSFixedC int1 frac1 int2 frac2

-- | Constraint for the <a>Fractional</a> instance of <a>UFixed</a>
type FracUFixedC int frac = FracSFixedC int frac

-- | Constraint for the <a>resizeF</a> function, specialized for
--   <a>UFixed</a>
type ResizeUFC int1 frac1 int2 frac2 = ResizeSFC int1 frac1 int2 frac2

-- | Constraint for the <a>divide</a> function, specialized for
--   <a>UFixed</a>
type DivideUC int1 frac1 int2 frac2 = DivideSC int1 frac1 int2 frac2

-- | Constraint for the <a>Num</a> instance of <a>Fixed</a>
type NumFixedC rep int frac = (SaturatingNum (rep (int + frac)), ExtendingNum (rep (int + frac)) (rep (int + frac)), MResult (rep (int + frac)) (rep (int + frac)) ~ rep ((int + int) + (frac + frac)), BitSize (rep ((int + int) + (frac + frac))) ~ (int + ((int + frac) + frac)), BitPack (rep ((int + int) + (frac + frac))), Bits (rep ((int + int) + (frac + frac))), BitPack (rep (int + frac)), Bits (rep (int + frac)), Integral (rep (int + frac)), Resize rep, Typeable rep, KnownNat int, KnownNat frac)

-- | Constraint for the <a>ExtendingNum</a> instance of <a>Fixed</a>
type ENumFixedC rep int1 frac1 int2 frac2 = (Bounded (rep ((1 + Max int1 int2) + Max frac1 frac2)), Num (rep ((1 + Max int1 int2) + Max frac1 frac2)), Bits (rep ((1 + Max int1 int2) + Max frac1 frac2)), ExtendingNum (rep (int1 + frac1)) (rep (int2 + frac2)), MResult (rep (int1 + frac1)) (rep (int2 + frac2)) ~ rep ((int1 + int2) + (frac1 + frac2)), KnownNat int1, KnownNat int2, KnownNat frac1, KnownNat frac2, Resize rep)

-- | Constraint for the <a>Fractional</a> instance of <a>Fixed</a>
type FracFixedC rep int frac = (NumFixedC rep int frac, DivideC rep int frac int frac)

-- | Constraint for the <a>resizeF</a> function
type ResizeFC rep int1 frac1 int2 frac2 = (Resize rep, Ord (rep (int1 + frac1)), Num (rep (int1 + frac1)), Bits (rep (int1 + frac1)), Bits (rep (int2 + frac2)), Bounded (rep (int2 + frac2)), KnownNat int1, KnownNat frac1, KnownNat int2, KnownNat frac2)

-- | Constraint for the <a>divide</a> function
type DivideC rep int1 frac1 int2 frac2 = (Resize rep, Integral (rep (((int1 + frac2) + 1) + (int2 + frac1))), Bits (rep (((int1 + frac2) + 1) + (int2 + frac1))), KnownNat int1, KnownNat frac1, KnownNat int2, KnownNat frac2)

-- | <a>Fixed</a> as a <a>Proxy</a> for it's representation type
--   <tt>rep</tt>
asRepProxy :: Fixed rep int frac -> Proxy rep

-- | <a>Fixed</a> as a <a>Proxy</a> for the number of integer bits
--   <tt>int</tt>
asIntProxy :: Fixed rep int frac -> Proxy int
instance Control.DeepSeq.NFData (rep (int GHC.TypeNats.+ frac)) => Control.DeepSeq.NFData (Clash.Sized.Fixed.Fixed rep int frac)
instance (Data.Typeable.Internal.Typeable rep, Data.Typeable.Internal.Typeable int, Data.Typeable.Internal.Typeable frac, Data.Data.Data (rep (int GHC.TypeNats.+ frac))) => Data.Data.Data (Clash.Sized.Fixed.Fixed rep int frac)
instance GHC.Classes.Eq (rep (int GHC.TypeNats.+ frac)) => GHC.Classes.Eq (Clash.Sized.Fixed.Fixed rep int frac)
instance GHC.Classes.Ord (rep (int GHC.TypeNats.+ frac)) => GHC.Classes.Ord (Clash.Sized.Fixed.Fixed rep int frac)
instance GHC.Enum.Bounded (rep (int GHC.TypeNats.+ frac)) => GHC.Enum.Bounded (Clash.Sized.Fixed.Fixed rep int frac)
instance Data.Default.Class.Default (rep (int GHC.TypeNats.+ frac)) => Data.Default.Class.Default (Clash.Sized.Fixed.Fixed rep int frac)
instance Test.QuickCheck.Arbitrary.Arbitrary (rep (int GHC.TypeNats.+ frac)) => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Fixed.Fixed rep int frac)
instance Test.QuickCheck.Arbitrary.CoArbitrary (rep (int GHC.TypeNats.+ frac)) => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Fixed.Fixed rep int frac)
instance Data.Bits.FiniteBits (rep (int GHC.TypeNats.+ frac)) => Data.Bits.FiniteBits (Clash.Sized.Fixed.Fixed rep int frac)
instance Data.Bits.Bits (rep (int GHC.TypeNats.+ frac)) => Data.Bits.Bits (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.FracFixedC rep int frac => GHC.Real.Fractional (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.FracFixedC rep int frac => GHC.Real.RealFrac (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.NumFixedC rep int frac => GHC.Num.Num (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.NumFixedC rep int frac => GHC.Enum.Enum (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.NumFixedC rep int frac => Clash.Class.Num.SaturatingNum (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.NumFixedC rep int frac => GHC.Real.Real (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.ENumFixedC rep int1 frac1 int2 frac2 => Clash.Class.Num.ExtendingNum (Clash.Sized.Fixed.Fixed rep int1 frac1) (Clash.Sized.Fixed.Fixed rep int2 frac2)
instance (size GHC.Types.~ (int GHC.TypeNats.+ frac), GHC.TypeNats.KnownNat frac, GHC.Real.Integral (rep size)) => GHC.Show.Show (Clash.Sized.Fixed.Fixed rep int frac)
instance (size GHC.Types.~ (int GHC.TypeNats.+ frac), GHC.TypeNats.KnownNat frac, GHC.Real.Integral (rep size)) => Clash.XException.ShowX (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.XException.NFDataX (rep (int GHC.TypeNats.+ frac)) => Clash.XException.NFDataX (Clash.Sized.Fixed.Fixed rep int frac)
instance (size GHC.Types.~ (int GHC.TypeNats.+ frac), GHC.TypeNats.KnownNat frac, GHC.Enum.Bounded (rep size), GHC.Real.Integral (rep size)) => GHC.Read.Read (Clash.Sized.Fixed.Fixed rep int frac)
instance (Clash.Class.BitPack.Internal.BitPack (rep (int GHC.TypeNats.+ frac)), GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.BitSize (rep (int GHC.TypeNats.+ frac)))) => Clash.Class.BitPack.Internal.BitPack (Clash.Sized.Fixed.Fixed rep int frac)
instance (Language.Haskell.TH.Syntax.Lift (rep (int GHC.TypeNats.+ frac)), GHC.TypeNats.KnownNat frac, GHC.TypeNats.KnownNat int, Data.Typeable.Internal.Typeable rep) => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Fixed.Fixed rep int frac)


module Clash.Sized.Internal.Index

-- | Arbitrarily-bounded unsigned integer represented by
--   <tt>ceil(log_2(n))</tt> bits
--   
--   Given an upper bound <tt>n</tt>, an <a>Index</a> <tt>n</tt> number has
--   a range of: [0 .. <tt>n</tt>-1]
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Index 8
--   7
--   
--   &gt;&gt;&gt; minBound :: Index 8
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Index 8)) :: Index 8
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Index 8
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Index 8
--   *** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 1 - 3 :: Index 8
--   *** Exception: X: Clash.Sized.Index: result -2 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 2 * 3 :: Index 8
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Index 8
--   *** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   </pre>
--   
--   <b>NB</b>: The usual Haskell method of converting an integral numeric
--   type to another, <a>fromIntegral</a>, is not well suited for Clash as
--   it will go through <a>Integer</a> which is arbitrarily bounded in HDL.
--   Instead use <a>bitCoerce</a> and the <a>Resize</a> class.
--   
--   Index has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Index
--   type role Index nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between <a>Index</a>es with different
--   ranges. To change the size, use the functions in the <a>Resize</a>
--   class.
newtype Index (n :: Nat)

-- | The constructor, <a>I</a>, and the field, <a>unsafeToInteger</a>, are
--   not synthesizable.
I :: Integer -> Index (n :: Nat)
[unsafeToInteger] :: Index (n :: Nat) -> Integer

-- | Safely convert an <a>SNat</a> value to an <a>Index</a>
fromSNat :: (KnownNat m, (n + 1) <= m) => SNat n -> Index m
size# :: (KnownNat n, 1 <= n) => Index n -> Int
pack# :: Index n -> BitVector (CLog 2 n)
unpack# :: (KnownNat n, 1 <= n) => BitVector (CLog 2 n) -> Index n
eq# :: Index n -> Index n -> Bool
neq# :: Index n -> Index n -> Bool
lt# :: Index n -> Index n -> Bool
ge# :: Index n -> Index n -> Bool
gt# :: Index n -> Index n -> Bool
le# :: Index n -> Index n -> Bool
toEnum# :: forall n. KnownNat n => Int -> Index n
fromEnum# :: forall n. KnownNat n => Index n -> Int
enumFrom# :: forall n. KnownNat n => Index n -> [Index n]
enumFromThen# :: forall n. KnownNat n => Index n -> Index n -> [Index n]
enumFromTo# :: Index n -> Index n -> [Index n]
enumFromThenTo# :: Index n -> Index n -> Index n -> [Index n]
maxBound# :: forall n. KnownNat n => Index n
(+#) :: KnownNat n => Index n -> Index n -> Index n
(-#) :: KnownNat n => Index n -> Index n -> Index n
(*#) :: KnownNat n => Index n -> Index n -> Index n
negate# :: KnownNat n => Index n -> Index n
fromInteger# :: KnownNat n => Integer -> Index n
plus# :: Index m -> Index n -> Index ((m + n) - 1)
minus# :: Index m -> Index n -> Index ((m + n) - 1)
times# :: Index m -> Index n -> Index (((m - 1) * (n - 1)) + 1)
quot# :: Index n -> Index n -> Index n
rem# :: Index n -> Index n -> Index n
toInteger# :: Index n -> Integer
resize# :: KnownNat m => Index n -> Index m
instance GHC.Generics.Generic (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.Index.Index n)
instance Control.DeepSeq.NFData (Clash.Sized.Internal.Index.Index n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Clash.Class.BitPack.Internal.BitPack (Clash.Sized.Internal.Index.Index n)
instance GHC.Classes.Eq (Clash.Sized.Internal.Index.Index n)
instance GHC.Classes.Ord (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.Index.Index n)
instance Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.Index.Index m) (Clash.Sized.Internal.Index.Index n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Text.Printf.PrintfArg (Clash.Sized.Internal.Index.Index n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Clash.Class.Parity.Parity (Clash.Sized.Internal.Index.Index n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Data.Bits.Bits (Clash.Sized.Internal.Index.Index n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Data.Bits.FiniteBits (Clash.Sized.Internal.Index.Index n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.Index.Index
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.Index.Index n)
instance GHC.Show.Show (Clash.Sized.Internal.Index.Index n)
instance Clash.XException.ShowX (Clash.Sized.Internal.Index.Index n)
instance Clash.XException.NFDataX (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Read.Read (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Data.Default.Class.Default (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Ix.Ix (Clash.Sized.Internal.Index.Index n)


module Clash.Sized.Index

-- | Arbitrarily-bounded unsigned integer represented by
--   <tt>ceil(log_2(n))</tt> bits
--   
--   Given an upper bound <tt>n</tt>, an <a>Index</a> <tt>n</tt> number has
--   a range of: [0 .. <tt>n</tt>-1]
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Index 8
--   7
--   
--   &gt;&gt;&gt; minBound :: Index 8
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Index 8)) :: Index 8
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Index 8
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Index 8
--   *** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 1 - 3 :: Index 8
--   *** Exception: X: Clash.Sized.Index: result -2 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 2 * 3 :: Index 8
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Index 8
--   *** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   </pre>
--   
--   <b>NB</b>: The usual Haskell method of converting an integral numeric
--   type to another, <a>fromIntegral</a>, is not well suited for Clash as
--   it will go through <a>Integer</a> which is arbitrarily bounded in HDL.
--   Instead use <a>bitCoerce</a> and the <a>Resize</a> class.
--   
--   Index has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Index
--   type role Index nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce between <a>Index</a>es with different
--   ranges. To change the size, use the functions in the <a>Resize</a>
--   class.
data Index (n :: Nat)

-- | An alternative implementation of <a>unpack</a> for the <a>Index</a>
--   data type; for when you know the size of the <a>BitVector</a> and want
--   to determine the size of the <a>Index</a>.
--   
--   That is, the type of <a>unpack</a> is:
--   
--   <pre>
--   <b>unpack</b> :: <a>BitVector</a> (<a>CLog</a> 2 n) -&gt; <a>Index</a> n
--   </pre>
--   
--   And is useful when you know the size of the <a>Index</a>, and want to
--   get a value from a <a>BitVector</a> that is large enough (<tt>CLog 2
--   n</tt>) enough to hold an <a>Index</a>. Note that <a>unpack</a> can
--   fail at <i>run-time</i> when the value inside the <a>BitVector</a> is
--   higher than 'n-1'.
--   
--   <a>bv2i</a> on the other hand will <i>never</i> fail at run-time,
--   because the <a>BitVector</a> argument determines the size.
bv2i :: KnownNat n => BitVector n -> Index (2 ^ n)

-- | Safely convert an <a>SNat</a> value to an <a>Index</a>
fromSNat :: (KnownNat m, (n + 1) <= m) => SNat n -> Index m


module Clash.Sized.Vector

-- | Fixed size vectors.
--   
--   <ul>
--   <li>Lists with their length encoded in their type</li>
--   <li><a>Vec</a>tor elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.</li>
--   </ul>
data Vec :: Nat -> Type -> Type
[Nil] :: Vec 0 a
[Cons] :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the head of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; 3:&gt;4:&gt;5:&gt;Nil
--   3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = 3:&gt;4:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 3 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (x :&gt; y :&gt; _) = x + y
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   7
--   </pre>
--   
--   Also in conjunctions with (<a>:&lt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:>) :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the tail of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   3 :&gt; 4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 4 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (_ :&lt; y :&lt; x) = y + x
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   13
--   </pre>
--   
--   Also in conjunctions with (<a>:&gt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:<) :: Vec n a -> a -> Vec (n + 1) a
infixr 5 :>
infixl 5 :<
infixr 5 `Cons`

-- | The length of a <a>Vec</a>tor as an <a>Int</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; length (6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   3
--   </pre>
length :: KnownNat n => Vec n a -> Int

-- | Length of a <a>Vec</a>tor as an <a>SNat</a> value
lengthS :: KnownNat n => Vec n a -> SNat n

-- | "<tt>xs</tt> <a>!!</a> <tt>n</tt>" returns the <i>n</i>'th element of
--   <i>xs</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 4
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! (length (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) - 1)
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 1
--   2
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 4
--   ...
--   </pre>
(!!) :: (KnownNat n, Enum i) => Vec n a -> i -> a

-- | Extract the first element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; head (1:&gt;2:&gt;3:&gt;Nil)
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; head Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘head’, namely ‘Nil’
--         In the expression: head Nil
--         In an equation for ‘it’: it = head Nil
--   </pre>
head :: Vec (n + 1) a -> a

-- | Extract the last element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; last (1:&gt;2:&gt;3:&gt;Nil)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; last Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘last’, namely ‘Nil’
--         In the expression: last Nil
--         In an equation for ‘it’: it = last Nil
--   </pre>
last :: Vec (n + 1) a -> a

-- | "<a>at</a> <tt>n xs</tt>" returns <i>n</i>'th element of <i>xs</i>
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; at (SNat :: SNat 1) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   
--   &gt;&gt;&gt; at d1               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   </pre>
at :: SNat m -> Vec (m + (n + 1)) a -> a

-- | Generate a vector of indices.
--   
--   <pre>
--   &gt;&gt;&gt; indices d4
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indices :: KnownNat n => SNat n -> Vec n (Index n)

-- | Generate a vector of indices, where the length of the vector is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; indicesI :: Vec 4 (Index 4)
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indicesI :: KnownNat n => Vec n (Index n)

-- | "<a>findIndex</a> <tt>p xs</tt>" returns the index of the <i>first</i>
--   element of <i>xs</i> satisfying the predicate <i>p</i>, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 3) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 3
--   
--   &gt;&gt;&gt; findIndex (&gt; 8) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
findIndex :: KnownNat n => (a -> Bool) -> Vec n a -> Maybe (Index n)

-- | "<a>elemIndex</a> <tt>a xs</tt>" returns the index of the <i>first</i>
--   element which is equal (by <a>==</a>) to the query element <i>a</i>,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndex 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; elemIndex 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
elemIndex :: (KnownNat n, Eq a) => a -> Vec n a -> Maybe (Index n)

-- | Extract the elements after the head of a vector
--   
--   <pre>
--   &gt;&gt;&gt; tail (1:&gt;2:&gt;3:&gt;Nil)
--   2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; tail Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘tail’, namely ‘Nil’
--         In the expression: tail Nil
--         In an equation for ‘it’: it = tail Nil
--   </pre>
tail :: Vec (n + 1) a -> Vec n a

-- | Extract all the elements of a vector except the last element
--   
--   <pre>
--   &gt;&gt;&gt; init (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; init Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘init’, namely ‘Nil’
--         In the expression: init Nil
--         In an equation for ‘it’: it = init Nil
--   </pre>
init :: Vec (n + 1) a -> Vec n a

-- | "<a>take</a> <tt>n xs</tt>" returns the <i>n</i>-length prefix of
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; take (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d0               (1:&gt;2:&gt;Nil)
--   Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘4 + n0’ with ‘2’
--         Expected type: Vec (4 + n0) a
--           Actual type: Vec (1 + 1) a
--         The type variable ‘n0’ is ambiguous
--       • In the second argument of ‘take’, namely ‘(1 :&gt; 2 :&gt; Nil)’
--         In the expression: take d4 (1 :&gt; 2 :&gt; Nil)
--         In an equation for ‘it’: it = take d4 (1 :&gt; 2 :&gt; Nil)
--   </pre>
take :: SNat m -> Vec (m + n) a -> Vec m a

-- | "<a>takeI</a> <tt>xs</tt>" returns the prefix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; takeI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   1 :&gt; 2 :&gt; Nil
--   </pre>
takeI :: KnownNat m => Vec (m + n) a -> Vec m a

-- | "<a>drop</a> <tt>n xs</tt>" returns the suffix of <i>xs</i> after the
--   first <i>n</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; drop (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d0               (1:&gt;2:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; drop d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...: error:...
--       • Couldn't match...type ‘4 + n0...
--         The type variable ‘n0’ is ambiguous
--       • In the first argument of ‘print’, namely ‘it’
--         In a stmt of an interactive GHCi command: print it
--   </pre>
drop :: SNat m -> Vec (m + n) a -> Vec n a

-- | "<a>dropI</a> <tt>xs</tt>" returns the suffix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; dropI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   4 :&gt; 5 :&gt; Nil
--   </pre>
dropI :: KnownNat m => Vec (m + n) a -> Vec n a

-- | "<a>select</a> <tt>f s n xs</tt>" selects <i>n</i> elements with
--   step-size <i>s</i> and offset <tt>f</tt> from <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; select (SNat :: SNat 1) (SNat :: SNat 2) (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; select d1 d2 d3 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   </pre>
select :: CmpNat (i + s) (s * n) ~ 'GT => SNat f -> SNat s -> SNat n -> Vec (f + i) a -> Vec n a

-- | "<a>selectI</a> <tt>f s xs</tt>" selects as many elements as demanded
--   by the context with step-size <i>s</i> and offset <i>f</i> from
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; selectI d1 d2 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil) :: Vec 2 Int
--   2 :&gt; 4 :&gt; Nil
--   </pre>
selectI :: (CmpNat (i + s) (s * n) ~ 'GT, KnownNat n) => SNat f -> SNat s -> Vec (f + i) a -> Vec n a

-- | Split a vector into two vectors at the given point.
--   
--   <pre>
--   &gt;&gt;&gt; splitAt (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   
--   &gt;&gt;&gt; splitAt d3 (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAt :: SNat m -> Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector into two vectors where the length of the two is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; splitAtI (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil) :: (Vec 2 Int, Vec 3 Int)
--   (1 :&gt; 2 :&gt; Nil,3 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAtI :: KnownNat m => Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector of (n * m) elements into a vector of "vectors of length
--   <i>m</i>", where the length <i>m</i> is given.
--   
--   <pre>
--   &gt;&gt;&gt; unconcat d4 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcat :: KnownNat n => SNat m -> Vec (n * m) a -> Vec n (Vec m a)

-- | Split a vector of <i>(n * m)</i> elements into a vector of "vectors of
--   length <i>m</i>", where the length <i>m</i> is determined by the
--   context.
--   
--   <pre>
--   &gt;&gt;&gt; unconcatI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil) :: Vec 2 (Vec 6 Int)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcatI :: (KnownNat n, KnownNat m) => Vec (n * m) a -> Vec n (Vec m a)

-- | Create a vector of one element
--   
--   <pre>
--   &gt;&gt;&gt; singleton 5
--   5 :&gt; Nil
--   </pre>
singleton :: a -> Vec 1 a

-- | "<a>replicate</a> <tt>n a</tt>" returns a vector that has <i>n</i>
--   copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; replicate (SNat :: SNat 3) 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; replicate d3 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
replicate :: SNat n -> a -> Vec n a

-- | "<a>repeat</a> <tt>a</tt>" creates a vector with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; repeat 6 :: Vec 5 Int
--   6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
repeat :: KnownNat n => a -> Vec n a

-- | "<a>iterate</a> <tt>n f x</tt>" returns a vector starting with
--   <i>x</i> followed by <i>n</i> repeated applications of <i>f</i> to
--   <i>x</i>.
--   
--   <pre>
--   iterate (SNat :: SNat 4) f x == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   iterate d4 f x               == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterate d4 (+1) 1
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>iterate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
iterate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>iterateI</a> <tt>f x</tt>" returns a vector starting with
--   <tt>x</tt> followed by <tt>n</tt> repeated applications of <tt>f</tt>
--   to <tt>x</tt>, where <tt>n</tt> is determined by the context.
--   
--   <pre>
--   iterateI f x :: Vec 3 a == (x :&gt; f x :&gt; f (f x) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterateI (+1) 1 :: Vec 3 Int
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   "<a>iterateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
iterateI :: forall n a. KnownNat n => (a -> a) -> a -> Vec n a

-- | "<a>generate</a> <tt>n f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>.
--   
--   <pre>
--   generate (SNat :: SNat 4) f x == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   generate d4 f x               == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generate d4 (+1) 1
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>generate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
generate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>generateI</a> <tt>f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>, where <tt>n</tt> is
--   determined by the context.
--   
--   <pre>
--   generateI f x :: Vec 3 a == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generateI (+1) 1 :: Vec 3 Int
--   2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>generateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
generateI :: KnownNat n => (a -> a) -> a -> Vec n a

-- | "<a>unfoldr</a> <tt>n f s</tt>" builds a vector of length <tt>n</tt>
--   from a seed value <tt>s</tt>, where every element <tt>a</tt> is
--   created by successive calls of <tt>f</tt> on <tt>s</tt>. Unlike
--   <a>unfoldr</a> from <a>Data.List</a> the generating function
--   <tt>f</tt> cannot dictate the length of the resulting vector, it must
--   be statically known.
--   
--   a simple use of <a>unfoldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr d10 (\s -&gt; (s,s-1)) 10
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldr :: SNat n -> (s -> (a, s)) -> s -> Vec n a

-- | "<a>unfoldrI</a> <tt>f s</tt>" builds a vector from a seed value
--   <tt>s</tt>, where every element <tt>a</tt> is created by successive
--   calls of <tt>f</tt> on <tt>s</tt>; the length of the vector is
--   inferred from the context. Unlike <a>unfoldr</a> from <a>Data.List</a>
--   the generating function <tt>f</tt> cannot dictate the length of the
--   resulting vector, it must be statically known.
--   
--   a simple use of <a>unfoldrI</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldrI (\s -&gt; (s,s-1)) 10 :: Vec 10 Int
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldrI :: KnownNat n => (s -> (a, s)) -> s -> Vec n a

-- | Create a vector literal from a list literal.
--   
--   <pre>
--   $(listToVecTH [1::Signed 8,2,3,4,5]) == (8:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 5 (Signed 8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1 :: Signed 8,2,3,4,5]
--   [1,2,3,4,5]
--   
--   &gt;&gt;&gt; $(listToVecTH [1::Signed 8,2,3,4,5])
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
listToVecTH :: Lift a => [a] -> ExpQ

-- | Append two vectors.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;Nil) ++ (7:&gt;8:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 8 :&gt; Nil
--   </pre>
(++) :: Vec n a -> Vec m a -> Vec (n + m) a
infixr 5 ++

-- | Add an element to the head of a vector, and extract all but the last
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; 1 +&gt;&gt; Nil
--   Nil
--   </pre>
(+>>) :: KnownNat n => a -> Vec n a -> Vec n a
infixr 4 +>>

-- | Add an element to the tail of a vector, and extract all but the first
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) &lt;&lt;+ 1
--   4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; Nil &lt;&lt;+ 1
--   Nil
--   </pre>
(<<+) :: Vec n a -> a -> Vec n a
infixl 4 <<+

-- | Concatenate a vector of vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concat ((1:&gt;2:&gt;3:&gt;Nil) :&gt; (4:&gt;5:&gt;6:&gt;Nil) :&gt; (7:&gt;8:&gt;9:&gt;Nil) :&gt; (10:&gt;11:&gt;12:&gt;Nil) :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil
--   </pre>
concat :: Vec n (Vec m a) -> Vec (n * m) a

-- | Map a function over all the elements of a vector and concatentate the
--   resulting vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concatMap (replicate d3) (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 1 :&gt; 1 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; 3 :&gt; 3 :&gt; 3 :&gt; Nil
--   </pre>
concatMap :: (a -> Vec m b) -> Vec n a -> Vec (n * m) b

-- | Shift in elements to the head of a vector, bumping out elements at the
--   tail. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; Nil,3 :&gt; 4 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; Nil,0 :&gt; 1 :&gt; Nil)
--   </pre>
shiftInAt0 :: KnownNat n => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift in element to the tail of a vector, bumping out elements at the
--   head. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; Nil)
--   (3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; Nil) (2 :&gt; 3 :&gt; Nil)
--   (3 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftInAtN :: KnownNat m => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift <i>m</i> elements out from the head of a vector, filling up the
--   tail with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFrom0 d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (3 :&gt; 4 :&gt; 5 :&gt; 0 :&gt; 0 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftOutFrom0 :: (Default a, KnownNat m) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Shift <i>m</i> elements out from the tail of a vector, filling up the
--   head with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFromN d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (0 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil,4 :&gt; 5 :&gt; Nil)
--   </pre>
shiftOutFromN :: (Default a, KnownNat n) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Merge two vectors, alternating their elements, i.e.,
--   
--   <pre>
--   &gt;&gt;&gt; merge (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   1 :&gt; 5 :&gt; 2 :&gt; 6 :&gt; 3 :&gt; 7 :&gt; 4 :&gt; 8 :&gt; Nil
--   </pre>
merge :: KnownNat n => Vec n a -> Vec n a -> Vec (2 * n) a

-- | "<a>replace</a> <tt>n a xs</tt>" returns the vector <i>xs</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; replace 3 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 0 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   7 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 9 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; *** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 4
--   ...
--   </pre>
replace :: (KnownNat n, Enum i) => i -> a -> Vec n a -> Vec n a

-- | Forward permutation specified by an index mapping, <i>ix</i>. The
--   result vector is initialized by the given defaults, <i>def</i>, and an
--   further values that are permuted into the result are added to the
--   current value using the given combination function, <i>f</i>.
--   
--   The combination function must be <i>associative</i> and
--   <i>commutative</i>.
permute :: (Enum i, KnownNat n, KnownNat m) => (a -> a -> a) -> Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>backpermute</a> <tt>xs is</tt>" is equivalent to "<a>map</a>
--   <tt>(xs <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; backpermute input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
backpermute :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | Copy elements from the source vector, <i>xs</i>, to the destination
--   vector according to an index mapping <i>is</i>. This is a forward
--   permute operation where a <i>to</i> vector encodes an input to output
--   index mapping. Output elements for indices that are not mapped assume
--   the value in the default vector <i>def</i>.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let defVec = 0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;Nil
--   
--   &gt;&gt;&gt; let to = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;8:&gt;Nil
--   
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; scatter defVec to input
--   0 :&gt; 1 :&gt; 4 :&gt; 9 :&gt; 0 :&gt; 4 :&gt; 0 :&gt; 6 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: If the same index appears in the index mapping more than
--   once, the latest mapping is chosen.
scatter :: (Enum i, KnownNat n, KnownNat m) => Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>gather</a> <tt>xs is</tt>" is equivalent to "<a>map</a> <tt>(xs
--   <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; gather input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
gather :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | The elements in a vector in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; reverse (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
reverse :: Vec n a -> Vec n a

-- | Transpose a matrix: go from row-major to column-major
--   
--   <pre>
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;Nil):&gt;(3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; transpose xss
--   (1 :&gt; 3 :&gt; 5 :&gt; Nil) :&gt; (2 :&gt; 4 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
transpose :: KnownNat n => Vec m (Vec n a) -> Vec n (Vec m a)

-- | "<a>interleave</a> <tt>d xs</tt>" creates a vector:
--   
--   <pre>
--   &lt;x_0,x_d,x_(2d),...,x_1,x_(d+1),x_(2d+1),...,x_(d-1),x_(2d-1),x_(3d-1)&gt;
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; Nil
--   
--   &gt;&gt;&gt; interleave d3 xs
--   1 :&gt; 4 :&gt; 7 :&gt; 2 :&gt; 5 :&gt; 8 :&gt; 3 :&gt; 6 :&gt; 9 :&gt; Nil
--   </pre>
interleave :: (KnownNat n, KnownNat d) => SNat d -> Vec (n * d) a -> Vec (d * n) a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs (-1)
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeftS</a> if you want to rotate left by a
--   <i>static</i> amount.
rotateLeft :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs (-1)
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRightS</a> if you want to rotate right by a
--   <i>static</i> amount.
rotateRight :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeftS xs d1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeft</a> if you want to rotate left by a
--   <i>dynamic</i> amount.
rotateLeftS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRightS xs d1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRight</a> if you want to rotate right by a
--   <i>dynamic</i> amount.
rotateRightS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | "<a>map</a> <tt>f xs</tt>" is the vector obtained by applying <i>f</i>
--   to each element of <i>xs</i>, i.e.,
--   
--   <pre>
--   map f (x1 :&gt; x2 :&gt;  ... :&gt; xn :&gt; Nil) == (f x1 :&gt; f x2 :&gt; ... :&gt; f xn :&gt; Nil)
--   </pre>
--   
--   and corresponds to the following circuit layout:
--   
map :: (a -> b) -> Vec n a -> Vec n b

-- | Apply a function of every element of a vector and its index.
--   
--   <pre>
--   &gt;&gt;&gt; :t imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Index 4)
--   
--   &gt;&gt;&gt; imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   2 :&gt; 3 :&gt; *** Exception: X: Clash.Sized.Index: result 4 is out of bounds: [0..3]
--   ...
--   
--   &gt;&gt;&gt; imap (\i a -&gt; extend (bitCoerce i) + a) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Unsigned 8)
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
imap :: forall n a b. KnownNat n => (Index n -> a -> b) -> Vec n a -> Vec n b

-- | Apply a function to every element of a vector and the element's
--   position (as an <a>SNat</a> value) in the vector.
--   
--   <pre>
--   &gt;&gt;&gt; let rotateMatrix = smap (flip rotateRightS)
--   
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; rotateMatrix xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; 1 :&gt; Nil) :&gt; Nil
--   </pre>
smap :: forall k a b. KnownNat k => (forall l. SNat l -> a -> b) -> Vec k a -> Vec k b

-- | <a>zipWith</a> generalizes <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "<a>zipWith</a> <tt>(+)</tt>" applied to two vectors produces
--   the vector of corresponding sums.
--   
--   <pre>
--   zipWith f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) == (f x1 y1 :&gt; f x2 y2 :&gt; ... :&gt; f xn yn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith</a> <tt>f xs ys</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>zipWith</a> is <i>strict</i> in its second argument, and
--   <i>lazy</i> in its third. This matters when <a>zipWith</a> is used in
--   a recursive setting. See <a>lazyV</a> for more information.
zipWith :: (a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>zipWith3</a> generalizes <a>zip3</a> by zipping with the function
--   given as the first argument, instead of a tupling function.
--   
--   <pre>
--   zipWith3 f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) (z1 :&gt; z2 :&gt; ... :&gt; zn :&gt; Nil) == (f x1 y1 z1 :&gt; f x2 y2 z2 :&gt; ... :&gt; f xn yn zn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith3</a> <tt>f xs ys zs</tt>" corresponds to the following
--   circuit layout:
--   
--   
--   <b>NB</b>: <a>zipWith3</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third and fourth. This matters when
--   <a>zipWith3</a> is used in a recursive setting. See <a>lazyV</a> for
--   more information.
zipWith3 :: (a -> b -> c -> d) -> Vec n a -> Vec n b -> Vec n c -> Vec n d
zipWith4 :: (a -> b -> c -> d -> e) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e
zipWith5 :: (a -> b -> c -> d -> e -> f) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f
zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g
zipWith7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n h

-- | <a>zip</a> takes two vectors and returns a vector of corresponding
--   pairs.
--   
--   <pre>
--   &gt;&gt;&gt; zip (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil)
--   (1,4) :&gt; (2,3) :&gt; (3,2) :&gt; (4,1) :&gt; Nil
--   </pre>
zip :: Vec n a -> Vec n b -> Vec n (a, b)

-- | <a>zip3</a> takes three vectors and returns a vector of corresponding
--   triplets.
--   
--   <pre>
--   &gt;&gt;&gt; zip3 (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil) (5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   (1,4,5) :&gt; (2,3,6) :&gt; (3,2,7) :&gt; (4,1,8) :&gt; Nil
--   </pre>
zip3 :: Vec n a -> Vec n b -> Vec n c -> Vec n (a, b, c)

-- | <a>zip4</a> takes four vectors and returns a list of quadruples,
--   analogous to <a>zip</a>.
zip4 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n (a, b, c, d)

-- | <a>zip5</a> takes five vectors and returns a list of five-tuples,
--   analogous to <a>zip</a>.
zip5 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n (a, b, c, d, e)

-- | <a>zip6</a> takes six vectors and returns a list of six-tuples,
--   analogous to <a>zip</a>.
zip6 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n (a, b, c, d, e, f)

-- | <a>zip7</a> takes seven vectors and returns a list of seven-tuples,
--   analogous to <a>zip</a>.
zip7 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n (a, b, c, d, e, f, g)

-- | Zip two vectors with a functions that also takes the elements'
--   indices.
--   
--   <pre>
--   &gt;&gt;&gt; izipWith (\i a b -&gt; i + a + b) (2 :&gt; 2 :&gt; Nil)  (3 :&gt; 3:&gt; Nil)
--   *** Exception: X: Clash.Sized.Index: result 3 is out of bounds: [0..1]
--   ...
--   
--   &gt;&gt;&gt; izipWith (\i a b -&gt; extend (bitCoerce i) + a + b) (2 :&gt; 2 :&gt; Nil) (3 :&gt; 3 :&gt; Nil) :: Vec 2 (Unsigned 8)
--   5 :&gt; 6 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>izipWith</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third. This matters when <a>izipWith</a> is
--   used in a recursive setting. See <a>lazyV</a> for more information.
izipWith :: KnownNat n => (Index n -> a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>unzip</a> transforms a vector of pairs into a vector of first
--   components and a vector of second components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip ((1,4):&gt;(2,3):&gt;(3,2):&gt;(4,1):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   </pre>
unzip :: Vec n (a, b) -> (Vec n a, Vec n b)

-- | <a>unzip3</a> transforms a vector of triplets into a vector of first
--   components, a vector of second components, and a vector of third
--   components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip3 ((1,4,5):&gt;(2,3,6):&gt;(3,2,7):&gt;(4,1,8):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil,5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
unzip3 :: Vec n (a, b, c) -> (Vec n a, Vec n b, Vec n c)

-- | <a>unzip4</a> takes a vector of quadruples and returns four vectors,
--   analogous to <a>unzip</a>.
unzip4 :: Vec n (a, b, c, d) -> (Vec n a, Vec n b, Vec n c, Vec n d)

-- | <a>unzip5</a> takes a vector of five-tuples and returns five vectors,
--   analogous to <a>unzip</a>.
unzip5 :: Vec n (a, b, c, d, e) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e)

-- | <a>unzip6</a> takes a vector of six-tuples and returns six vectors,
--   analogous to <a>unzip</a>.
unzip6 :: Vec n (a, b, c, d, e, f) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f)

-- | <a>unzip7</a> takes a vector of seven-tuples and returns seven
--   vectors, analogous to <a>unzip</a>.
unzip7 :: Vec n (a, b, c, d, e, f, g) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f, Vec n g)

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z (x1 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn1 `f` (xn `f` z))...)
--   foldr r z Nil                             == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldr :: (a -> b -> b) -> b -> Vec n a -> b

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from left to right:
--   
--   <pre>
--   foldl f z (x1 :&gt; x2 :&gt; ... :&gt; xn :&gt; Nil) == (...((z `f` x1) `f` x2) `f`...) `f` xn
--   foldl f z Nil                            == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldl :: (b -> a -> b) -> b -> Vec n a -> b

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldr1 f (x1 :&gt; ... :&gt; xn2 :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn2 `f` (xn1 `f` xn))...)
--   foldr1 f (x1 :&gt; Nil)                            == x1
--   foldr1 f Nil                                    == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (/) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldr1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldl1 f (x1 :&gt; x2 :&gt; x3 :&gt; ... :&gt; xn :&gt; Nil) == (...((x1 `f` x2) `f` x3) `f`...) `f` xn
--   foldl1 f (x1 :&gt; Nil)                          == x1
--   foldl1 f Nil                                  == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (/) (1 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldl1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>fold</a> is a variant of <a>foldr1</a> and <a>foldl1</a>, but
--   instead of reducing from right to left, or left to right, it reduces a
--   vector using a tree-like structure. The depth, or delay, of the
--   structure produced by "<tt><a>fold</a> f xs</tt>", is hence
--   <tt>O(log_2(<a>length</a> xs))</tt>, and not <tt>O(<a>length</a>
--   xs)</tt>.
--   
--   <b>NB</b>: The binary operator "<tt>f</tt>" in "<tt><a>fold</a> f
--   xs</tt>" must be associative.
--   
--   <pre>
--   fold f (x1 :&gt; x2 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == ((x1 `f` x2) `f` ...) `f` (... `f` (xn1 `f` xn))
--   fold f (x1 :&gt; Nil)                           == x1
--   fold f Nil                                   == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fold (+) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   15
--   </pre>
--   
--   "<a>fold</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
fold :: forall n a. (a -> a -> a) -> Vec (n + 1) a -> a

-- | Right fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findLeftmost x xs = ifoldr (\i a b -&gt; if a == x then Just i else b) Nothing xs
--   
--   &gt;&gt;&gt; findLeftmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; findLeftmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldr :: KnownNat n => (Index n -> a -> b -> b) -> b -> Vec n a -> b

-- | Left fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findRightmost x xs = ifoldl (\a i b -&gt; if b == x then Just i else a) Nothing xs
--   
--   &gt;&gt;&gt; findRightmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 4
--   
--   &gt;&gt;&gt; findRightmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldl :: KnownNat n => (a -> Index n -> b -> a) -> a -> Vec n b -> a

-- | A <i>dependently</i> typed fold.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -fplugin GHC.TypeLits.Normalise
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data Append (m :: Nat) (a :: Type) (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply (Append m a) l = Vec (l + m) a
--   
--   &gt;&gt;&gt; let append' xs ys = dfold (Proxy :: Proxy (Append m a)) (const (:&gt;)) ys xs
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   Using lists, we can define <i>append</i> (a.k.a.
--   <tt>Data.List.</tt><a>++</a>) in terms of
--   <tt>Data.List.</tt><a>foldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List
--   
--   &gt;&gt;&gt; let append xs ys = Data.List.foldr (:) ys xs
--   
--   &gt;&gt;&gt; append [1,2] [3,4]
--   [1,2,3,4]
--   </pre>
--   
--   However, when we try to do the same for <a>Vec</a>, by defining
--   <i>append'</i> in terms of <tt>Clash.Sized.Vector.</tt><a>foldr</a>:
--   
--   <pre>
--   append' xs ys = <a>foldr</a> (:&gt;) ys xs
--   </pre>
--   
--   we get a type error:
--   
--   <pre>
--   <b>&gt;&gt;&gt; let append' xs ys = foldr (:&gt;) ys xs</b>
--   
--   &lt;interactive&gt;:...
--       • Occurs check: cannot construct the infinite type: ... ~ ... + 1
--         Expected type: a -&gt; Vec ... a -&gt; Vec ... a
--           Actual type: a -&gt; Vec ... a -&gt; Vec (... + 1) a
--       • In the first argument of ‘foldr’, namely ‘(:&gt;)’
--         In the expression: foldr (:&gt;) ys xs
--         In an equation for ‘append'’: append' xs ys = foldr (:&gt;) ys xs
--       • Relevant bindings include
--           ys :: Vec ... a (bound at ...)
--           append' :: Vec n a -&gt; Vec ... a -&gt; Vec ... a
--             (bound at ...)
--   </pre>
--   
--   The reason is that the type of <a>foldr</a> is:
--   
--   <pre>
--   &gt;&gt;&gt; :t foldr
--   foldr :: (a -&gt; b -&gt; b) -&gt; b -&gt; Vec n a -&gt; b
--   </pre>
--   
--   While the type of (<a>:&gt;</a>) is:
--   
--   <pre>
--   &gt;&gt;&gt; :t (:&gt;)
--   (:&gt;) :: a -&gt; Vec n a -&gt; Vec (n + 1) a
--   </pre>
--   
--   We thus need a <tt>fold</tt> function that can handle the growing
--   vector type: <a>dfold</a>. Compared to <a>foldr</a>, <a>dfold</a>
--   takes an extra parameter, called the <i>motive</i>, that allows the
--   folded function to have an argument and result type that
--   <i>depends</i> on the current length of the vector. Using
--   <a>dfold</a>, we can now correctly define <i>append'</i>:
--   
--   <pre>
--   import Data.Singletons
--   import Data.Proxy
--   
--   data Append (m :: Nat) (a :: Type) (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> (Append m a) l = <a>Vec</a> (l + m) a
--   
--   append' xs ys = <a>dfold</a> (Proxy :: Proxy (Append m a)) (const (<a>:&gt;</a>)) ys xs
--   </pre>
--   
--   We now see that <i>append'</i> has the appropriate type:
--   
--   <pre>
--   &gt;&gt;&gt; :t append'
--   append' :: KnownNat k =&gt; Vec k a -&gt; Vec m a -&gt; Vec (k + m) a
--   </pre>
--   
--   And that it works:
--   
--   <pre>
--   &gt;&gt;&gt; append' (1 :&gt; 2 :&gt; Nil) (3 :&gt; 4 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: "<tt><a>dfold</a> m f z xs</tt>" creates a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Look at <a>dtfold</a> for a <i>dependently</i> typed fold
--   that produces a structure with a depth of O(log_2(<tt><a>length</a>
--   xs</tt>)).
dfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (forall l. SNat l -> a -> (p @@ l) -> p @@ (l + 1)) -> (p @@ 0) -> Vec k a -> p @@ k

-- | A combination of <a>dfold</a> and <a>fold</a>: a <i>dependently</i>
--   typed fold that reduces a vector in a tree-like structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XUndecidableInstances
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data IIndex (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply IIndex l = Index ((2^l)+1)
--   
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat k, KnownNat (2^k)) =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--       populationCount' bv = dtfold (Proxy @IIndex)
--                                    fromIntegral
--                                    (\_ x y -&gt; add x y)
--                                    (bv2v bv)
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <a>BitVector</a>. Given a vector of <i>n</i> bits, we
--   only need we need a data type that can represent the number <i>n</i>:
--   <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a range of
--   <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits), hence we need
--   <a>Index</a> <tt>n+1</tt>. As an initial attempt we will use
--   <a>sum</a>, because it gives a nice (<tt>log2(n)</tt>) tree-structure
--   of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (n+1), KnownNat (n+2))
--                   =&gt; <a>BitVector</a> (n+1) -&gt; <a>Index</a> (n+2)
--   populationCount = sum . map fromIntegral . <a>bv2v</a>
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>add</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <a>fold</a> to create a tree-structure
--   of <a>add</a>es:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (n+1), KnownNat (n+2))
--                        =&gt; BitVector (n+1) -&gt; Index (n+2)
--       populationCount' = fold add . map fromIntegral . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘((n + 2) + (n + 2)) - 1’ with ‘n + 2’
--         Expected type: Index (n + 2) -&gt; Index (n + 2) -&gt; Index (n + 2)
--           Actual type: Index (n + 2)
--                        -&gt; Index (n + 2) -&gt; AResult (Index (n + 2)) (Index (n + 2))
--       • In the first argument of ‘fold’, namely ‘add’
--         In the first argument of ‘(.)’, namely ‘fold add’
--         In the expression: fold add . map fromIntegral . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (n + 1) -&gt; Index (n + 2)
--             (bound at ...)
--   </pre>
--   
--   because <a>fold</a> expects a function of type "<tt>a -&gt; a -&gt;
--   a</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>add</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons
--   import Data.Proxy
--   
--   data IIndex (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>dtfold</a> (Proxy @IIndex)
--                                fromIntegral
--                                (\_ x y -&gt; <a>add</a> x y)
--                                (<a>bv2v</a> bv)
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
--   
--   Some final remarks:
--   
--   <ul>
--   <li>By using <a>dtfold</a> instead of <a>fold</a>, we had to restrict
--   our <a>BitVector</a> argument to have bit-width that is a power of
--   2.</li>
--   <li>Even though our original <i>populationCount</i> function specified
--   a structure where all adders had the same width. Most
--   VHDL/(System)Verilog synthesis tools will create a more efficient
--   circuit, i.e. one where the adders have an increasing bit-width for
--   every layer, from the VHDL/(System)Verilog produced by the Clash
--   compiler.</li>
--   </ul>
--   
--   <b>NB</b>: The depth, or delay, of the structure produced by
--   "<tt><a>dtfold</a> m f g xs</tt>" is O(log_2(<tt><a>length</a>
--   xs</tt>)).
dtfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (a -> p @@ 0) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> p @@ (l + 1)) -> Vec (2 ^ k) a -> p @@ k

-- | Specialised version of <a>dfold</a> that builds a triangular
--   computational structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; let insert y xs = let (y',xs') = mapAccumL compareSwap y xs in xs' :&lt; y'
--   
--   &gt;&gt;&gt; let insertionSort = vfold (const insert)
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   <pre>
--   compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   insert y xs     = let (y',xs') = <a>mapAccumL</a> compareSwap y xs in xs' <a>:&lt;</a> y'
--   insertionSort   = <a>vfold</a> (const insert)
--   </pre>
--   
--   Builds a triangular structure of compare and swaps to sort a row.
--   
--   <pre>
--   &gt;&gt;&gt; insertionSort (7 :&gt; 3 :&gt; 9 :&gt; 1 :&gt; Nil)
--   1 :&gt; 3 :&gt; 7 :&gt; 9 :&gt; Nil
--   </pre>
--   
--   The circuit layout of <tt>insertionSort</tt>, build using
--   <a>vfold</a>, is:
--   
vfold :: forall k a b. KnownNat k => (forall l. SNat l -> a -> Vec l b -> Vec (l + 1) b) -> Vec k a -> Vec k b

-- | The largest element of a non-empty vector
maximum :: Ord a => Vec (n + 1) a -> a

-- | The least element of a non-empty vector
minimum :: Ord a => Vec (n + 1) a -> a

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a vector of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == z :&gt; (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   0 :&gt; 5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>scanl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>last (scanl f z xs) == foldl f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanl :: (b -> a -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>scanl</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanl1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   1 :&gt; -1 :&gt; -4 :&gt; -8 :&gt; Nil
--   </pre>
scanl1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a vector of
--   successive reduced values from the right:
--   
--   <pre>
--   scanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; z :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; 0 :&gt; Nil
--   </pre>
--   
--   "<a>scanr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>head (scanr f z xs) == foldr f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanr :: (a -> b -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>scanr</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanr1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   -2 :&gt; 3 :&gt; -1 :&gt; 4 :&gt; Nil
--   </pre>
scanr1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>postscanl</a> is a variant of <a>scanl</a> where the first result
--   is dropped:
--   
--   <pre>
--   postscanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>postscanl</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanl :: (b -> a -> b) -> b -> Vec n a -> Vec n b

-- | <a>postscanr</a> is a variant of <a>scanr</a> that where the last
--   result is dropped:
--   
--   <pre>
--   postscanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   "<a>postscanr</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanr :: (a -> b -> b) -> b -> Vec n a -> Vec n b

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumL (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,1 :&gt; 2 :&gt; 4 :&gt; 7 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumL</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumL :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumR (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,10 :&gt; 8 :&gt; 5 :&gt; 1 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumR</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumR :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | 1-dimensional stencil computations
--   
--   "<a>stencil1d</a> <tt>stX f xs</tt>", where <i>xs</i> has <i>stX +
--   n</i> elements, applies the stencil computation <i>f</i> on: <i>n +
--   1</i> overlapping (1D) windows of length <i>stX</i>, drawn from
--   <i>xs</i>. The resulting vector has <i>n + 1</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t stencil1d d2 sum xs
--   stencil1d d2 sum xs :: Num b =&gt; Vec 5 b
--   
--   &gt;&gt;&gt; stencil1d d2 sum xs
--   3 :&gt; 5 :&gt; 7 :&gt; 9 :&gt; 11 :&gt; Nil
--   </pre>
stencil1d :: KnownNat n => SNat (stX + 1) -> (Vec (stX + 1) a -> b) -> Vec ((stX + n) + 1) a -> Vec (n + 1) b

-- | 2-dimensional stencil computations
--   
--   "<a>stencil2d</a> <tt>stY stX f xss</tt>", where <i>xss</i> is a
--   matrix of <i>stY + m</i> rows of <i>stX + n</i> elements, applies the
--   stencil computation <i>f</i> on: <i>(m + 1) * (n + 1)</i> overlapping
--   (2D) windows of <i>stY</i> rows of <i>stX</i> elements, drawn from
--   <i>xss</i>. The result matrix has <i>m + 1</i> rows of <i>n + 1</i>
--   elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t stencil2d d2 d2 (sum . map sum) xss
--   stencil2d d2 d2 (sum . map sum) xss :: Num b =&gt; Vec 3 (Vec 3 b)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stencil2d d2 d2 (sum . map sum) xss
--   (14 :&gt; 18 :&gt; 22 :&gt; Nil) :&gt; (30 :&gt; 34 :&gt; 38 :&gt; Nil) :&gt; (46 :&gt; 50 :&gt; 54 :&gt; Nil) :&gt; Nil
--   </pre>
stencil2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> (Vec (stY + 1) (Vec (stX + 1) a) -> b) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) b)

-- | "<a>windows1d</a> <tt>stX xs</tt>", where the vector <i>xs</i> has
--   <i>stX + n</i> elements, returns a vector of <i>n + 1</i> overlapping
--   (1D) windows of <i>xs</i> of length <i>stX</i>.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t windows1d d2 xs
--   windows1d d2 xs :: Num a =&gt; Vec 5 (Vec 2 a)
--   
--   &gt;&gt;&gt; windows1d d2 xs
--   (1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
windows1d :: KnownNat n => SNat (stX + 1) -> Vec ((stX + n) + 1) a -> Vec (n + 1) (Vec (stX + 1) a)

-- | "<a>windows2d</a> <tt>stY stX xss</tt>", where matrix <i>xss</i> has
--   <i>stY + m</i> rows of <i>stX + n</i>, returns a matrix of <i>m+1</i>
--   rows of <i>n+1</i> elements. The elements of this new matrix are the
--   overlapping (2D) windows of <i>xss</i>, where every window has
--   <i>stY</i> rows of <i>stX</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   
--   &gt;&gt;&gt; :t windows2d d2 d2 xss
--   windows2d d2 d2 xss :: Num a =&gt; Vec 3 (Vec 3 (Vec 2 (Vec 2 a)))
--   
--   &gt;&gt;&gt; windows2d d2 d2 xss
--   (((1 :&gt; 2 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil) :&gt; ((2 :&gt; 3 :&gt; Nil) :&gt; (6 :&gt; 7 :&gt; Nil) :&gt; Nil) :&gt; ((3 :&gt; 4 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((5 :&gt; 6 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; Nil) :&gt; Nil) :&gt; ((6 :&gt; 7 :&gt; Nil) :&gt; (10 :&gt; 11 :&gt; Nil) :&gt; Nil) :&gt; ((7 :&gt; 8 :&gt; Nil) :&gt; (11 :&gt; 12 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((9 :&gt; 10 :&gt; Nil) :&gt; (13 :&gt; 14 :&gt; Nil) :&gt; Nil) :&gt; ((10 :&gt; 11 :&gt; Nil) :&gt; (14 :&gt; 15 :&gt; Nil) :&gt; Nil) :&gt; ((11 :&gt; 12 :&gt; Nil) :&gt; (15 :&gt; 16 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; Nil
--   </pre>
windows2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) (Vec (stY + 1) (Vec (stX + 1) a)))

-- | Convert a vector to a list.
--   
--   <pre>
--   &gt;&gt;&gt; toList (1:&gt;2:&gt;3:&gt;Nil)
--   [1,2,3]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
toList :: Vec n a -> [a]

-- | Convert a list to a vector. This function returns Nothing if the size
--   of the list is not equal to the size of the resulting vector.
--   
--   <pre>
--   &gt;&gt;&gt; Vec.fromList [1,2,3,4,5] :: Maybe (Vec 5 Int)
--   Just (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Vec.fromList [1,2,3,4,5] :: Maybe (Vec 3 Int)
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Vec.fromList [1,2,3,4,5] :: Maybe (Vec 10 Int)
--   Nothing
--   </pre>
--   
--   <ul>
--   <li><b>NB</b>: Use <a>listToVecTH</a> if you want to make a
--   <i>statically known</i> vector</li>
--   <li><b>NB</b>: This function is not synthesizable</li>
--   </ul>
fromList :: forall n a. KnownNat n => [a] -> Maybe (Vec n a)

-- | Convert a list to a vector. This function always returns a vector of
--   the desired length, by either truncating the list or padding the
--   vector with undefined elements.
--   
--   <pre>
--   &gt;&gt;&gt; Vec.unsafeFromList [1,2,3,4,5] :: Vec 5 Int
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Vec.unsafeFromList [1,2,3,4,5] :: Vec 3 Int
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Vec.unsafeFromList [1,2,3,4,5] :: Vec 10 Int
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; *** Exception: Clash.Sized.Vector.unsafeFromList: vector larger than list
--   ...
--   </pre>
--   
--   <ul>
--   <li><b>NB</b>: Use <a>listToVecTH</a> if you want to make a
--   <i>statically known</i> vector</li>
--   <li><b>NB</b>: This function is not synthesizable</li>
--   </ul>
unsafeFromList :: forall n a. KnownNat n => [a] -> Vec n a

-- | Convert a <a>BitVector</a> to a <a>Vec</a> of <a>Bit</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 6 :: BitVector 8
--   
--   &gt;&gt;&gt; x
--   0b0000_0110
--   
--   &gt;&gt;&gt; bv2v x
--   0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 1 :&gt; 0 :&gt; Nil
--   </pre>
bv2v :: KnownNat n => BitVector n -> Vec n Bit

-- | Convert a <a>Vec</a> of <a>Bit</a>s to a <a>BitVector</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let x = (0:&gt;0:&gt;0:&gt;1:&gt;0:&gt;0:&gt;1:&gt;0:&gt;Nil) :: Vec 8 Bit
--   
--   &gt;&gt;&gt; x
--   0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; Nil
--   
--   &gt;&gt;&gt; v2bv x
--   0b0001_0010
--   </pre>
v2bv :: KnownNat n => Vec n Bit -> BitVector n

-- | What you should use when your vector functions are too strict in their
--   arguments.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwapL a b = if a &lt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; :{
--   let sortVL :: (Ord a, KnownNat (n + 1)) =&gt; Vec ((n + 1) + 1) a -&gt; Vec ((n + 1) + 1) a
--       sortVL xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith compareSwapL (lazyV lefts) rights
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let sortV_flip xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith (flip compareSwapL) rights lefts
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   For example:
--   
--   <pre>
--   -- Bubble sort for 1 iteration
--   sortV xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL lefts rights
--   
--   -- Compare and swap
--   compareSwapL a b = if a &lt; b then (a,b)
--                               else (b,a)
--   </pre>
--   
--   Will not terminate because <a>zipWith</a> is too strict in its second
--   argument.
--   
--   In this case, adding <a>lazyV</a> on <a>zipWith</a>s second argument:
--   
--   <pre>
--   sortVL xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; map snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL (<a>lazyV</a> lefts) rights
--   </pre>
--   
--   Results in a successful computation:
--   
--   <pre>
--   &gt;&gt;&gt; sortVL (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: There is also a solution using <a>flip</a>, but it slightly
--   obfuscates the meaning of the code:
--   
--   <pre>
--   sortV_flip xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> (<a>flip</a> compareSwapL) rights lefts
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sortV_flip (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
lazyV :: KnownNat n => Vec n a -> Vec n a

-- | To be used as the motive <i>p</i> for <a>dfold</a>, when the <i>f</i>
--   in "<a>dfold</a> <tt>p f</tt>" is a variation on (<a>:&gt;</a>), e.g.:
--   
--   <pre>
--   map' :: forall n a b . KnownNat n =&gt; (a -&gt; b) -&gt; Vec n a -&gt; Vec n b
--   map' f = <a>dfold</a> (Proxy @(<a>VCons</a> b)) (_ x xs -&gt; f x :&gt; xs)
--   </pre>
data VCons (a :: Type) (f :: TyFun Nat Type) :: Type

-- | <a>Vec</a>tor as a <a>Proxy</a> for <a>Nat</a>
asNatProxy :: Vec n a -> Proxy n

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument
seqV :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqV`

-- | Evaluate all elements of a vector to WHNF
forceV :: KnownNat n => Vec n a -> Vec n a

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument. Does not propagate <a>XException</a>s.
seqVX :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqVX`

-- | Evaluate all elements of a vector to WHNF. Does not propagate
--   <a>XException</a>s.
forceVX :: KnownNat n => Vec n a -> Vec n a
traverse# :: forall a f b n. Applicative f => (a -> f b) -> Vec n a -> f (Vec n b)
concatBitVector# :: forall n m. (KnownNat n, KnownNat m) => Vec n (BitVector m) -> BitVector (n * m)
unconcatBitVector# :: forall n m. (KnownNat n, KnownNat m) => BitVector (n * m) -> Vec n (BitVector m)
instance GHC.TypeNats.KnownNat n => GHC.Generics.Generic (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, Data.Typeable.Internal.Typeable a, Data.Data.Data a) => Data.Data.Data (Clash.Sized.Vector.Vec n a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Sized.Vector.Vec n a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Sized.Vector.Vec n a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, GHC.Classes.Eq a) => GHC.Classes.Eq (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, GHC.Classes.Ord a) => GHC.Classes.Ord (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, GHC.Base.Semigroup a) => GHC.Base.Semigroup (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, GHC.Base.Monoid a) => GHC.Base.Monoid (Clash.Sized.Vector.Vec n a)
instance GHC.TypeNats.KnownNat n => GHC.Base.Applicative (Clash.Sized.Vector.Vec n)
instance GHC.TypeNats.KnownNat n => Data.Foldable.Foldable (Clash.Sized.Vector.Vec n)
instance GHC.Base.Functor (Clash.Sized.Vector.Vec n)
instance GHC.TypeNats.KnownNat n => Data.Traversable.Traversable (Clash.Sized.Vector.Vec n)
instance (Data.Default.Class.Default a, GHC.TypeNats.KnownNat n) => Data.Default.Class.Default (Clash.Sized.Vector.Vec n a)
instance (Clash.XException.NFDataX a, GHC.TypeNats.KnownNat n) => Clash.XException.NFDataX (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, Clash.Class.BitPack.Internal.BitPack a) => Clash.Class.BitPack.Internal.BitPack (Clash.Sized.Vector.Vec n a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, Test.QuickCheck.Arbitrary.Arbitrary a) => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Vector.Vec n a)
instance Test.QuickCheck.Arbitrary.CoArbitrary a => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Vector.Vec n a)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Vector.Vec n a)


-- | Tooling to safely work around <tt>incomplete-uni-patterns</tt> and
--   <tt>incomplete-patterns</tt> warnings. See <a>vecToTuple</a> for more
--   information and examples.
--   
--   Note: This module has been added to make upgrading to GHC 9.2 easier.
--   As of GHC 9.2, the <tt>incomplete-uni-patterns</tt> has been added to
--   the <tt>-Wall</tt>, making previously warning-free code now produce
--   warnings.
module Clash.Sized.Vector.ToTuple
class VecToTuple a where {
    type family TupType a = r | r -> a;
}

-- | Given a vector with three elements:
--   
--   <pre>
--   &gt;&gt;&gt; myVec = (1 :&gt; 2 :&gt; 3 :&gt; Nil) :: Vec 3 Int
--   </pre>
--   
--   The following would produce a warning even though we can be sure no
--   other pattern can ever apply:
--   
--   <pre>
--   &gt;&gt;&gt; (a :&gt; b :&gt; c :&gt; Nil) = myVec
--   </pre>
--   
--   <a>vecToTuple</a> can be used to work around the warning:
--   
--   <pre>
--   &gt;&gt;&gt; (a, b, c) = vecToTuple myVec
--   </pre>
--   
--   Of course, you will still get an error if you try to match a vector of
--   the wrong length:
--   
--   <pre>
--   &gt;&gt;&gt; (a, b, c, d) = vecToTuple myVec
--   ...
--       • Couldn't match type: (Int, Int, Int)
--                               ^
--                        with: (a, b, c, d)
--   ...
--   </pre>
vecToTuple :: VecToTuple a => a -> TupType a
instance Clash.Sized.Vector.ToTuple.VecToTuple (Clash.Sized.Vector.Vec 3 a)
instance Clash.Sized.Vector.ToTuple.VecToTuple (Clash.Sized.Vector.Vec 0 a)
instance Clash.Sized.Vector.ToTuple.VecToTuple (Clash.Sized.Vector.Vec 2 a)


-- | I/O actions that are translatable to HDL
module Clash.Explicit.SimIO

-- | Simulation-level I/O environment that can be synthesized to HDL-level
--   I/O. Note that it is unlikely that the HDL-level I/O can subsequently
--   be synthesized to a circuit.
--   
--   <h1>Example</h1>
--   
--   <pre>
--   tbMachine :: (File,File) -&gt; Int -&gt; SimIO Int
--   tbMachine (fileIn,fileOut) regOut = do
--     eofFileOut &lt;- <a>isEOF</a> fileOut
--     eofFileIn  &lt;- <a>isEOF</a> fileIn
--     when (eofFileIn || eofFileOut) $ do
--       <a>display</a> "success"
--       <a>finish</a> 0
--   
--     goldenIn  &lt;- <a>getChar</a> fileIn
--     goldenOut &lt;- <a>getChar</a> fileOut
--     res &lt;- if regOut == fromEnum goldenOut then do
--              return (fromEnum goldenIn)
--            else do
--              <a>display</a> "Output doesn't match golden output"
--              <a>finish</a> 1
--     display ("Output matches golden output")
--     return res
--   
--   tbInit :: (File,File)
--   tbInit = do
--     fileIn  &lt;- <a>openFile</a> "./goldenInput00.txt" "r"
--     fileOut &lt;- <a>openFile</a> "./goldenOutput00.txt" "r"
--     return (fileIn,fileOut)
--   
--   topEntity :: Signal System Int
--   topEntity = regOut
--     where
--       clk = systemClockGen
--       rst = resetGen
--       ena = enableGen
--   
--       regOut = register clk rst ena (fromEnum 'a') regIn
--       regIn  = <a>mealyIO</a> clk tbMachine tbInit regOut
--   </pre>
mealyIO :: KnownDomain dom => Clock dom -> (s -> i -> SimIO o) -> SimIO s -> Signal dom i -> Signal dom o

-- | Simulation-level I/O environment; synthesizable to HDL I/O, which in
--   itself is unlikely to be synthesisable to a digital circuit.
--   
--   See <a>mealyIO</a> as to its use.
data SimIO a

-- | Display a string on <i>stdout</i>
display :: String -> SimIO ()

-- | Finish the simulation with an exit code
finish :: Integer -> SimIO a

-- | Mutable reference
data Reg a

-- | Create a new mutable reference with the given starting value
reg :: a -> SimIO (Reg a)

-- | Read value from a mutable reference
readReg :: Reg a -> SimIO a

-- | Write new value to the mutable reference
writeReg :: Reg a -> a -> SimIO ()

-- | File handle
data File

-- | Open a file
openFile :: FilePath -> String -> SimIO File

-- | Close a file
closeFile :: File -> SimIO ()

-- | Read one character from a file
getChar :: File -> SimIO Char

-- | Insert a character into a buffer specified by the file
putChar :: Char -> File -> SimIO ()

-- | Read one line from a file
getLine :: forall n. KnownNat n => File -> Reg (Vec n (Unsigned 8)) -> SimIO Int

-- | Determine whether we've reached the end of the file
isEOF :: File -> SimIO Bool

-- | Write any buffered output to file
flush :: File -> SimIO ()

-- | Set the position of the next operation on the file
seek :: File -> Integer -> Int -> SimIO Int

-- | Set the position of the next operation to the beginning of the file
rewind :: File -> SimIO Int

-- | Returns the offset from the beginning of the file (in bytes).
tell :: File -> SimIO Integer
instance GHC.Base.Functor Clash.Explicit.SimIO.SimIO
instance GHC.Base.Applicative Clash.Explicit.SimIO.SimIO
instance GHC.Base.Monad Clash.Explicit.SimIO.SimIO


-- | ROMs
module Clash.Explicit.ROM

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFile</a> and
--   <a>romBlob</a> for different approaches that scale well.</li>
--   </ul>
rom :: (KnownDomain dom, KnownNat n, NFDataX a, Enum addr) => Clock dom -> Enable dom -> Vec n a -> Signal dom addr -> Signal dom a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFilePow2</a> and
--   <a>romBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
romPow2 :: (KnownDomain dom, KnownNat n, NFDataX a) => Clock dom -> Enable dom -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom a

-- | ROM primitive
rom# :: forall dom n a. (KnownDomain dom, KnownNat n, NFDataX a) => Clock dom -> Enable dom -> Vec n a -> Signal dom Int -> Signal dom a


-- | Internals for <a>Clash.Class.HasDomain</a>
module Clash.Class.HasDomain.HasSpecificDomain
type Outro = "" :$$$: "------" :$$$: "" :$$$: "You tried to apply an explicitly routed clock, reset, or enable line" :$$$: "to a construct with, possibly, an implicitly routed one. Clash failed to" :$$$: "unambigously link the given domain (by passing in a 'Clock', 'Reset', or" :$$$: "'Enable') to the component passed in." :$$$: ""
type NotFoundError (dom :: Domain) (t :: Type) = "Could not find domain '" :<<>>: 'ShowType dom :<<>>: "' in the following type:" :$$$: "" :$$$: "  " :<<>>: t :$$$: "" :$$$: "If that type contains that domain anyway, you might need to provide an" :$$$: "additional type instance of HasDomain. Example implementations:" :$$$: "" :$$$: " * type instance HasDomain dom  (MyVector n a)     = HasDomain dom a" :$$$: " * type instance HasDomain dom1 (MyCircuit dom2 a) = DomEq dom1 dom2" :$$$: " * type instance HasDomain dom1 (MyTuple a b)      = Merge dom a b" :$$$: "" :$$$: Outro

-- | Type that forces <i>dom</i> to be present in <i>r</i> at least once.
--   Will resolve to a type error if it doesn't. It will always fail if
--   given <i>dom</i> is completely polymorphic and can't be tied to
--   <i>r</i> in any way.
type WithSpecificDomain dom r = (HasSpecificDomain dom r, dom ~ GetDomain dom r)
data HasDomainWrapperResult

-- | No domain found
NotFound :: HasDomainWrapperResult

-- | Found the specific domain caller was looking for
Found :: HasDomainWrapperResult

-- | Merge two <a>HasDomainWrapperResult</a>s according to the semantics of
--   'HasDomain.
type family MergeWorker (n :: HasDomainWrapperResult) (m :: HasDomainWrapperResult) :: HasDomainWrapperResult
type Merge (dom :: Domain) (n :: Type) (m :: Type) = MergeWorker (HasDomainWrapper dom n) (HasDomainWrapper dom m)
type family DomEqWorker (n :: Domain) (m :: Domain) :: HasDomainWrapperResult

-- | Check domain for equality. Return <tt>'Found</tt> if so, return
--   <tt>'NotFound</tt> if not. The reason d'etre for this type family is
--   that _open_ type families don't allow overlapping types. We therefore
--   defer equality checking to a closed type family.
type DomEq (n :: Domain) (m :: Domain) = IfStuck (DomEqWorker n m) ('NotFound) (Pure (DomEqWorker n m))

-- | Type family that searches a type and checks whether a specific domain
--   is present. Will result in either "domain not found, and no others
--   either", "domain not found, but found another", or "found domain".
type family HasDomain (dom :: Domain) (n :: Type) :: HasDomainWrapperResult
type family ErrOnNotFound (dom :: Domain) (n :: HasDomainWrapperResult) (t :: Type) :: Domain

-- | Wrapper that checks for stuckness and returns <tt>'NotFound</tt> if so
type family HasDomainWrapper (dom :: Domain) (n :: Type) :: HasDomainWrapperResult

-- | Helper function for HasSpecificDomain class (I don't really understand
--   why this one is necessary. HasDomainWrapper _should_ check for
--   stuckness and does so according to tests..
type family ResolveOrErr (dom :: Domain) (t :: Type) :: Domain

-- | Type class that specifies that a certain domain, <i>dom</i>, needs to
--   be present in some other type, <i>r</i>. This is used to disambiguate
--   what hidden clock, reset, and enable lines should be exposed in
--   functions such as <a>withSpecificReset</a>.
--   
--   Functions in need of this class should use <a>WithSpecificDomain</a>
--   though, to force Clash to display an error instead of letting it
--   silently pass.
class HasSpecificDomain (dom :: Domain) (r :: Type) where {
    type family GetDomain dom r :: Domain;
    type GetDomain dom r = ResolveOrErr dom r;
}
instance Clash.Class.HasDomain.HasSpecificDomain.HasSpecificDomain dom a


-- | API for synthesis attributes (sometimes referred to as "synthesis
--   directives", "pragmas", or "logic synthesis directives"). This is an
--   experimental feature, please report any unexpected or broken behavior
--   to Clash's GitHub page
--   (<a>https://github.com/clash-lang/clash-compiler/issues</a>).
module Clash.Annotations.SynthesisAttributes

-- | Synthesis attributes are directives passed to synthesis tools, such as
--   Quartus. An example of such an attribute in VHDL:
--   
--   <pre>
--   attribute chip_pin : string;
--   attribute chip_pin of sel : signal is "C4";
--   attribute chip_pin of data : signal is "D1, D2, D3, D4";
--   </pre>
--   
--   This would instruct the synthesis tool to map the wire <i>sel</i> to
--   pin <i>C4</i>, and wire <i>data</i> to pins <i>D1</i>, <i>D2</i>,
--   <i>D3</i>, and <i>D4</i>. To achieve this in Clash, <i>Attr</i>s are
--   used. An example of the same annotation:
--   
--   <pre>
--   import Clash.Annotations.SynthesisAttributes (Attr (..), Annotate )
--   
--   myFunc
--       :: (Signal System Bool `Annotate` 'StringAttr "chip_pin" "C4")
--       -&gt; (Signal System Int4 `Annotate` 'StringAttr "chip_pin" "D1, D2, D3, D4")
--       -&gt; ...
--   myFunc sel data = ...
--   {-# NOINLINE myFunc #-}
--   </pre>
--   
--   To ensure this function will be rendered as its own module, do not
--   forget a NOINLINE pragma.
--   
--   Multiple attributes for the <i>same</i> argument can be specified by
--   using a list. For example:
--   
--   <pre>
--   Signal System Bool `Annotate`
--     [ 'StringAttr "chip_pin" "C4"
--     , 'BoolAttr "direct_enable" 'True
--     , 'IntegerAttr "max_depth" 512
--     , 'Attr "keep"
--     ]
--   </pre>
--   
--   For Verilog see:
--   <a>https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir.htm</a>
--   
--   For VHDL, see:
--   <a>https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vhdl/vhdl_file_dir.htm</a>
--   
--   <h1>Warnings</h1>
--   
--   When using annotations, it is important that annotated arguments are
--   not eta-reduced, as this may result in the annotation being stripped
--   by GHC. For example
--   
--   <pre>
--   f :: Signal System Bool `Annotate` 'StringAttr "chip_pin" "C4"
--     -&gt; Signal System Bool
--   f x = id x -- Using a lambda, i.e. f = \x -&gt; id x also works
--   </pre>
--   
--   will reliably show the annotation in the generated HDL, but
--   
--   <pre>
--   g :: Signal System Bool `Annotate` 'StringAttr "chip_pin" "C4"
--     -&gt; Signal System Bool
--   g = id
--   </pre>
--   
--   will not work.
--   
--   This is an experimental feature, please report any unexpected or
--   broken behavior to Clash's GitHub page
--   (<a>https://github.com/clash-lang/clash-compiler/issues</a>).
--   
--   Use <a>annotate</a> if you wish to annotate an intermediate signal.
--   Its use is preferred over type level annotations.
data Attr a

-- | Attribute which argument is rendered as a bool. Example:
--   <a>https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_direct_enable.htm</a>
BoolAttr :: a -> Bool -> Attr a

-- | Attribute which argument is rendered as a integer. Example:
--   <a>https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_max_depth.htm</a>
IntegerAttr :: a -> Integer -> Attr a

-- | Attribute which argument is rendered as a string. Example:
--   <a>https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_chip.htm</a>
StringAttr :: a -> a -> Attr a

-- | Attribute rendered as constant. Example:
--   <a>https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_keep.htm</a>
Attr :: a -> Attr a
type Annotate (a :: Type) (attrs :: k) = a

-- | Create a new identifier in HDL and inserts given synthesis attributes.
--   The name of the intermediate signal can be influenced using naming
--   functions in <a>Clash.Magic</a>.
annotate :: forall n dom a. Vec n (Attr String) -> Signal dom a -> Signal dom a

-- | Insert attributes such that signals are preserved in major synthesis
--   tools. Also inserts "mark_debug", a way of signalling Vivado a signal
--   should show up in a list of signals desired for ILA/VIO insertion.
--   
--   Attributes inserted: <tt>keep</tt>, <tt>mark_debug</tt>,
--   <tt>noprune</tt>, and <tt>preserve</tt>.
markDebug :: Signal dom a -> Signal dom a
instance GHC.Base.Functor Clash.Annotations.SynthesisAttributes.Attr
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Clash.Annotations.SynthesisAttributes.Attr a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Clash.Annotations.SynthesisAttributes.Attr a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Annotations.SynthesisAttributes.Attr a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Annotations.SynthesisAttributes.Attr a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Clash.Annotations.SynthesisAttributes.Attr a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Annotations.SynthesisAttributes.Attr a)
instance GHC.Generics.Generic (Clash.Annotations.SynthesisAttributes.Attr a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Annotations.SynthesisAttributes.Attr a)


module Clash.Sized.RTree

-- | Perfect depth binary tree.
--   
--   <ul>
--   <li>Only has elements at the leaf of the tree</li>
--   <li>A tree of depth <i>d</i> has <i>2^d</i> elements.</li>
--   </ul>
data RTree :: Nat -> Type -> Type
[RLeaf] :: a -> RTree 0 a
[RBranch] :: RTree d a -> RTree d a -> RTree (d + 1) a

-- | RLeaf of a perfect depth tree
--   
--   <pre>
--   &gt;&gt;&gt; LR 1
--   1
--   
--   &gt;&gt;&gt; let x = LR 1
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; RTree 0 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (LR a) (LR b) = a + b
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; RTree 0 a -&gt; RTree 0 a -&gt; a
--   
--   &gt;&gt;&gt; f (LR 1) (LR 2)
--   3
--   </pre>
pattern LR :: a -> RTree 0 a

-- | RBranch of a perfect depth tree
--   
--   <pre>
--   &gt;&gt;&gt; BR (LR 1) (LR 2)
--   &lt;1,2&gt;
--   
--   &gt;&gt;&gt; let x = BR (LR 1) (LR 2)
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; RTree 1 a
--   </pre>
--   
--   Case be used a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (BR (LR a) (LR b)) = LR (a + b)
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; RTree 1 a -&gt; RTree 0 a
--   
--   &gt;&gt;&gt; f (BR (LR 1) (LR 2))
--   3
--   </pre>
pattern BR :: RTree d a -> RTree d a -> RTree (d + 1) a

-- | "<a>treplicate</a> <tt>d a</tt>" returns a tree of depth <i>d</i>, and
--   has <i>2^d</i> copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; treplicate (SNat :: SNat 3) 6
--   &lt;&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;,&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;&gt;
--   
--   &gt;&gt;&gt; treplicate d3 6
--   &lt;&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;,&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;&gt;
--   </pre>
treplicate :: forall d a. SNat d -> a -> RTree d a

-- | "<a>trepeat</a> <tt>a</tt>" creates a tree with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; trepeat 6 :: RTree 2 Int
--   &lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;
--   </pre>
trepeat :: KnownNat d => a -> RTree d a

-- | Extract the first element of a tree
--   
--   The first element is defined to be the bottom-left leaf.
--   
--   <pre>
--   &gt;&gt;&gt; thead $ BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))
--   1
--   </pre>
thead :: RTree n a -> a

-- | Extract the last element of a tree
--   
--   The last element is defined to be the bottom-right leaf.
--   
--   <pre>
--   &gt;&gt;&gt; tlast $ BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))
--   4
--   </pre>
tlast :: RTree n a -> a

-- | "<a>indexTree</a> <tt>t n</tt>" returns the <i>n</i>'th element of
--   <i>t</i>.
--   
--   The bottom-left leaf had index <i>0</i>, and the bottom-right leaf has
--   index <i>2^d-1</i>, where <i>d</i> is the depth of the tree
--   
--   <pre>
--   &gt;&gt;&gt; indexTree (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))) 0
--   1
--   
--   &gt;&gt;&gt; indexTree (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))) 2
--   3
--   
--   &gt;&gt;&gt; indexTree (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))) 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 3
--   ...
--   </pre>
indexTree :: (KnownNat d, Enum i) => RTree d a -> i -> a

-- | Generate a tree of indices, where the depth of the tree is determined
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; tindices :: RTree 3 (Index 8)
--   &lt;&lt;&lt;0,1&gt;,&lt;2,3&gt;&gt;,&lt;&lt;4,5&gt;,&lt;6,7&gt;&gt;&gt;
--   </pre>
tindices :: forall d. KnownNat d => RTree d (Index (2 ^ d))

-- | "<a>replaceTree</a> <tt>n a t</tt>" returns the tree <i>t</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   The bottom-left leaf had index <i>0</i>, and the bottom-right leaf has
--   index <i>2^d-1</i>, where <i>d</i> is the depth of the tree
--   
--   <pre>
--   &gt;&gt;&gt; replaceTree 0 5 (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;5,2&gt;,&lt;3,4&gt;&gt;
--   
--   &gt;&gt;&gt; replaceTree 2 7 (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;1,2&gt;,&lt;7,4&gt;&gt;
--   
--   &gt;&gt;&gt; replaceTree 9 6 (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;1,2&gt;,&lt;3,*** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 3
--   ...
--   </pre>
replaceTree :: (KnownNat d, Enum i) => i -> a -> RTree d a -> RTree d a

-- | "<a>tmap</a> <tt>f t</tt>" is the tree obtained by apply <i>f</i> to
--   each element of <i>t</i>, i.e.,
--   
--   <pre>
--   tmap f (BR (LR a) (LR b)) == BR (LR (f a)) (LR (f b))
--   </pre>
tmap :: forall d a b. KnownNat d => (a -> b) -> RTree d a -> RTree d b

-- | <a>tzipWith</a> generalizes <a>tzip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "tzipWith (+)" applied to two trees produces the tree of
--   corresponding sums.
--   
--   <pre>
--   tzipWith f (BR (LR a1) (LR b1)) (BR (LR a2) (LR b2)) == BR (LR (f a1 a2)) (LR (f b1 b2))
--   </pre>
tzipWith :: forall a b c d. KnownNat d => (a -> b -> c) -> RTree d a -> RTree d b -> RTree d c

-- | <a>tzip</a> takes two trees and returns a tree of corresponding pairs.
tzip :: KnownNat d => RTree d a -> RTree d b -> RTree d (a, b)

-- | <a>tunzip</a> transforms a tree of pairs into a tree of first
--   components and a tree of second components.
tunzip :: forall d a b. KnownNat d => RTree d (a, b) -> (RTree d a, RTree d b)

-- | Reduce a tree to a single element
tfold :: forall d a b. KnownNat d => (a -> b) -> (b -> b -> b) -> RTree d a -> b

-- | A <i>dependently</i> typed fold over trees.
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <a>BitVector</a>. Given a vector of <i>n</i> bits, we
--   only need we need a data type that can represent the number <i>n</i>:
--   <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a range of
--   <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits), hence we need
--   <a>Index</a> <tt>n+1</tt>. As an initial attempt we will use
--   <a>tfold</a>, because it gives a nice (<tt>log2(n)</tt>)
--   tree-structure of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1))
--                   =&gt; BitVector (2^d) -&gt; Index (2^d+1)
--   populationCount = tfold (resize . bv2i . pack) (+) . v2t . bv2v
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (2^d+1) -&gt; <a>Index</a> (2^d+1) -&gt; <a>Index</a> (2^d+1).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>add</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <a>fold</a> to create a tree-structure
--   of <a>add</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1))
--                        =&gt; BitVector (2^d) -&gt; Index (2^d+1)
--       populationCount' = tfold (resize . bv2i . pack) add . v2t . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘(((2 ^ d) + 1) + ((2 ^ d) + 1)) - 1’
--                        with ‘(2 ^ d) + 1’
--         Expected type: Index ((2 ^ d) + 1)
--                        -&gt; Index ((2 ^ d) + 1) -&gt; Index ((2 ^ d) + 1)
--           Actual type: Index ((2 ^ d) + 1)
--                        -&gt; Index ((2 ^ d) + 1)
--                        -&gt; AResult (Index ((2 ^ d) + 1)) (Index ((2 ^ d) + 1))
--       • In the second argument of ‘tfold’, namely ‘add’
--         In the first argument of ‘(.)’, namely
--           ‘tfold (resize . bv2i . pack) add’
--         In the expression: tfold (resize . bv2i . pack) add . v2t . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (2 ^ d) -&gt; Index ((2 ^ d) + 1)
--             (bound at ...)
--   </pre>
--   
--   because <a>tfold</a> expects a function of type "<tt>b -&gt; b -&gt;
--   b</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>add</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons
--   
--   data IIndex (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>tdfold</a> (Proxy @IIndex)
--                                (resize . bv2i . pack)
--                                (\_ x y -&gt; <a>add</a> x y)
--                                (<a>v2t</a> (<a>bv2v</a> bv))
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
tdfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (a -> p @@ 0) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> p @@ (l + 1)) -> RTree k a -> p @@ k

-- | <a>tscanl</a> applied to <a>Vec</a>
--   
--   <pre>
--   &gt;&gt;&gt; scanlPar (+) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   1 :&gt; 3 :&gt; 6 :&gt; 10 :&gt; Nil
--   </pre>
scanlPar :: KnownNat n => (a -> a -> a) -> Vec (2 ^ n) a -> Vec (2 ^ n) a

-- | Low-depth left scan
--   
--   <a>tscanl</a> is similar to <a>foldl</a>, but returns a tree of
--   successive reduced values from the left:
--   
--   <pre>
--   tscanl f [x1, x2, x3, ...] == [x1, x1 `f` x2, x1 `f` x2 `f` x3, ...]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; tscanl (+) (v2t (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil))
--   &lt;&lt;1,3&gt;,&lt;6,10&gt;&gt;
--   </pre>
--   
tscanl :: forall a n. KnownNat n => (a -> a -> a) -> RTree n a -> RTree n a

-- | <a>tscanr</a> applied to <a>Vec</a>
--   
--   <pre>
--   &gt;&gt;&gt; scanrPar (+) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   10 :&gt; 9 :&gt; 7 :&gt; 4 :&gt; Nil
--   </pre>
scanrPar :: KnownNat n => (a -> a -> a) -> Vec (2 ^ n) a -> Vec (2 ^ n) a

-- | Low-depth right scan
--   
--   <a>tscanr</a> is similar to <a>foldr</a>, but returns a tree of
--   successive reduced values from the left:
--   
--   <pre>
--   tscanr f [..., xn2, xn1, xn] == [..., xn2 `f` xn1 `f` xn, xn1 `f` xn, xn]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; tscanr (+) (v2t (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil))
--   &lt;&lt;10,9&gt;,&lt;7,4&gt;&gt;
--   </pre>
tscanr :: forall a n. KnownNat n => (a -> a -> a) -> RTree n a -> RTree n a

-- | Convert a vector with <i>2^d</i> elements to a tree of depth <i>d</i>.
--   
--   <pre>
--   &gt;&gt;&gt; v2t (1 :&gt; 2 :&gt; 3 :&gt; 4:&gt; Nil)
--   &lt;&lt;1,2&gt;,&lt;3,4&gt;&gt;
--   </pre>
v2t :: forall d a. KnownNat d => Vec (2 ^ d) a -> RTree d a

-- | Convert a tree of depth <i>d</i> to a vector of <i>2^d</i> elements
--   
--   <pre>
--   &gt;&gt;&gt; (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;1,2&gt;,&lt;3,4&gt;&gt;
--   
--   &gt;&gt;&gt; t2v (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
t2v :: forall d a. KnownNat d => RTree d a -> Vec (2 ^ d) a

-- | Given a function <tt>f</tt> that is strict in its <i>n</i>th
--   <a>RTree</a> argument, make it lazy by applying <a>lazyT</a> to this
--   argument:
--   
--   <pre>
--   f x0 x1 .. (lazyT xn) .. xn_plus_k
--   </pre>
lazyT :: KnownNat d => RTree d a -> RTree d a
instance GHC.TypeNats.KnownNat d => Data.Traversable.Traversable (Clash.Sized.RTree.RTree d)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, GHC.Classes.Eq a) => GHC.Classes.Eq (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, GHC.Classes.Ord a) => GHC.Classes.Ord (Clash.Sized.RTree.RTree d a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Sized.RTree.RTree n a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Sized.RTree.RTree n a)
instance GHC.TypeNats.KnownNat d => GHC.Base.Functor (Clash.Sized.RTree.RTree d)
instance GHC.TypeNats.KnownNat d => GHC.Base.Applicative (Clash.Sized.RTree.RTree d)
instance GHC.TypeNats.KnownNat d => Data.Foldable.Foldable (Clash.Sized.RTree.RTree d)
instance (GHC.TypeNats.KnownNat d, Clash.Class.BitPack.Internal.BitPack a) => Clash.Class.BitPack.Internal.BitPack (Clash.Sized.RTree.RTree d a)
instance GHC.TypeNats.KnownNat d => Control.Lens.At.Ixed (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, Data.Default.Class.Default a) => Data.Default.Class.Default (Clash.Sized.RTree.RTree d a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, Test.QuickCheck.Arbitrary.Arbitrary a) => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, Test.QuickCheck.Arbitrary.CoArbitrary a) => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, Clash.XException.NFDataX a) => Clash.XException.NFDataX (Clash.Sized.RTree.RTree d a)


-- | The Product/Signal isomorphism
module Clash.Signal.Bundle

-- | Isomorphism between a <a>Signal</a> of a product type (e.g. a tuple)
--   and a product type of <a>Signal</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <a>Unbundled</a> clk D = <a>Signal</a> clk D
--     <a>bundle</a>   s = s
--     <a>unbundle</a> s = s
--   </pre>
--   
--   For custom product types you'll have to write the instance manually:
--   
--   <pre>
--   data Pair a b = MkPair { getA :: a, getB :: b }
--   
--   instance Bundle (Pair a b) where
--     type Unbundled dom (Pair a b) = Pair (Signal dom a) (Signal dom b)
--   
--     -- bundle :: Pair (Signal dom a) (Signal dom b) -&gt; Signal dom (Pair a b)
--     bundle   (MkPair as bs) = MkPair <a>&lt;$&gt;</a> as <a>&lt;*&gt;</a> bs
--   
--     -- unbundle :: Signal dom (Pair a b) -&gt; Pair (Signal dom a) (Signal dom b)
--     unbundle pairs = MkPair (getA <a>&lt;$&gt;</a> pairs) (getB <a>&lt;$&gt;</a> pairs)
--   </pre>
class Bundle a where {
    type family Unbundled (dom :: Domain) a = res | res -> dom a;
    type Unbundled dom a = Signal dom a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: (Bundle a, Signal dom a ~ Unbundled dom a) => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: Bundle a => Signal dom a -> Unbundled dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, Unbundled dom a ~ Signal dom a) => Signal dom a -> Unbundled dom a

-- | See <a>TaggedEmptyTuple</a>
data EmptyTuple
EmptyTuple :: EmptyTuple

-- | Helper type to emulate the "old" behavior of Bundle's unit instance.
--   I.e., the instance for <tt>Bundle ()</tt> used to be defined as:
--   
--   <pre>
--   class Bundle () where
--     bundle   :: () -&gt; Signal dom ()
--     unbundle :: Signal dom () -&gt; ()
--   </pre>
--   
--   In order to have sensible type inference, the <a>Bundle</a> class
--   specifies that the argument type of <a>bundle</a> should uniquely
--   identify the result type, and vice versa for <a>unbundle</a>. The type
--   signatures in the snippet above don't though, as <tt>()</tt> doesn't
--   uniquely map to a specific domain. In other words, <tt>domain</tt>
--   should occur in both the argument and result of both functions.
--   
--   <a>TaggedEmptyTuple</a> tackles this by carrying the domain in its
--   type. The <a>bundle</a> and <a>unbundle</a> instance now looks like:
--   
--   <pre>
--   class Bundle EmptyTuple where
--     bundle   :: TaggedEmptyTuple dom -&gt; Signal dom EmptyTuple
--     unbundle :: Signal dom EmptyTuple -&gt; TaggedEmptyTuple dom
--   </pre>
--   
--   <tt>dom</tt> is now mentioned both the argument and result for both
--   <a>bundle</a> and <a>unbundle</a>.
data TaggedEmptyTuple (dom :: Domain)
TaggedEmptyTuple :: TaggedEmptyTuple (dom :: Domain)
vecBundle# :: Vec n (Signal t a) -> Signal t (Vec n a)
instance Clash.Signal.Bundle.Bundle Clash.Signal.Bundle.EmptyTuple
instance Clash.Signal.Bundle.Bundle (a1, a2)
instance Clash.Signal.Bundle.Bundle (a1, a2, a3)
instance GHC.TypeNats.KnownNat n => Clash.Signal.Bundle.Bundle (Clash.Sized.Vector.Vec n a)
instance GHC.TypeNats.KnownNat d => Clash.Signal.Bundle.Bundle (Clash.Sized.RTree.RTree d a)
instance Clash.Signal.Bundle.Bundle ((GHC.Generics.:*:) f g a)
instance Clash.Signal.Bundle.Bundle ()
instance Clash.Signal.Bundle.Bundle GHC.Types.Bool
instance Clash.Signal.Bundle.Bundle GHC.Integer.Type.Integer
instance Clash.Signal.Bundle.Bundle GHC.Types.Int
instance Clash.Signal.Bundle.Bundle GHC.Types.Float
instance Clash.Signal.Bundle.Bundle GHC.Types.Double
instance Clash.Signal.Bundle.Bundle (GHC.Maybe.Maybe a)
instance Clash.Signal.Bundle.Bundle (Data.Either.Either a b)
instance Clash.Signal.Bundle.Bundle Clash.Sized.Internal.BitVector.Bit
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.Index.Index n)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.Unsigned.Unsigned n)


-- | <h1>Initializing a block RAM with a data file </h1>
--   
--   Block RAM primitives that can be initialized with a data file. The BNF
--   grammar for this data file is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned numbers <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   Such a file can be produced with <a>memFile</a>:
--   
--   <pre>
--   writeFile "memory.bin" (memFile Nothing [7 :: Unsigned 9 .. 13])
--   </pre>
--   
--   We can instantiate a block RAM using the contents of the file above
--   like so:
--   
--   <pre>
--   f :: KnownDomain dom
--     =&gt; Clock  dom
--     -&gt; Enable dom
--     -&gt; Signal dom (Unsigned 3)
--     -&gt; Signal dom (Unsigned 9)
--   f clk en rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>blockRamFile</a> clk en d7 "memory.bin" rd (signal Nothing)
--   </pre>
--   
--   In the example above, we basically treat the block RAM as a
--   synchronous ROM. We can see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f systemClockGen enableGen (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g :: KnownDomain dom
--     =&gt; Clock  dom
--     -&gt; Enable dom
--     -&gt; Signal dom (Unsigned 3)
--     -&gt; Signal dom (Unsigned 6,Signed 3)
--   g clk en rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>blockRamFile</a> clk en d7 "memory.bin" rd (signal Nothing)
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g systemClockGen enableGen (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Explicit.BlockRam.File

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamFile</a> clk en size file) rd wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
blockRamFile :: (KnownDomain dom, KnownNat m, Enum addr, NFDataX addr, HasCallStack) => Clock dom -> Enable dom -> SNat n -> FilePath -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en (blockRamFilePow2'
--   clk en file) rd wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Explicit.Fixed#creatingdatafiles</a> for more ideas
--   on how to create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall dom n m. (KnownDomain dom, KnownNat m, KnownNat n, HasCallStack) => Clock dom -> Enable dom -> FilePath -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Convert data to the <a>String</a> contents of a memory file.
--   
--   <ul>
--   <li><b>NB</b>: Not synthesizable</li>
--   <li>The following document the several ways to instantiate components
--   with
--   files:<ul><li><a>Clash.Prelude.BlockRam.File#usingramfiles</a></li><li><a>Clash.Prelude.ROM.File#usingromfiles</a></li><li><a>Clash.Explicit.BlockRam.File#usingramfiles</a></li><li><a>Clash.Explicit.ROM.File#usingromfiles</a></li></ul></li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
--   
--   <h1>Example</h1>
--   
--   The <tt>Maybe</tt> datatype has don't care bits, where the actual
--   value does not matter. But the bits need a defined value in the
--   memory. Either 0 or 1 can be used, and both are valid representations
--   of the data.
--   
--   <pre>
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8]
--   
--   &gt;&gt;&gt; mapM_ (putStrLn . show . pack) es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 0) es)
--   000000000
--   100000111
--   100001000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 1) es)
--   011111111
--   100000111
--   100001000
--   </pre>
memFile :: forall a f. (BitPack a, Foldable f, HasCallStack) => Maybe Bit -> f a -> String

-- | blockRamFile primitive
blockRamFile# :: forall m dom n. (KnownDomain dom, KnownNat m, HasCallStack) => Clock dom -> Enable dom -> SNat n -> FilePath -> Signal dom Int -> Signal dom Bool -> Signal dom Int -> Signal dom (BitVector m) -> Signal dom (BitVector m)

-- | <b>NB</b>: Not synthesizable
initMem :: KnownNat n => FilePath -> IO [BitVector n]


-- | Configurable model for true dual-port block RAM
module Clash.Explicit.BlockRam.Model

-- | Helper used in <a>getConflict</a>
data Conflict
Conflict :: !MaybeX Bool -> !MaybeX Bool -> !MaybeX Bool -> Conflict

-- | Read/Write conflict for output A
[cfRWA] :: Conflict -> !MaybeX Bool

-- | Read/Write conflict for output B
[cfRWB] :: Conflict -> !MaybeX Bool

-- | Write/Write conflict
[cfWW] :: Conflict -> !MaybeX Bool

-- | Determines whether there was a write-write or read-write conflict. A
--   conflict occurs when two ports tried to (potentially, in case of
--   undefined values) access the same address and one or both tried to
--   write to it. See documentation of <a>Conflict</a> for more
--   information.
getConflict :: (MaybeX Bool, MaybeX Bool, MaybeX Int) -> (MaybeX Bool, MaybeX Bool, MaybeX Int) -> Maybe Conflict

-- | Step through a cycle of a TDP block RAM where only one clock is
--   active. Like <a>accessRam</a>, it accounts for <a>XException</a> in
--   all values supplied by the user of the block RAM.
cycleOne :: forall nAddrs a writeEnable. (HasCallStack, NFDataX a) => SNat nAddrs -> TdpbramModelConfig writeEnable a -> a -> Seq a -> (MaybeX Bool, MaybeX Int, MaybeX writeEnable, a) -> (Seq a, a)

-- | Step through a cycle of a TDP block RAM where the clock edges of port
--   A and port B coincided. Like <a>accessRam</a>, it accounts for
--   <a>XException</a> in all values supplied by the user of the block RAM.
cycleBoth :: forall nAddrs a writeEnable. (NFDataX a, HasCallStack) => SNat nAddrs -> TdpbramModelConfig writeEnable a -> a -> a -> Seq a -> (MaybeX Bool, MaybeX Int, MaybeX writeEnable, a) -> (MaybeX Bool, MaybeX Int, MaybeX writeEnable, a) -> (Seq a, a, a)

-- | Access a RAM and account for undefined values in the address, write
--   enable, and data to write. Return read after write value.
accessRam :: forall nAddrs a writeEnable. (NFDataX a, HasCallStack) => SNat nAddrs -> (MaybeX writeEnable -> MaybeX Bool) -> (Int -> MaybeX writeEnable -> a -> Seq a -> Seq a) -> MaybeX Int -> MaybeX writeEnable -> a -> Seq a -> (a, Seq a)
data TdpbramModelConfig writeEnable a
TdpbramModelConfig :: (MaybeX writeEnable -> MaybeX Bool) -> (MaybeX Bool -> MaybeX writeEnable -> MaybeX writeEnable) -> (Int -> MaybeX writeEnable -> a -> Seq a -> Seq a) -> TdpbramModelConfig writeEnable a

-- | Determine whether a write enable is active
[tdpIsActiveWriteEnable] :: TdpbramModelConfig writeEnable a -> MaybeX writeEnable -> MaybeX Bool

-- | Merge global enable with write enable
[tdpMergeWriteEnable] :: TdpbramModelConfig writeEnable a -> MaybeX Bool -> MaybeX writeEnable -> MaybeX writeEnable

-- | Update memory with a defined address
[tdpUpdateRam] :: TdpbramModelConfig writeEnable a -> Int -> MaybeX writeEnable -> a -> Seq a -> Seq a

-- | Haskell model for a true dual-port block RAM which is polymorphic in
--   its write enables
tdpbramModel :: forall nAddrs domA domB a writeEnable. (HasCallStack, KnownNat nAddrs, KnownDomain domA, KnownDomain domB, NFDataX a) => TdpbramModelConfig writeEnable a -> Clock domA -> Signal domA Bool -> Signal domA (Index nAddrs) -> Signal domA writeEnable -> Signal domA a -> Clock domB -> Signal domB Bool -> Signal domB (Index nAddrs) -> Signal domB writeEnable -> Signal domB a -> (Signal domA a, Signal domB a)
instance GHC.Show.Show Clash.Explicit.BlockRam.Model.Conflict


-- | Internals for <a>Clash.Class.HasDomain</a>
module Clash.Class.HasDomain.HasSingleDomain
type MissingInstance = "This might happen if an instance for TryDomain is missing. Try to determine" :$$$: "which of the types miss an instance, and add them. Example implementations:" :$$$: "" :$$$: " * type instance TryDomain t (MyVector n a)    = TryDomain t a" :$$$: " * type instance TryDomain t (MyCircuit dom a) = Found dom" :$$$: " * type instance TryDomain t Terminal          = NotFound" :$$$: "" :$$$: "Alternatively, use one of the withSpecific* functions."
type Outro = "" :$$$: "------" :$$$: "" :$$$: "You tried to apply an explicitly routed clock, reset, or enable line" :$$$: "to a construct with, possibly, an implicitly routed one. Clash failed to" :$$$: "unambigously determine a single domain and could therefore not route it." :$$$: "You possibly used one of these sets of functions:" :$$$: "" :$$$: " * with{ClockResetEnable,Clock,Reset,Enable}" :$$$: " * expose{ClockResetEnable,Clock,Reset,Enable}" :$$$: "" :$$$: "These functions are suitable for components defined over a single domain" :$$$: "only. If you want to use multiple domains, use the following instead:" :$$$: "" :$$$: " * withSpecific{ClockResetEnable,Clock,Reset,Enable}" :$$$: " * exposeSpecific{ClockResetEnable,Clock,Reset,Enable}" :$$$: ""
type NotFoundError (t :: Type) = "Could not find a non-ambiguous domain in the following type:" :$$$: "" :$$$: "  " :<<>>: t :$$$: "" :$$$: MissingInstance :$$$: Outro
type AmbiguousError (t :: Type) (dom1 :: Domain) (dom2 :: Domain) = "Could not determine that the domain '" :<<>>: dom1 :<<>>: "'" :$$$: "was equal to the domain '" :<<>>: dom2 :<<>>: "' in the type:" :$$$: "" :$$$: "  " :<<>>: t :$$$: "" :$$$: "This is usually resolved by adding explicit type signatures." :$$$: Outro
type StuckErrorMsg (orig :: Type) (n :: Type) = "Could not determine whether the following type contained a non-ambiguous domain:" :$$$: "" :$$$: "  " :<<>>: n :$$$: "" :$$$: "In the full type:" :$$$: "" :$$$: "  " :<<>>: orig :$$$: "" :$$$: "Does it contain one?" :$$$: "" :$$$: "------" :$$$: "" :$$$: MissingInstance :$$$: Outro

-- | Type that forces <i>dom</i> to be the same in all subtypes of <i>r</i>
--   that might contain a domain. If given a polymorphic domain not tied to
--   <i>r</i>, GHC will be allowed to infer that that domain is equal to
--   the one in <i>r</i> on the condition that <i>r</i> contains just a
--   single domain.
type WithSingleDomain dom r = (HasSingleDomain r, dom ~ GetDomain r)
data TryDomainResult
NotFound :: TryDomainResult
Ambiguous :: Domain -> Domain -> TryDomainResult
Found :: Domain -> TryDomainResult

-- | Type family to resolve type conflicts (if any)
type family Merge' (n :: TryDomainResult) (m :: TryDomainResult) :: TryDomainResult

-- | Same as Merge', but will insert a type error if Merge' got stuck.
type family Merge (orig :: Type) (n :: Type) (m :: Type) :: TryDomainResult
type family ErrOnConflict (t :: Type) (n :: TryDomainResult) :: Domain
type family TryDomain (orig :: Type) (n :: Type) :: TryDomainResult

-- | Type family that searches a type and checks whether all subtypes that
--   can contain a domain (for example, Signal) contain the <i>same</i>
--   domain. Its associated type, GetDomain, will yield a type error if
--   that doesn't hold OR if it can't check it.
class HasSingleDomain (r :: Type) where {
    type family GetDomain r :: Domain;
    type GetDomain r = IfStuck (TryDomain r r) (DelayError (StuckErrorMsg r r)) (Pure (ErrOnConflict r (TryDomain r r)));
}
instance Clash.Class.HasDomain.HasSingleDomain.HasSingleDomain a

module Clash.Class.HasDomain

-- | Type that forces <i>dom</i> to be present in <i>r</i> at least once.
--   Will resolve to a type error if it doesn't. It will always fail if
--   given <i>dom</i> is completely polymorphic and can't be tied to
--   <i>r</i> in any way.
type WithSpecificDomain dom r = (HasSpecificDomain dom r, dom ~ GetDomain dom r)

-- | Type that forces <i>dom</i> to be the same in all subtypes of <i>r</i>
--   that might contain a domain. If given a polymorphic domain not tied to
--   <i>r</i>, GHC will be allowed to infer that that domain is equal to
--   the one in <i>r</i> on the condition that <i>r</i> contains just a
--   single domain.
type WithSingleDomain dom r = (HasSingleDomain r, dom ~ GetDomain r)

-- | Type family that searches a type and checks whether a specific domain
--   is present. Will result in either "domain not found, and no others
--   either", "domain not found, but found another", or "found domain".
type family HasDomain (dom :: Domain) (n :: Type) :: HasDomainWrapperResult
type family TryDomain (orig :: Type) (n :: Type) :: TryDomainResult
data TryDomainResult
NotFound :: TryDomainResult
Ambiguous :: Domain -> Domain -> TryDomainResult
Found :: Domain -> TryDomainResult

-- | Check domain for equality. Return <tt>'Found</tt> if so, return
--   <tt>'NotFound</tt> if not. The reason d'etre for this type family is
--   that _open_ type families don't allow overlapping types. We therefore
--   defer equality checking to a closed type family.
type DomEq (n :: Domain) (m :: Domain) = IfStuck (DomEqWorker n m) ('NotFound) (Pure (DomEqWorker n m))


-- | Wires are fundamentally bidirectional, and in traditional HDLs we can
--   exploit this aspect by explicitly marking the endpoint, or port, of
--   such a wire as <i>inout</i>, thereby making this port function as both
--   a source and a drain for the signals flowing over the wire.
--   
--   Clash has support for <tt>inout</tt> ports through the implementation
--   of <i>BiSignal</i>s. To cleanly map to functions (and thus support
--   software simulation using Haskell), a <i>BiSignal</i> comes in two
--   parts; the <b>in</b> part:
--   
--   <pre>
--   <a>BiSignalIn</a> (ds :: <a>BiSignalDefault</a>) (dom :: <a>Domain</a>) (n :: Nat)
--   </pre>
--   
--   and the <b>out</b> part:
--   
--   <pre>
--   <a>BiSignalOut</a> (ds :: <a>BiSignalDefault</a>) (dom :: <a>Domain</a>) (n :: Nat)
--   </pre>
--   
--   Where:
--   
--   <ul>
--   <li>The internal representation is a <a>BitVector</a></li>
--   <li><i>n</i> indicates the number of bits in the <a>BitVector</a></li>
--   <li><i>dom</i> is the <i>clock-</i> (and <i>reset-</i>) domain to
--   which the memory elements manipulating these BiSignals belong.</li>
--   <li>Lastly, <i>ds</i> indicates the default behavior for the BiSignal
--   if nothing is being written (pull-down, pull-up, or undefined).</li>
--   </ul>
--   
--   <a>BiSignalIn</a> is used by Clash to generate the <tt>inout</tt>
--   ports on a HDL level, while <a>BiSignalOut</a> is only used for
--   simulation purposes and generally discarded by the compiler.
--   
--   <h1>Example</h1>
--   
--   The following describes a system where two circuits, in alternating
--   fashion, read the current value from the <i>bus</i>, increment it, and
--   write it on the next cycle.
--   
--   <pre>
--   import Clash.Explicit.Prelude
--   import Clash.Signal.BiSignal
--   
--   -- | Alternatingly read / increment+write
--   counter
--     :: (Bool, Int)
--     -- ^ Internal flip + previous read
--     -&gt; Int
--     -- ^ Int from inout
--     -&gt; ((Bool, Int), Maybe Int)
--   counter (write, prevread) i = ((write', prevread'), output)
--     where
--       output    = if write then Just (succ prevread) else Nothing
--       prevread' = if write then prevread else i
--       write' = not write
--   
--   -- | Write on odd cyles
--   f :: Clock System
--     -&gt; Reset System
--     -&gt; Enable System
--     -&gt; BiSignalIn  'Floating System (BitSize Int)
--     -&gt; BiSignalOut 'Floating System (BitSize Int)
--   f clk rst en s = writeToBiSignal s (mealy clk rst en counter (False, 0) (readFromBiSignal s))
--   
--   -- | Write on even cyles
--   g :: Clock System
--     -&gt; Reset System
--     -&gt; Enable System
--     -&gt; BiSignalIn  'Floating System (BitSize Int)
--     -&gt; BiSignalOut 'Floating System (BitSize Int)
--   g clk rst en s = writeToBiSignal s (mealy clk rst en counter (True, 0) (readFromBiSignal s))
--   
--   
--   -- | Connect the /f/ and /g/ circuits to the same bus
--   topEntity
--     :: Clock System
--     -&gt; Reset System
--     -&gt; Enable System
--     -&gt; Signal System Int
--   topEntity clk rst en = readFromBiSignal bus'
--     where
--       bus  = mergeBiSignalOuts $ f clk rst en bus' :&gt; g clk rst en bus' :&gt; Nil
--       bus' = veryUnsafeToBiSignalIn bus
--   </pre>
module Clash.Signal.BiSignal

-- | The <i>in</i> part of an <b>inout</b> port. BiSignalIn has the <a>type
--   role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalIn
--   type role BiSignalIn nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalIn (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | The <i>out</i> part of an <b>inout</b> port
--   
--   Wraps (multiple) writing signals. The semantics are such that only one
--   of the signals may write at a single time step.
--   
--   BiSignalOut has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalOut
--   type role BiSignalOut nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalOut (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | Used to specify the <i>default</i> behavior of a "BiSignal" in Haskell
--   simulation, i.e. what value is read when no value is being written to
--   it.
data BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-up resistor
PullUp :: BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-down resistor
PullDown :: BiSignalDefault

-- | <b>inout</b> port behaves as if is <i>floating</i>. Reading a
--   <i>floating</i> "BiSignal" value in simulation will yield an errorX
--   (undefined value).
Floating :: BiSignalDefault

-- | Singleton versions of <a>BiSignalDefault</a>
data SBiSignalDefault :: BiSignalDefault -> Type
[SPullUp] :: SBiSignalDefault 'PullUp
[SPullDown] :: SBiSignalDefault 'PullDown
[SFloating] :: SBiSignalDefault 'Floating

-- | Type class for <a>BiSignalDefault</a>: can be used as a constraint and
--   for obtaining the pull-up mode
class HasBiSignalDefault (ds :: BiSignalDefault)
pullUpMode :: HasBiSignalDefault ds => BiSignalIn ds dom n -> SBiSignalDefault ds

-- | Combine several <b>inout</b> signals into one.
mergeBiSignalOuts :: (HasCallStack, KnownNat n) => Vec n (BiSignalOut defaultState dom m) -> BiSignalOut defaultState dom m

-- | Read the value from an <b>inout</b> port
readFromBiSignal :: (HasCallStack, BitPack a) => BiSignalIn ds d (BitSize a) -> Signal d a

-- | Write to an <b>inout</b> port
writeToBiSignal :: (HasCallStack, BitPack a, NFDataX a) => BiSignalIn ds d (BitSize a) -> Signal d (Maybe a) -> BiSignalOut ds d (BitSize a)

-- | Converts the <tt>out</tt> part of a BiSignal to an <tt>in</tt> part.
--   In simulation it checks whether multiple components are writing and
--   will error accordingly. Make sure this is only called ONCE for every
--   BiSignal.
veryUnsafeToBiSignalIn :: (HasCallStack, KnownNat n, Given (SBiSignalDefault ds)) => BiSignalOut ds d n -> BiSignalIn ds d n
instance GHC.Show.Show Clash.Signal.BiSignal.BiSignalDefault
instance GHC.Base.Semigroup (Clash.Signal.BiSignal.BiSignalOut defaultState dom n)
instance GHC.Base.Monoid (Clash.Signal.BiSignal.BiSignalOut defaultState dom n)
instance Clash.Signal.BiSignal.HasBiSignalDefault 'Clash.Signal.BiSignal.PullUp
instance Clash.Signal.BiSignal.HasBiSignalDefault 'Clash.Signal.BiSignal.PullDown
instance Clash.Signal.BiSignal.HasBiSignalDefault 'Clash.Signal.BiSignal.Floating
instance Data.Reflection.Given (Clash.Signal.BiSignal.SBiSignalDefault 'Clash.Signal.BiSignal.PullUp)
instance Data.Reflection.Given (Clash.Signal.BiSignal.SBiSignalDefault 'Clash.Signal.BiSignal.PullDown)
instance Data.Reflection.Given (Clash.Signal.BiSignal.SBiSignalDefault 'Clash.Signal.BiSignal.Floating)


-- | Clash has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (dom :: <a>Symbol</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>dom</i> is the <i>clock-</i>
--   (and <i>reset-</i>) domain to which the memory elements manipulating
--   these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>dom</i>, is of the kind <a>Domain</a> - a
--   simple string. That string refers to a single <i>synthesis domain</i>.
--   A synthesis domain describes the behavior of certain aspects of memory
--   elements in it. More specifically, a domain looks like:
--   
--   <pre>
--   <a>DomainConfiguration</a>
--     { _name:: <a>Symbol</a>
--     -- ^ Domain name
--     , _period :: <a>Nat</a>
--     -- ^ Clock period in /ps/
--     , _edge :: <a>ActiveEdge</a>
--     -- ^ Active edge of the clock
--     , _reset :: <a>ResetKind</a>
--     -- ^ Whether resets are synchronous (edge-sensitive) or asynchronous (level-sensitive)
--     , _init :: <a>InitBehavior</a>
--     -- ^ Whether the initial (or "power up") value of memory elements is
--     -- unknown/undefined, or configurable to a specific value
--     , _polarity :: <a>ResetPolarity</a>
--     -- ^ Whether resets are active high or active low
--     }
--   </pre>
--   
--   Check the documentation of each of the types to see the various
--   options Clash provides. In order to specify a domain, an instance of
--   <a>KnownDomain</a> should be made. Clash provides a standard
--   implementation, called <a>System</a>, that is configured as follows:
--   
--   <pre>
--   instance KnownDomain <a>System</a> where
--     type KnownConf <a>System</a> = 'DomainConfiguration <a>System</a> 10000 'Rising 'Asynchronous 'Defined 'ActiveHigh
--     knownDomain = <a>SDomainConfiguration</a> SSymbol SNat <a>SRising</a> <a>SAsynchronous</a> <a>SDefined</a> <a>SActiveHigh</a>
--   </pre>
--   
--   In words, "System" is a synthesis domain with a clock running with a
--   period of 10000 <i>ps</i> (100 MHz). Memory elements update their
--   state on the rising edge of the clock, can be reset asynchronously
--   with regards to the clock, and have defined power up values if
--   applicable.
--   
--   In order to create a new domain, you don't have to instantiate it
--   explicitly. Instead, you can have <a>createDomain</a> create a domain
--   for you. You can also use the same function to subclass existing
--   domains.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   <li><b>NB</b>: For the best compatibility make sure your period is
--   divisible by 2, because some VHDL simulators don't support fractions
--   of picoseconds.</li>
--   <li><b>NB</b>: Whether <a>System</a> has good defaults depends on your
--   target platform. Check out <a>IntelSystem</a> and <a>XilinxSystem</a>
--   too!</li>
--   </ul>
--   
--   <h3>Explicit clocks and resets, and meta-stability </h3>
--   
--   When using multiple clocks and/or reset lines there are ways to
--   accidentally introduce situations that are prone to
--   <a>metastability</a>. These bugs are incredibly hard to debug as they
--   often cannot be simulated, so it's best to prevent them in the first
--   place. This section outlines the situations in which metastability
--   arises and how to prevent it.
--   
--   Two types of resets exist: synchronous and asynchronous resets. These
--   reset types are encoded in a synthesis domain. For the following
--   examples we assume the following exist:
--   
--   <pre>
--   <a>DomainConfiguration</a> "SyncExample" _period _edge <a>Synchronous</a> _init
--   <a>DomainConfiguration</a> "AsyncExample" _period _edge <a>Asynchronous</a> _init
--   </pre>
--   
--   See the previous section on how to use domains.
--   
--   We now go over the clock and reset line combinations and explain when
--   they can potentially introduce situations prone to meta-stability:
--   
--   <ul>
--   <li><i>Reset situation 1</i>:<pre>f :: <a>Reset</a> "SyncExample"
--   -&gt; <a>Reset</a> "SyncExample" -&gt; .. f x y = .. </pre>There are
--   no problems here, because although <i>x</i> and <i>y</i> can have
--   different values, components to these reset lines are reset
--   <i>synchronously</i>, and there is no metastability situation.</li>
--   <li><i>Reset situation 2</i>:<pre>g :: <a>Reset</a> "AsyncExample"
--   -&gt; <a>Reset</a> "AsyncExample" -&gt; .. g x y = .. </pre>This
--   situation can be prone to metastability, because although <i>x</i> and
--   <i>y</i> belong to the same <i>domain</i> according to their domain,
--   there is no guarantee that they actually originate from the same
--   source. This means that one component can enter its reset state
--   asynchronously to another component, inducing metastability in the
--   other component.</li>
--   <li><i>Clock situation</i>:<pre>k :: <a>Clock</a> dom -&gt;
--   <a>Clock</a> dom -&gt; .. k x y = .. </pre>The situation above is
--   potentially prone to metastability, because even though <i>x</i> and
--   <i>y</i> belong to the same <i>domain</i> according to their domain,
--   there is no guarantee that they actually originate from the same
--   source. They could hence be connected to completely unrelated clock
--   sources, and components can then induce metastable states in
--   others.</li>
--   </ul>
module Clash.Explicit.Signal

-- | Clash has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (dom :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>dom</i> is the <i>clock-</i>
--   (and <i>reset-</i>) domain to which the memory elements manipulating
--   these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>dom</i>, is of the kind <a>Domain</a> - a
--   simple string. That string refers to a single <i>synthesis domain</i>.
--   A synthesis domain describes the behavior of certain aspects of memory
--   elements in it.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   <li><b>NB</b>: For the best compatibility make sure your period is
--   divisible by 2, because some VHDL simulators don't support fractions
--   of picoseconds.</li>
--   <li><b>NB</b>: Whether <a>System</a> has good defaults depends on your
--   target platform. Check out <a>IntelSystem</a> and <a>XilinxSystem</a>
--   too!</li>
--   </ul>
--   
--   Signals have the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Signal
--   type role Signal nominal representational
--   ...
--   </pre>
--   
--   as it is safe to coerce the underlying value of a signal, but not safe
--   to coerce a signal between different synthesis domains.
--   
--   See the module documentation of <a>Clash.Signal</a> for more
--   information about domains.
data Signal (dom :: Domain) a

-- | The <i>in</i> part of an <b>inout</b> port. BiSignalIn has the <a>type
--   role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalIn
--   type role BiSignalIn nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalIn (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | The <i>out</i> part of an <b>inout</b> port
--   
--   Wraps (multiple) writing signals. The semantics are such that only one
--   of the signals may write at a single time step.
--   
--   BiSignalOut has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalOut
--   type role BiSignalOut nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalOut (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | Used to specify the <i>default</i> behavior of a "BiSignal" in Haskell
--   simulation, i.e. what value is read when no value is being written to
--   it.
data BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-up resistor
PullUp :: BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-down resistor
PullDown :: BiSignalDefault

-- | <b>inout</b> port behaves as if is <i>floating</i>. Reading a
--   <i>floating</i> "BiSignal" value in simulation will yield an errorX
--   (undefined value).
Floating :: BiSignalDefault
type Domain = Symbol

-- | A <a>KnownDomain</a> constraint indicates that a circuit's behavior
--   depends on some properties of a domain. See <a>DomainConfiguration</a>
--   for more information.
class (KnownSymbol dom, KnownNat (DomainPeriod dom)) => KnownDomain (dom :: Domain) where {
    type family KnownConf dom :: DomainConfiguration;
}

-- | Returns <a>SDomainConfiguration</a> corresponding to an instance's
--   <a>DomainConfiguration</a>.
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; knownDomain @System
--   SDomainConfiguration {sName = SSymbol @"System", sPeriod = SNat @10000, sActiveEdge = SRising, sResetKind = SAsynchronous, sInitBehavior = SDefined, sResetPolarity = SActiveHigh}
--   </pre>
knownDomain :: KnownDomain dom => SDomainConfiguration dom (KnownConf dom)
type KnownConfiguration dom conf = (KnownDomain dom, KnownConf dom ~ conf)

-- | Determines clock edge memory elements are sensitive to. Not yet
--   implemented.
data ActiveEdge

-- | Elements are sensitive to the rising edge (low-to-high) of the clock.
Rising :: ActiveEdge

-- | Elements are sensitive to the falling edge (high-to-low) of the clock.
Falling :: ActiveEdge

-- | Singleton version of <a>ActiveEdge</a>
data SActiveEdge (edge :: ActiveEdge)
[SRising] :: SActiveEdge 'Rising
[SFalling] :: SActiveEdge 'Falling
data InitBehavior

-- | Power up value of memory elements is <i>unknown</i>.
Unknown :: InitBehavior

-- | If applicable, power up value of a memory element is defined. Applies
--   to <a>register</a>s for example, but not to <a>blockRam</a>.
Defined :: InitBehavior
data SInitBehavior (init :: InitBehavior)
[SUnknown] :: SInitBehavior 'Unknown
[SDefined] :: SInitBehavior 'Defined
data ResetKind

-- | Elements respond <i>asynchronously</i> to changes in their reset
--   input. This means that they do <i>not</i> wait for the next active
--   clock edge, but respond immediately instead. Common on Intel FPGA
--   platforms.
Asynchronous :: ResetKind

-- | Elements respond <i>synchronously</i> to changes in their reset input.
--   This means that changes in their reset input won't take effect until
--   the next active clock edge. Common on Xilinx FPGA platforms.
Synchronous :: ResetKind

-- | Singleton version of <a>ResetKind</a>
data SResetKind (resetKind :: ResetKind)
[SAsynchronous] :: SResetKind 'Asynchronous
[SSynchronous] :: SResetKind 'Synchronous

-- | Determines the value for which a reset line is considered "active"
data ResetPolarity

-- | Reset is considered active if underlying signal is <a>True</a>.
ActiveHigh :: ResetPolarity

-- | Reset is considered active if underlying signal is <a>False</a>.
ActiveLow :: ResetPolarity

-- | Singleton version of <a>ResetPolarity</a>
data SResetPolarity (polarity :: ResetPolarity)
[SActiveHigh] :: SResetPolarity 'ActiveHigh
[SActiveLow] :: SResetPolarity 'ActiveLow

-- | A domain with a name (<tt>Domain</tt>). Configures the behavior of
--   various aspects of a circuits. See the documentation of this record's
--   field types for more information on the options.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
data DomainConfiguration
DomainConfiguration :: Domain -> Nat -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> DomainConfiguration

-- | Domain name
[_name] :: DomainConfiguration -> Domain

-- | Period of clock in <i>ps</i>
[_period] :: DomainConfiguration -> Nat

-- | Active edge of the clock
[_activeEdge] :: DomainConfiguration -> ActiveEdge

-- | Whether resets are synchronous (edge-sensitive) or asynchronous
--   (level-sensitive)
[_resetKind] :: DomainConfiguration -> ResetKind

-- | Whether the initial (or "power up") value of memory elements is
--   unknown/undefined, or configurable to a specific value
[_initBehavior] :: DomainConfiguration -> InitBehavior

-- | Whether resets are active high or active low
[_resetPolarity] :: DomainConfiguration -> ResetPolarity

-- | Singleton version of <a>DomainConfiguration</a>
data SDomainConfiguration (dom :: Domain) (conf :: DomainConfiguration)
[SDomainConfiguration] :: {sName :: SSymbol dom " Domain name", sPeriod :: SNat period " Period of clock in /ps/", sActiveEdge :: SActiveEdge edge " Active edge of the clock (not yet implemented)", sResetKind :: SResetKind reset " Whether resets are synchronous (edge-sensitive) or asynchronous (level-sensitive)", sInitBehavior :: SInitBehavior init " Whether the initial (or "power up") value of memory elements is unknown/undefined, or configurable to a specific value", sResetPolarity :: SResetPolarity polarity " Whether resets are active high or active low"} -> SDomainConfiguration dom ('DomainConfiguration dom period edge reset init polarity)

-- | Convenience type to help to extract a period from a domain. Example
--   usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainPeriod dom ~ 6000) =&gt; ...
--   </pre>
type DomainPeriod (dom :: Domain) = DomainConfigurationPeriod (KnownConf dom)

-- | Convenience type to help to extract the active edge from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainActiveEdge dom ~ 'Rising) =&gt; ...
--   </pre>
type DomainActiveEdge (dom :: Domain) = DomainConfigurationActiveEdge (KnownConf dom)

-- | Convenience type to help to extract the reset synchronicity from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetKind dom ~ 'Synchronous) =&gt; ...
--   </pre>
type DomainResetKind (dom :: Domain) = DomainConfigurationResetKind (KnownConf dom)

-- | Convenience type to help to extract the initial value behavior from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainInitBehavior dom ~ 'Defined) =&gt; ...
--   </pre>
type DomainInitBehavior (dom :: Domain) = DomainConfigurationInitBehavior (KnownConf dom)

-- | Convenience type to help to extract the reset polarity from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetPolarity dom ~ 'ActiveHigh) =&gt; ...
--   </pre>
type DomainResetPolarity (dom :: Domain) = DomainConfigurationResetPolarity (KnownConf dom)

-- | Convenience type to constrain a domain to have synchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasSynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasSynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Synchronous)

-- | Convenience type to constrain a domain to have asynchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasAsynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasAsynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Asynchronous)

-- | Convenience type to constrain a domain to have initial values. Example
--   usage:
--   
--   <pre>
--   myFunc :: HasDefinedInitialValues dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   Note that there is no <tt>UnknownInitialValues dom</tt> as a component
--   that works without initial values will also work if it does have them.
--   
--   <a>Click here for usage hints</a>
type HasDefinedInitialValues (dom :: Domain) = (KnownDomain dom, DomainInitBehavior dom ~ 'Defined)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type System = ("System" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and synchronously to
--   changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type XilinxSystem = ("XilinxSystem" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type IntelSystem = ("IntelSystem" :: Domain)

-- | Convenience value to allow easy "subclassing" of System domain. Should
--   be used in combination with <a>createDomain</a>. For example, if you
--   just want to change the period but leave all other settings intact
--   use:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
vSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of IntelSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vIntelSystem{vName="Intel10", vPeriod=10}
--   </pre>
vIntelSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of XilinxSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vXilinxSystem{vName="Xilinx10", vPeriod=10}
--   </pre>
vXilinxSystem :: VDomainConfiguration

-- | Same as SDomainConfiguration but allows for easy updates through
--   record update syntax. Should be used in combination with
--   <a>vDomain</a> and <a>createDomain</a>. Example:
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
data VDomainConfiguration
VDomainConfiguration :: String -> Natural -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> VDomainConfiguration

-- | Corresponds to <a>_name</a> on <a>DomainConfiguration</a>
[vName] :: VDomainConfiguration -> String

-- | Corresponds to <a>_period</a> on <a>DomainConfiguration</a>
[vPeriod] :: VDomainConfiguration -> Natural

-- | Corresponds to <a>_activeEdge</a> on <a>DomainConfiguration</a>
[vActiveEdge] :: VDomainConfiguration -> ActiveEdge

-- | Corresponds to <a>_resetKind</a> on <a>DomainConfiguration</a>
[vResetKind] :: VDomainConfiguration -> ResetKind

-- | Corresponds to <a>_initBehavior</a> on <a>DomainConfiguration</a>
[vInitBehavior] :: VDomainConfiguration -> InitBehavior

-- | Corresponds to <a>_resetPolarity</a> on <a>DomainConfiguration</a>
[vResetPolarity] :: VDomainConfiguration -> ResetPolarity

-- | Convert <a>SDomainConfiguration</a> to <a>VDomainConfiguration</a>.
--   Should be used in combination with <a>createDomain</a> only.
vDomain :: SDomainConfiguration dom conf -> VDomainConfiguration

-- | Convenience method to express new domains in terms of others.
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
--   
--   The function will create two extra identifiers. The first:
--   
--   <pre>
--   type System10 = ..
--   </pre>
--   
--   You can use that as the dom to Clocks/Resets/Enables/Signals. For
--   example: <tt>Signal System10 Int</tt>. Additionally, it will create a
--   <a>VDomainConfiguration</a> that you can use in later calls to
--   <a>createDomain</a>:
--   
--   <pre>
--   vSystem10 = knownVDomain @System10
--   </pre>
--   
--   It will also make <tt>System10</tt> an instance of <a>KnownDomain</a>.
--   
--   If either identifier is already in scope it will not be generated a
--   second time. Note: This can be useful for example when documenting a
--   new domain:
--   
--   <pre>
--   -- | Here is some documentation for CustomDomain
--   type CustomDomain = ("CustomDomain" :: Domain)
--   
--   -- | Here is some documentation for vCustomDomain
--   createDomain vSystem{vName="CustomDomain"}
--   </pre>
createDomain :: VDomainConfiguration -> Q [Dec]

-- | Like 'knownDomain but yields a <a>VDomainConfiguration</a>. Should
--   only be used in combination with <a>createDomain</a>.
knownVDomain :: forall dom. KnownDomain dom => VDomainConfiguration

-- | Get the clock period from a KnownDomain context
clockPeriod :: forall dom period. (KnownDomain dom, DomainPeriod dom ~ period) => SNat period

-- | Get <a>ActiveEdge</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case activeEdge @dom of
--       SRising -&gt; foo
--       SFalling -&gt; bar
--   </pre>
activeEdge :: forall dom edge. (KnownDomain dom, DomainActiveEdge dom ~ edge) => SActiveEdge edge

-- | Get <a>ResetKind</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetKind @dom of
--       SAsynchronous -&gt; foo
--       SSynchronous -&gt; bar
--   </pre>
resetKind :: forall dom sync. (KnownDomain dom, DomainResetKind dom ~ sync) => SResetKind sync

-- | Get <a>InitBehavior</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case initBehavior @dom of
--       SDefined -&gt; foo
--       SUnknown -&gt; bar
--   </pre>
initBehavior :: forall dom init. (KnownDomain dom, DomainInitBehavior dom ~ init) => SInitBehavior init

-- | Get <a>ResetPolarity</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetPolarity @dom of
--       SActiveHigh -&gt; foo
--       SActiveLow -&gt; bar
--   </pre>
resetPolarity :: forall dom polarity. (KnownDomain dom, DomainResetPolarity dom ~ polarity) => SResetPolarity polarity

-- | A signal of booleans, indicating whether a component is enabled. No
--   special meaning is implied, it's up to the component itself to decide
--   how to respond to its enable line. It is used throughout Clash as a
--   global enable signal.
data Enable dom

-- | Convert a signal of bools to an <a>Enable</a> construct
toEnable :: Signal dom Bool -> Enable dom

-- | Convert <a>Enable</a> construct to its underlying representation: a
--   signal of bools.
fromEnable :: Enable dom -> Signal dom Bool

-- | Enable generator for some domain. Is simply always True.
enableGen :: Enable dom

-- | A clock signal belonging to a domain named <i>dom</i>.
data Clock (dom :: Domain)

-- | A differential clock signal belonging to a domain named <i>dom</i>.
--   The clock input of a design with such an input has two ports which are
--   in antiphase. The first input is the positive phase, the second the
--   negative phase. When using <a>makeTopEntity</a>, the names of the
--   inputs will end in <tt>_p</tt> and <tt>_n</tt> respectively.
--   
--   To create a differential clock in a test bench, you can use
--   <a>clockToDiffClock</a>.
data DiffClock (dom :: Domain)

-- | Calculate the frequency in <b>Hz</b>, given the period in <b>ps</b>
--   
--   I.e., to calculate the clock frequency of a clock with a period of
--   5000 ps:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz 5000
--   2.0e8
--   </pre>
--   
--   Note that if <tt>p</tt> in <tt>periodToHz (<a>fromIntegral</a> p)</tt>
--   is negative, <tt>fromIntegral</tt> will give an <tt><a>Underflow</a>
--   :: <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Ratio</a>
--   <a>Natural</a>. To get the old behavior of this function, use a type
--   application:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz @(Ratio Natural) 5000
--   200000000 % 1
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
periodToHz :: (HasCallStack, Fractional a) => Natural -> a

-- | Calculate the period in <b>ps</b>, given a frequency in <b>Hz</b>
--   
--   I.e., to calculate the clock period for a circuit to run at 240 MHz we
--   get
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod 240e6
--   4166
--   </pre>
--   
--   If the value <tt>hzToPeriod</tt> is applied to is not of the type
--   <a>Ratio</a> <a>Natural</a>, you can use <tt>hzToPeriod
--   (<a>realToFrac</a> f)</tt>. Note that if <tt>f</tt> is negative,
--   <tt>realToFrac</tt> will give an <tt><a>Underflow</a> ::
--   <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Natural</a>. To
--   get the old behavior of this function, use a type application:
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod @Natural 240e6
--   4166
--   </pre>
--   
--   <ul>
--   <li><b>NB</b>: This function is not synthesizable</li>
--   <li><b>NB</b>: This function is lossy. I.e., <tt>periodToHz .
--   hzToPeriod /= id</tt>.</li>
--   </ul>
hzToPeriod :: (HasCallStack, Integral a) => Ratio Natural -> a

-- | The <a>unsafeSynchronizer</a> function is a primitive that must be
--   used to connect one clock domain to the other, and will be synthesized
--   to a (bundle of) wire(s) in the eventual circuit. This function should
--   only be used as part of a proper synchronization component, such as
--   the following dual flip-flop synchronizer:
--   
--   <pre>
--   dualFlipFlop
--     :: Clock domA
--     -&gt; Clock domB
--     -&gt; Enable domA
--     -&gt; Enable domB
--     -&gt; Bit
--     -&gt; Signal domA Bit
--     -&gt; Signal domB Bit
--   dualFlipFlop clkA clkB enA enB dflt =
--     <a>delay</a> clkB enB dflt . <a>delay</a> clkB enB dflt . <a>unsafeSynchronizer</a> clkA clkB
--   </pre>
--   
--   The <a>unsafeSynchronizer</a> works in such a way that, given 2
--   clocks:
--   
--   <pre>
--   createDomain vSystem{vName="Dom7", vPeriod=7}
--   
--   clk7 :: <a>Clock</a> Dom7
--   clk7 = <a>clockGen</a>
--   
--   en7 :: <a>Enable</a> Dom7
--   en7 = <a>enableGen</a>
--   </pre>
--   
--   and
--   
--   <pre>
--   createDomain vSystem{vName="Dom2", vPeriod=2}
--   
--   clk2 :: <a>Clock</a> Dom2
--   clk2 = <a>clockGen</a>
--   
--   en2 :: <a>Enable</a> Dom2
--   en2 = <a>enableGen</a>
--   </pre>
--   
--   Oversampling followed by compression is the identity function plus 2
--   initial values:
--   
--   <pre>
--   <a>delay</a> clkB enB dflt $
--   <a>unsafeSynchronizer</a> clkA clkB $
--   <a>delay</a> clkA enA dflt $
--   <a>unsafeSynchronizer</a> clkB clkA $
--   <a>delay</a> clkB enB s
--   
--   ==
--   
--   dflt :- dflt :- s
--   </pre>
--   
--   Something we can easily observe:
--   
--   <pre>
--   oversampling clkA clkB enA enB dflt =
--     <a>delay</a> clkB enB dflt
--       . <a>unsafeSynchronizer</a> clkA clkB
--       . <a>delay</a> clkA enA dflt
--   almostId clkA clkB enA enB dflt =
--     <a>delay</a> clkB enB dflt
--       . <a>unsafeSynchronizer</a> clkA clkB
--       . <a>delay</a> clkA enA dflt
--       . <a>unsafeSynchronizer</a> clkB clkA
--       . <a>delay</a> clkB enB dflt
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 37 (oversampling clk7 clk2 en7 en2 0 (fromList [(1::Int)..10]))
--   [0,0,1,1,1,2,2,2,2,3,3,3,4,4,4,4,5,5,5,6,6,6,6,7,7,7,8,8,8,8,9,9,9,10,10,10,10]
--   
--   &gt;&gt;&gt; sampleN 12 (almostId clk2 clk7 en2 en7 0 (fromList [(1::Int)..10]))
--   [0,0,1,2,3,4,5,6,7,8,9,10]
--   </pre>
unsafeSynchronizer :: forall dom1 dom2 a. (KnownDomain dom1, KnownDomain dom2) => Clock dom1 -> Clock dom2 -> Signal dom1 a -> Signal dom2 a

-- | Same as <a>unsafeSynchronizer</a>, but with manually supplied clock
--   periods.
--   
--   Note: this unsafeSynchronizer is defined to be consistent with the
--   vhdl and verilog implementations however as only synchronous signals
--   are represented in Clash this cannot be done precisely and can lead to
--   odd behavior. For example,
--   
--   <pre>
--   sample $ unsafeSynchronizer @Dom2 @Dom7 . unsafeSynchronizer @Dom7 @Dom2 $ fromList [0..10]
--   &gt; [0,4,4,4,7,7,7,7,11,11,11..
--   </pre>
--   
--   is quite different from the identity,
--   
--   <pre>
--   sample $ fromList [0..10]
--   &gt; [0,1,2,3,4,5,6,7,8,9,10..
--   </pre>
--   
--   with values appearing from the "future".
veryUnsafeSynchronizer :: Either Int (Signal dom1 Int) -> Either Int (Signal dom2 Int) -> Signal dom1 a -> Signal dom2 a

-- | A reset signal belonging to a domain called <i>dom</i>.
--   
--   The underlying representation of resets is <a>Bool</a>.
data Reset (dom :: Domain)

-- | <a>unsafeToReset</a> is unsafe. For asynchronous resets it is unsafe
--   because it can introduce combinatorial loops. In case of synchronous
--   resets it can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeFromActiveLow</a> or
--   <a>unsafeFromActiveHigh</a>.
unsafeToReset :: KnownDomain dom => Signal dom Bool -> Reset dom

-- | <a>unsafeFromReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeToActiveLow</a> or
--   <a>unsafeToActiveHigh</a>.
unsafeFromReset :: Reset dom -> Signal dom Bool

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveHigh :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveLow :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveHigh :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveLow :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Merge enable signal with signal of bools by applying the boolean AND
--   operation.
andEnable :: Enable dom -> Signal dom Bool -> Enable dom

-- | Special version of <a>delay</a> that doesn't take enable signals of
--   any kind. Initial value will be undefined.
dflipflop :: (KnownDomain dom, NFDataX a) => Clock dom -> Signal dom a -> Signal dom a

-- | "<tt><a>delay</a> clk s</tt>" delays the values in <a>Signal</a>
--   <i>s</i> for once cycle, the value at time 0 is <i>dflt</i>.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 3 (delay systemClockGen enableGen 0 (fromList [1,2,3,4]))
--   [0,1,2]
--   </pre>
delay :: (KnownDomain dom, NFDataX a) => Clock dom -> Enable dom -> a -> Signal dom a -> Signal dom a

-- | Version of <a>delay</a> that only updates when its third argument is a
--   <a>Just</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; let input = fromList [Just 1, Just 2, Nothing, Nothing, Just 5, Just 6, Just (7::Int)]
--   
--   &gt;&gt;&gt; sampleN 7 (delayMaybe systemClockGen enableGen 0 input)
--   [0,1,2,2,2,5,6]
--   </pre>
delayMaybe :: (KnownDomain dom, NFDataX a) => Clock dom -> Enable dom -> a -> Signal dom (Maybe a) -> Signal dom a

-- | Version of <a>delay</a> that only updates when its third argument is
--   asserted.
--   
--   <pre>
--   &gt;&gt;&gt; let input = fromList [1,2,3,4,5,6,7::Int]
--   
--   &gt;&gt;&gt; let enable = fromList [True,True,False,False,True,True,True]
--   
--   &gt;&gt;&gt; sampleN 7 (delayEn systemClockGen enableGen 0 enable input)
--   [0,1,2,2,2,5,6]
--   </pre>
delayEn :: (KnownDomain dom, NFDataX a) => Clock dom -> Enable dom -> a -> Signal dom Bool -> Signal dom a -> Signal dom a

-- | "<tt><a>register</a> clk rst en i s</tt>" delays the values in
--   <a>Signal</a> <i>s</i> for one cycle, and sets the value to <tt>i</tt>
--   the moment the reset becomes <a>False</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 5 (register systemClockGen resetGen enableGen 8 (fromList [1,1,2,3,4]))
--   [8,8,1,2,3]
--   </pre>
register :: (KnownDomain dom, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom a -> Signal dom a

-- | Version of <a>register</a> that only updates its content when its
--   fourth argument is a <a>Just</a> value. So given:
--   
--   <pre>
--   sometimes1 clk rst en = s where
--     s = <a>register</a> clk rst en Nothing (switch <a>&lt;$&gt;</a> s)
--   
--     switch Nothing = Just 1
--     switch _       = Nothing
--   
--   countSometimes clk rst en = s where
--     s     = <a>regMaybe</a> clk rst en 0 (plusM (<a>pure</a> <a>&lt;$&gt;</a> s) (sometimes1 clk rst en))
--     plusM = liftA2 (liftA2 (+))
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 9 (sometimes1 systemClockGen resetGen enableGen)
--   [Nothing,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]
--   
--   &gt;&gt;&gt; sampleN 9 (count systemClockGen resetGen enableGen)
--   [0,0,0,1,1,2,2,3,3]
--   </pre>
regMaybe :: (KnownDomain dom, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom (Maybe a) -> Signal dom a

-- | Version of <a>register</a> that only updates its content when its
--   fourth argument is asserted. So given:
--   
--   <pre>
--   oscillate clk rst en = let s = <a>register</a> clk rst en False (not &lt;$&gt; s) in s
--   count clk rst en     = let s = 'regEn clk rst en 0 (oscillate clk rst en) (s + 1) in s
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 9 (oscillate systemClockGen resetGen enableGen)
--   [False,False,True,False,True,False,True,False,True]
--   
--   &gt;&gt;&gt; sampleN 9 (count systemClockGen resetGen enableGen)
--   [0,0,0,1,1,2,2,3,3]
--   </pre>
regEn :: (KnownDomain dom, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom Bool -> Signal dom a -> Signal dom a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>mux</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a
--   </pre>
--   
--   A multiplexer. Given "<tt><a>mux</a> b t f</tt>", output <tt>t</tt>
--   when <tt>b</tt> is <a>True</a>, and <tt>f</tt> when <tt>b</tt> is
--   <a>False</a>.
mux :: Applicative f => f Bool -> f a -> f a -> f a

-- | Clock generator for simulations. Do <b>not</b> use this clock
--   generator for the <i>testBench</i> function, use <a>tbClockGen</a>
--   instead.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem = clockGen @System
--   </pre>
--   
--   See <a>DomainConfiguration</a> for more information on how to use
--   synthesis domains.
clockGen :: KnownDomain dom => Clock dom

-- | Reset generator for simulation purposes. Asserts the reset for a
--   single cycle.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem = resetGen @System
--   </pre>
--   
--   See <a>tbClockGen</a> for example usage.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGen :: forall dom. KnownDomain dom => Reset dom

-- | Reset generator for simulation purposes. Asserts the reset for the
--   first <i>n</i> cycles.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem5 = resetGen @System d5
--   </pre>
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (unsafeToActiveHigh (resetGenN @System d3))
--   [True,True,True,False,False,False,False]
--   </pre>
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGenN :: forall dom n. (KnownDomain dom, 1 <= n) => SNat n -> Reset dom

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: Should only be used for simulation, and <b>not</b> for the
--   <i>testBench</i> function. For the <i>testBench</i> function, used
--   <a>tbSystemClockGen</a>
systemClockGen :: Clock System

-- | Reset generator for use in simulation, for the <a>System</a> clock
--   domain. Asserts the reset for a single cycle.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = <a>systemResetGen</a>
--   </pre>
systemResetGen :: Reset System

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&amp;&amp;.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&amp;&amp;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.&&.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 3 .&&.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.||.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>||</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.||.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 2 .||.

-- | Isomorphism between a <a>Signal</a> of a product type (e.g. a tuple)
--   and a product type of <a>Signal</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <a>Unbundled</a> clk D = <a>Signal</a> clk D
--     <a>bundle</a>   s = s
--     <a>unbundle</a> s = s
--   </pre>
--   
--   For custom product types you'll have to write the instance manually:
--   
--   <pre>
--   data Pair a b = MkPair { getA :: a, getB :: b }
--   
--   instance Bundle (Pair a b) where
--     type Unbundled dom (Pair a b) = Pair (Signal dom a) (Signal dom b)
--   
--     -- bundle :: Pair (Signal dom a) (Signal dom b) -&gt; Signal dom (Pair a b)
--     bundle   (MkPair as bs) = MkPair <a>&lt;$&gt;</a> as <a>&lt;*&gt;</a> bs
--   
--     -- unbundle :: Signal dom (Pair a b) -&gt; Pair (Signal dom a) (Signal dom b)
--     unbundle pairs = MkPair (getA <a>&lt;$&gt;</a> pairs) (getB <a>&lt;$&gt;</a> pairs)
--   </pre>
class Bundle a where {
    type family Unbundled (dom :: Domain) a = res | res -> dom a;
    type Unbundled dom a = Signal dom a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: (Bundle a, Signal dom a ~ Unbundled dom a) => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: Bundle a => Signal dom a -> Unbundled dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, Unbundled dom a ~ Signal dom a) => Signal dom a -> Unbundled dom a

-- | See <a>TaggedEmptyTuple</a>
data EmptyTuple
EmptyTuple :: EmptyTuple

-- | Helper type to emulate the "old" behavior of Bundle's unit instance.
--   I.e., the instance for <tt>Bundle ()</tt> used to be defined as:
--   
--   <pre>
--   class Bundle () where
--     bundle   :: () -&gt; Signal dom ()
--     unbundle :: Signal dom () -&gt; ()
--   </pre>
--   
--   In order to have sensible type inference, the <a>Bundle</a> class
--   specifies that the argument type of <a>bundle</a> should uniquely
--   identify the result type, and vice versa for <a>unbundle</a>. The type
--   signatures in the snippet above don't though, as <tt>()</tt> doesn't
--   uniquely map to a specific domain. In other words, <tt>domain</tt>
--   should occur in both the argument and result of both functions.
--   
--   <a>TaggedEmptyTuple</a> tackles this by carrying the domain in its
--   type. The <a>bundle</a> and <a>unbundle</a> instance now looks like:
--   
--   <pre>
--   class Bundle EmptyTuple where
--     bundle   :: TaggedEmptyTuple dom -&gt; Signal dom EmptyTuple
--     unbundle :: Signal dom EmptyTuple -&gt; TaggedEmptyTuple dom
--   </pre>
--   
--   <tt>dom</tt> is now mentioned both the argument and result for both
--   <a>bundle</a> and <a>unbundle</a>.
data TaggedEmptyTuple (dom :: Domain)
TaggedEmptyTuple :: TaggedEmptyTuple (dom :: Domain)

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen resetGen enableGen 8) [1, 1, 2, 3]
--   [8,8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulate :: (NFDataX a, NFDataX b) => (Signal dom1 a -> Signal dom2 b) -> [a] -> [b]

-- | Simulate a (<tt><a>Unbundled</a> a -&gt; <a>Unbundled</a> b</tt>)
--   function given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (unbundle . register systemClockGen resetGen enableGen (8,8) . bundle) [(1,1), (1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulateB :: (Bundle a, Bundle b, NFDataX a, NFDataX b) => (Unbundled dom1 a -> Unbundled dom2 b) -> [a] -> [b]

-- | Same as <a>simulate</a>, but with the reset line asserted for <i>n</i>
--   cycles. Similar to <a>simulate</a>, <a>simulateWithReset</a> will drop
--   the output values produced while the reset is asserted. While the
--   reset is asserted, the first value from <tt>[a]</tt> is fed to the
--   circuit.
simulateWithReset :: forall dom a b m. (KnownDomain dom, NFDataX a, NFDataX b, 1 <= m) => SNat m -> a -> (KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Same as <a>simulateWithReset</a>, but only sample the first <i>Int</i>
--   output values.
simulateWithResetN :: (KnownDomain dom, NFDataX a, NFDataX b, 1 <= m) => SNat m -> a -> Int -> (KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Simulate a component until it matches a condition
--   
--   It prints a message of the form
--   
--   <pre>
--   Signal sampled for N cycles until value X
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
--   
--   <h3><b>Example with test bench</b></h3>
--   
--   A common usage is with a test bench using <a>outputVerifier</a>.
--   
--   <b>NB</b>: Since this uses <a>assert</a>, when using <tt>clashi</tt>,
--   read the note at <a>Clash.Explicit.Testbench#assert-clashi</a>.
--   
--   <pre>
--   import Clash.Prelude
--   import Clash.Explicit.Testbench
--   
--   topEntity
--     :: <a>Signal</a> <a>System</a> Int
--     -&gt; <a>Signal</a> <a>System</a> Int
--   topEntity = id
--   
--   testBench
--     :: <a>Signal</a> <a>System</a> Bool
--   testBench = done
--    where
--     testInput = <a>stimuliGenerator</a> clk rst $(<a>listToVecTH</a> [1 :: Int .. 10])
--     expectedOutput =
--       <a>outputVerifier'</a> clk rst $(<a>listToVecTH</a> $ [1 :: Int .. 9] <a>&lt;&gt;</a> [42])
--     done = expectedOutput $ topEntity testInput
--     clk = <a>tbSystemClockGen</a> (not &lt;$&gt; done)
--     rst = <a>systemResetGen</a>
--   </pre>
--   
--   <pre>
--   &gt; runUntil id testBench
--   
--   
--   cycle(&lt;Clock: System&gt;): 10, outputVerifier
--   expected value: 42, not equal to actual value: 10
--   Signal sampled for 11 cycles until value True
--   </pre>
--   
--   When you need to verify multiple test benches, the following
--   invocations come in handy:
--   
--   <pre>
--   &gt; <a>mapM_</a> (runUntil id) [ testBenchA, testBenchB ]
--   </pre>
--   
--   or when the test benches are in different clock domains:
--   
--   <pre>
--   testBenchA :: Signal DomA Bool
--   testBenchB :: Signal DomB Bool
--   </pre>
--   
--   <pre>
--   &gt; <a>sequence_</a> [ runUntil id testBenchA, runUntil id testBenchB ]
--   </pre>
runUntil :: forall dom a. (KnownDomain dom, NFDataX a, ShowX a) => (a -> Bool) -> Signal dom a -> IO ()

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen resetGen enableGen 8) [1, 1, 2, 3]
--   [8,8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulate_lazy :: (Signal dom1 a -> Signal dom2 b) -> [a] -> [b]

-- | <i>Lazily</i> simulate a (<tt><a>Unbundled</a> a -&gt;
--   <a>Unbundled</a> b</tt>) function given a list of samples of type
--   <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (unbundle . register systemClockGen resetGen enableGen (8,8) . bundle) [(1,1), (1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulateB_lazy :: (Bundle a, Bundle b) => (Unbundled dom1 a -> Unbundled dom2 b) -> [a] -> [b]

-- | Build an <a>Automaton</a> from a function over <a>Signal</a>s.
--   
--   <b>NB</b>: Consumption of continuation of the <a>Automaton</a> must be
--   affine; that is, you can only apply the continuation associated with a
--   particular element at most once.
signalAutomaton :: forall dom a b. (Signal dom a -> Signal dom b) -> Automaton (->) a b

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sample :: (Foldable f, NFDataX a) => f a -> [a]

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sampleN :: (Foldable f, NFDataX a) => Int -> f a -> [a]

-- | Get a list of samples from a <a>Signal</a>, while asserting the reset
--   line for <i>n</i> clock cycles. <a>sampleWithReset</a> does not return
--   the first <i>n</i> cycles, i.e., when the reset is asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleWithReset :: forall dom a m. (KnownDomain dom, NFDataX a, 1 <= m) => SNat m -> (KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> Signal dom a) -> [a]

-- | Get a fine list of <i>m</i> samples from a <a>Signal</a>, while
--   asserting the reset line for <i>n</i> clock cycles.
--   <a>sampleWithReset</a> does not return the first <i>n</i> cycles,
--   i.e., while the reset is asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleWithResetN :: forall dom a m. (KnownDomain dom, NFDataX a, 1 <= m) => SNat m -> Int -> (KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> Signal dom a) -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList :: NFDataX a => [a] -> Signal dom a

-- | Like <a>fromList</a>, but resets on reset and has a defined reset
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; let rst = unsafeFromActiveHigh (fromList [True, True, False, False, True, False])
--   
--   &gt;&gt;&gt; let res = fromListWithReset @System rst Nothing [Just 'a', Just 'b', Just 'c']
--   
--   &gt;&gt;&gt; sampleN 6 res
--   [Nothing,Nothing,Just 'a',Just 'b',Nothing,Just 'a']
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromListWithReset :: forall dom a. (KnownDomain dom, NFDataX a) => Reset dom -> a -> [a] -> Signal dom a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sample_lazy :: Foldable f => f a -> [a]

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
sampleN_lazy :: Foldable f => Int -> f a -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5] :: Signal System Int)
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList_lazy :: [a] -> Signal dom a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>testFor</b> :: <a>Int</a> -&gt; <a>Signal</a> Bool -&gt; <a>Property</a>
--   </pre>
--   
--   <tt>testFor n s</tt> tests the signal <tt>s</tt> for <tt>n</tt>
--   cycles.
--   
--   <b>NB</b>: This function is not synthesizable
testFor :: Foldable f => Int -> f Bool -> Property

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.==.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>==</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.==.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 .==.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(./=.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>/=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(./=.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 ./=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>.

-- | Converts the <tt>out</tt> part of a BiSignal to an <tt>in</tt> part.
--   In simulation it checks whether multiple components are writing and
--   will error accordingly. Make sure this is only called ONCE for every
--   BiSignal.
veryUnsafeToBiSignalIn :: (HasCallStack, KnownNat n, Given (SBiSignalDefault ds)) => BiSignalOut ds d n -> BiSignalIn ds d n

-- | Read the value from an <b>inout</b> port
readFromBiSignal :: (HasCallStack, BitPack a) => BiSignalIn ds d (BitSize a) -> Signal d a

-- | Write to an <b>inout</b> port
writeToBiSignal :: (HasCallStack, BitPack a, NFDataX a) => BiSignalIn ds d (BitSize a) -> Signal d (Maybe a) -> BiSignalOut ds d (BitSize a)

-- | Combine several <b>inout</b> signals into one.
mergeBiSignalOuts :: (HasCallStack, KnownNat n) => Vec n (BiSignalOut defaultState dom m) -> BiSignalOut defaultState dom m

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromHighPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromLowPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToHighPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToLowPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool


module Clash.Explicit.Signal.Delayed

-- | A synchronized signal with samples of type <tt>a</tt>, synchronized to
--   clock <tt>clk</tt>, that has accumulated <tt>delay</tt> amount of
--   samples delay along its path.
--   
--   DSignal has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i DSignal
--   type role DSignal nominal nominal representational
--   ...
--   </pre>
--   
--   as it is safe to coerce the values in the signal, but not safe to
--   coerce the synthesis domain or delay in the signal.
data DSignal (dom :: Domain) (delay :: Nat) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> periods.
--   
--   <pre>
--   delay3
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 3) Int
--   delay3 clk rst en = <a>delayed</a> clk rst en (-1 <a>:&gt;</a> -1 <a>:&gt;</a> -1 <a>:&gt;</a> <a>Nil</a>)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (delay3 systemClockGen resetGen enableGen (dfromList [0..]))
--   [-1,-1,-1,-1,1,2,3]
--   </pre>
delayed :: forall dom a n d. (KnownDomain dom, KnownNat d, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> Vec d a -> DSignal dom n a -> DSignal dom (n + d) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> periods, where <tt>d</tt> is
--   derived from the context.
--   
--   <pre>
--   delay2
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; Int
--     -&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 2) Int
--   delay2 = <a>delayedI</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (delay2 systemClockGen resetGen enableGen (-1) (dfromList ([0..])))
--   [-1,-1,-1,1,2,3,4]
--   </pre>
--   
--   <tt>d</tt> can also be specified using type application:
--   
--   <pre>
--   &gt;&gt;&gt; :t delayedI @3
--   delayedI @3
--     :: ... =&gt;
--        Clock dom
--        -&gt; Reset dom
--        -&gt; Enable dom
--        -&gt; a
--        -&gt; DSignal dom n a
--        -&gt; DSignal dom (n + 3) a
--   </pre>
delayedI :: (KnownNat d, KnownDomain dom, NFDataX a) => Clock dom -> Reset dom -> Enable dom -> a -> DSignal dom n a -> DSignal dom (n + d) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> cycles, the value at time 0..d-1
--   is <i>a</i>.
--   
--   <pre>
--   delayN2
--     :: <a>KnownDomain</a> dom
--     =&gt; Int
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Clock</a> dom
--     -&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 2) Int
--   delayN2 = <a>delayN</a> d2
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 6 (delayN2 (-1) enableGen systemClockGen (dfromList [1..]))
--   [-1,-1,1,2,3,4]
--   </pre>
delayN :: forall dom a d n. (KnownDomain dom, NFDataX a) => SNat d -> a -> Enable dom -> Clock dom -> DSignal dom n a -> DSignal dom (n + d) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> cycles, where <tt>d</tt> is
--   derived from the context. The value at time 0..d-1 is a default value.
--   
--   <pre>
--   delayI2
--     :: <a>KnownDomain</a> dom
--     =&gt; Int
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Clock</a> dom
--     -&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 2) Int
--   delayI2 = <a>delayI</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (delayI2 (-1) enableGen systemClockGen (dfromList [1..]))
--   [-1,-1,1,2,3,4]
--   </pre>
--   
--   You can also use type application to do the same:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (delayI @2 (-1) enableGen systemClockGen (dfromList [1..]))
--   [-1,-1,1,2,3,4]
--   </pre>
delayI :: forall d n a dom. (NFDataX a, KnownDomain dom, KnownNat d) => a -> Enable dom -> Clock dom -> DSignal dom n a -> DSignal dom (n + d) a

-- | Tree fold over a <a>Vec</a> of <a>DSignal</a>s with a combinatorial
--   function, and delaying <tt>delay</tt> cycles after each application.
--   Values at times 0..(delay*k)-1 are set to a default.
--   
--   <pre>
--   countingSignals :: Vec 4 (DSignal dom 0 Int)
--   countingSignals = repeat (dfromList [0..])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 6 (delayedFold  d1 (-1) (+) enableGen systemClockGen countingSignals)
--   [-1,-2,0,4,8,12]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 8 (delayedFold d2 (-1) (*) enableGen systemClockGen countingSignals)
--   [-1,-1,1,1,0,1,16,81]
--   </pre>
delayedFold :: forall dom n delay k a. (NFDataX a, KnownDomain dom, KnownNat delay, KnownNat k) => SNat delay -> a -> (a -> a -> a) -> Enable dom -> Clock dom -> Vec (2 ^ k) (DSignal dom n a) -> DSignal dom (n + (delay * k)) a

-- | Feed the delayed result of a function back to its input:
--   
--   <pre>
--   mac
--     :: forall dom
--      . KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--   mac clk rst en x y = <a>feedback</a> (mac' x y)
--     where
--       mac'
--         :: <a>DSignal</a> dom 0 Int
--         -&gt; <a>DSignal</a> dom 0 Int
--         -&gt; <a>DSignal</a> dom 0 Int
--         -&gt; (<a>DSignal</a> dom 0 Int, <a>DSignal</a> dom 1 Int)
--       mac' a b acc = let acc' = a * b + acc
--                      in  (acc, <a>delayedI</a> clk rst en 0 acc')
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (toSignal (mac systemClockGen systemResetGen enableGen (dfromList [0..]) (dfromList [0..])))
--   [0,0,1,5,14,30,55]
--   </pre>
feedback :: (DSignal dom n a -> (DSignal dom n a, DSignal dom ((n + m) + 1) a)) -> DSignal dom n a

-- | <a>Signal</a>s are not delayed
fromSignal :: Signal dom a -> DSignal dom 0 a

-- | Strip a <a>DSignal</a> of its delay information.
toSignal :: DSignal dom delay a -> Signal dom a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (toSignal (dfromList [1,2,3,4,5]))
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
dfromList :: NFDataX a => [a] -> DSignal dom 0 a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (toSignal (dfromList [1,2,3,4,5]))
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
dfromList_lazy :: [a] -> DSignal dom 0 a

-- | <b>EXPERIMENTAL</b>
--   
--   <b>Unsafely</b> convert a <a>Signal</a> to a <a>DSignal</a> with an
--   arbitrary <tt>delay</tt>.
--   
--   <b>NB</b>: Should only be used to interface with functions specified
--   in terms of <a>Signal</a>.
unsafeFromSignal :: Signal dom a -> DSignal dom n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal from the future in the present. Often
--   required When writing a circuit that requires feedback from itself.
--   
--   <pre>
--   mac
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--   mac clk rst en x y = acc'
--     where
--       acc' = (x * y) + <a>antiDelay</a> d1 acc
--       acc  = <a>delayedI</a> clk rst en 0 acc'
--   </pre>
antiDelay :: SNat d -> DSignal dom (n + d) a -> DSignal dom n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal from the past in the present. In
--   contrast with <a>delayed</a> and friends forward does not insert any
--   logic. This means using this function violates the delay invariant of
--   <a>DSignal</a>. This is sometimes useful when combining unrelated
--   delayed signals where inserting logic is not wanted or when
--   abstracting over internal delayed signals where the internal delay
--   information should not be leaked.
--   
--   For example, the circuit below returns a sequence of numbers as a pair
--   but the internal delay information between the elements of the pair
--   should not leak into the type.
--   
--   <pre>
--   numbers
--     :: forall dom
--      . KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 5 (Int, Int)
--   numbers clk rst en = DB.bundle (forward d1 s1, s2)
--     where
--       s1 :: <a>DSignal</a> dom 4 Int
--       s1 = <a>delayed</a> clk rst en (100 :&gt; 10 :&gt; 5 :&gt; 1 :&gt; Nil) (pure 200)
--       s2 :: <a>DSignal</a> dom 5 Int
--       s2 = fmap (2*) $ <a>delayN</a> d1 0 en clk s1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 8 (toSignal (numbers systemClockGen systemResetGen enableGen))
--   [(1,0),(1,2),(5,2),(10,10),(100,20),(200,200),(200,400),(200,400)]
--   </pre>
forward :: SNat d -> DSignal dom n a -> DSignal dom (n + d) a


-- | <h1>Initializing a ROM with a data file </h1>
--   
--   ROMs initialized with a data file. The BNF grammar for this data file
--   is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned numbers <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   Such a file can be produced with <a>memFile</a>:
--   
--   <pre>
--   writeFile "memory.bin" (memFile Nothing [7 :: Unsigned 9 .. 13])
--   </pre>
--   
--   We can instantiate a synchronous ROM using the contents of the file
--   above like so:
--   
--   <pre>
--   f :: KnownDomain dom
--     =&gt; Clock  dom
--     -&gt; Enable dom
--     -&gt; Signal dom (Unsigned 3)
--     -&gt; Signal dom (Unsigned 9)
--   f clk en rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> clk en d7 "memory.bin" rd
--   </pre>
--   
--   And see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f systemClockGen (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g :: KnownDomain dom
--     =&gt; Clock  dom
--     -&gt; Signal dom (Unsigned 3)
--     -&gt; Signal dom (Unsigned 6,Signed 3)
--   g clk en rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> clk en d7 "memory.bin" rd
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g systemClockGen (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Explicit.ROM.File

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, Enum addr, KnownDomain dom) => Clock dom -> Enable dom -> SNat n -> FilePath -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
romFilePow2 :: forall dom n m. (KnownNat m, KnownNat n, KnownDomain dom) => Clock dom -> Enable dom -> FilePath -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Convert data to the <a>String</a> contents of a memory file.
--   
--   <ul>
--   <li><b>NB</b>: Not synthesizable</li>
--   <li>The following document the several ways to instantiate components
--   with
--   files:<ul><li><a>Clash.Prelude.BlockRam.File#usingramfiles</a></li><li><a>Clash.Prelude.ROM.File#usingromfiles</a></li><li><a>Clash.Explicit.BlockRam.File#usingramfiles</a></li><li><a>Clash.Explicit.ROM.File#usingromfiles</a></li></ul></li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
--   
--   <h1>Example</h1>
--   
--   The <tt>Maybe</tt> datatype has don't care bits, where the actual
--   value does not matter. But the bits need a defined value in the
--   memory. Either 0 or 1 can be used, and both are valid representations
--   of the data.
--   
--   <pre>
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8]
--   
--   &gt;&gt;&gt; mapM_ (putStrLn . show . pack) es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 0) es)
--   000000000
--   100000111
--   100001000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 1) es)
--   011111111
--   100000111
--   100001000
--   </pre>
memFile :: forall a f. (BitPack a, Foldable f, HasCallStack) => Maybe Bit -> f a -> String

-- | romFile primitive
romFile# :: forall m dom n. (KnownNat m, KnownDomain dom) => Clock dom -> Enable dom -> SNat n -> FilePath -> Signal dom Int -> Signal dom (BitVector m)


-- | RAM primitives with a combinational read port.
module Clash.Explicit.RAM

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, NFDataX addr, HasCallStack, KnownDomain wdom, KnownDomain rdom, NFDataX a) => Clock wdom -> Clock rdom -> Enable wdom -> SNat n -> Signal rdom addr -> Signal wdom (Maybe (addr, a)) -> Signal rdom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: forall wdom rdom n a. (KnownNat n, HasCallStack, KnownDomain wdom, KnownDomain rdom, NFDataX a) => Clock wdom -> Clock rdom -> Enable wdom -> Signal rdom (Unsigned n) -> Signal wdom (Maybe (Unsigned n, a)) -> Signal rdom a

-- | RAM primitive
asyncRam# :: forall wdom rdom n a. (HasCallStack, KnownDomain wdom, KnownDomain rdom, NFDataX a) => Clock wdom -> Clock rdom -> Enable wdom -> SNat n -> Signal rdom Int -> Signal wdom Bool -> Signal wdom Int -> Signal wdom a -> Signal rdom a


-- | Whereas the output of a Mealy machine depends on <i>current
--   transition</i>, the output of a Moore machine depends on the
--   <i>previous state</i>.
--   
--   Moore machines are strictly less expressive, but may impose laxer
--   timing requirements.
module Clash.Explicit.Moore

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac clk rst en = <a>moore</a> clk rst en macT id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen enableGen) [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac clk rst en (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> clk rst en macT id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> clk rst en macT id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> (s -> o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (moore clk rst en t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (moore clk rst en t o 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> clk rst en t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> clk rst en t o 3 (c,i1)
--   </pre>
mooreB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> (s -> o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a synchronous function from a combinational function describing
--   a moore machine without any output logic
medvedev :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> s -> Signal dom i -> Signal dom s

-- | A version of <a>medvedev</a> that does automatic <a>Bundle</a>ing
medvedevB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> s -> Unbundled dom i -> Unbundled dom s


-- | Whereas the output of a Moore machine depends on the <i>previous
--   state</i>, the output of a Mealy machine depends on <i>current
--   transition</i>.
--   
--   Mealy machines are strictly more expressive, but may impose stricter
--   timing requirements.
module Clash.Explicit.Mealy

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   import qualified Data.List as L
--   
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac clk rst en = <a>mealy</a> clk rst en macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen enableGen) [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac clk rst en (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> clk rst en macT 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> clk rst en macT 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o

-- | Create a synchronous function from a combinational function describing
--   a mealy machine using the state monad. This can be particularly useful
--   when combined with lenses or optics to replicate imperative
--   algorithms.
--   
--   <pre>
--   data DelayState = DelayState
--     { _history    :: Vec 4 Int
--     , _untilValid :: Index 4
--     }
--     deriving (Generic, NFDataX)
--   makeLenses ''DelayState
--   
--   initialDelayState = DelayState (repeat 0) maxBound
--   
--   delayS :: Int -&gt; State DelayState (Maybe Int)
--   delayS n = do
--     history   %= (n +&gt;&gt;)
--     remaining &lt;- use untilValid
--     if remaining &gt; 0
--     then do
--        untilValid -= 1
--        return Nothing
--      else do
--        out &lt;- uses history last
--        return (Just out)
--   
--   delayTop ::<a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int -&gt; <a>Signal</a> dom (Maybe Int))
--   delayTop clk rst en = <a>mealyS</a> clk rst en delayS initialDelayState
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; L.take 7 $ simulate (delayTop systemClockGen systemResetGen enableGen) [-100,1,2,3,4,5,6,7,8]
--   [Nothing,Nothing,Nothing,Nothing,Just 1,Just 2,Just 3]
--   </pre>
mealyS :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (i -> State s o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool,Int) -&gt; (Int,(Int,Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (mealy clk rst en f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (mealy clk rst en f 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> clk rst en f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> clk rst en f 3 (c,i1)
--   </pre>
mealyB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | A version of <a>mealyS</a> that does automatic <a>Bundle</a>ing, see
--   <a>mealyB</a> for details.
mealySB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (i -> State s o) -> s -> Unbundled dom i -> Unbundled dom o


-- | <h1>Efficient bundling of initial RAM content with the compiled
--   code</h1>
--   
--   Leveraging Template Haskell, the initial content for the block RAM
--   components in this module is stored alongside the compiled Haskell
--   code. It covers use cases where passing the initial content as a
--   <a>Vec</a> turns out to be problematically slow.
--   
--   The data is stored efficiently, with very little overhead (worst-case
--   7%, often no overhead at all).
--   
--   Unlike <a>Clash.Explicit.BlockRam.File</a>,
--   <a>Clash.Explicit.BlockRam.Blob</a> generates practically the same HDL
--   as <a>Clash.Explicit.BlockRam</a> and is compatible with all tools
--   consuming the generated HDL.
module Clash.Explicit.BlockRam.Blob

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamBlob</a> clk en content) rd wrM</tt>.</li>
--   </ul>
blockRamBlob :: forall dom addr m n. (KnownDomain dom, Enum addr, NFDataX addr) => Clock dom -> Enable dom -> MemBlob n m -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamBlobPow2</a> clk en content) rd wrM</tt>.</li>
--   </ul>
blockRamBlobPow2 :: forall dom m n. (KnownDomain dom, KnownNat n) => Clock dom -> Enable dom -> MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]

-- | blockRAMBlob primitive
blockRamBlob# :: forall dom m n. KnownDomain dom => Clock dom -> Enable dom -> MemBlob n m -> Signal dom Int -> Signal dom Bool -> Signal dom Int -> Signal dom (BitVector m) -> Signal dom (BitVector m)


-- | <h1>Efficient bundling of ROM content with the compiled code</h1>
--   
--   Leveraging Template Haskell, the content for the ROM components in
--   this module is stored alongside the compiled Haskell code. It covers
--   use cases where passing the initial content as a <a>Vec</a> turns out
--   to be problematically slow.
--   
--   The data is stored efficiently, with very little overhead (worst-case
--   7%, often no overhead at all).
--   
--   Unlike <a>Clash.Explicit.ROM.File</a>, <a>Clash.Explicit.ROM.Blob</a>
--   generates practically the same HDL as <a>Clash.Explicit.ROM</a> and is
--   compatible with all tools consuming the generated HDL.
module Clash.Explicit.ROM.Blob

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlob :: forall dom addr m n. (KnownDomain dom, Enum addr) => Clock dom -> Enable dom -> MemBlob n m -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlobPow2 :: forall dom m n. (KnownDomain dom, KnownNat n) => Clock dom -> Enable dom -> MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]

-- | ROM primitive
romBlob# :: forall dom m n. KnownDomain dom => Clock dom -> Enable dom -> MemBlob n m -> Signal dom Int -> Signal dom (BitVector m)


-- | Block RAM primitives
--   
--   <h1>Using RAMs </h1>
--   
--   We will show a rather elaborate example on how you can, and why you
--   might want to use block RAMs. We will build a "small" CPU + Memory +
--   Program ROM where we will slowly evolve to using block RAMs. Note that
--   the code is <i>not</i> meant as a de-facto standard on how to do CPU
--   design in Clash.
--   
--   We start with the definition of the Instructions, Register names and
--   machine codes:
--   
--   <pre>
--   {-# LANGUAGE RecordWildCards, TupleSections, DeriveAnyClass #-}
--   
--   module CPU where
--   
--   import Clash.Explicit.Prelude
--   
--   type InstrAddr = Unsigned 8
--   type MemAddr   = Unsigned 5
--   type Value     = Signed 8
--   
--   data Instruction
--     = Compute Operator Reg Reg Reg
--     | Branch Reg Value
--     | Jump Value
--     | Load MemAddr Reg
--     | Store Reg MemAddr
--     | Nop
--     deriving (Eq, Show, Generic, NFDataX)
--   
--   data Reg
--     = Zero
--     | PC
--     | RegA
--     | RegB
--     | RegC
--     | RegD
--     | RegE
--     deriving (Eq, Show, Enum, Generic, NFDataX)
--   
--   data Operator = Add | Sub | Incr | Imm | CmpGt
--     deriving (Eq, Show, Generic, NFDataX)
--   
--   data MachCode
--     = MachCode
--     { inputX  :: Reg
--     , inputY  :: Reg
--     , result  :: Reg
--     , aluCode :: Operator
--     , ldReg   :: Reg
--     , rdAddr  :: MemAddr
--     , wrAddrM :: Maybe MemAddr
--     , jmpM    :: Maybe Value
--     }
--   
--   nullCode =
--     MachCode
--       { inputX = Zero
--       , inputY = Zero
--       , result = Zero
--       , aluCode = Imm
--       , ldReg = Zero
--       , rdAddr = 0
--       , wrAddrM = Nothing
--       , jmpM = Nothing
--       }
--   </pre>
--   
--   Next we define the CPU and its ALU:
--   
--   <pre>
--   cpu
--     :: Vec 7 Value          -- ^ Register bank
--     -&gt; (Value,Instruction)  -- ^ (Memory output, Current instruction)
--     -&gt; ( Vec 7 Value
--        , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--        )
--   cpu regbank (memOut, instr) =
--     (regbank', (rdAddr, (,aluOut) <a>&lt;$&gt;</a> wrAddrM, bitCoerce ipntr))
--    where
--     -- Current instruction pointer
--     ipntr = regbank <a>!!</a> PC
--   
--     -- Decoder
--     (MachCode {..}) = case instr of
--       Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--       Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--       Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--       Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--       Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--       Nop                  -&gt; nullCode
--   
--     -- ALU
--     regX   = regbank <a>!!</a> inputX
--     regY   = regbank <a>!!</a> inputY
--     aluOut = alu aluCode regX regY
--   
--     -- next instruction
--     nextPC =
--       case jmpM of
--         Just a | aluOut /= 0 -&gt; ipntr + a
--         _                    -&gt; ipntr + 1
--   
--     -- update registers
--     regbank' = <a>replace</a> Zero   0
--              $ <a>replace</a> PC     nextPC
--              $ <a>replace</a> result aluOut
--              $ <a>replace</a> ldReg  memOut
--              $ regbank
--   
--   alu Add   x y = x + y
--   alu Sub   x y = x - y
--   alu Incr  x _ = x + 1
--   alu Imm   x _ = x
--   alu CmpGt x y = if x &gt; y then 1 else 0
--   </pre>
--   
--   We initially create a memory out of simple registers:
--   
--   <pre>
--   dataMem
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; Signal dom MemAddr
--     -- ^ Read address
--     -&gt; Signal dom (Maybe (MemAddr,Value))
--     -- ^ (write address, data in)
--     -&gt; Signal dom Value
--     -- ^ data out
--   dataMem clk rst en rd wrM =
--     <a>mealy</a> clk rst en dataMemT (<a>replicate</a> d32 0) (bundle (rd,wrM))
--    where
--     dataMemT mem (rd,wrM) = (mem',dout)
--       where
--         dout = mem <a>!!</a> rd
--         mem' =
--           case wrM of
--             Just (wr,din) -&gt; <a>replace</a> wr din mem
--             _             -&gt; mem
--   </pre>
--   
--   And then connect everything:
--   
--   <pre>
--   system
--     :: ( KnownDomain dom
--        , KnownNat n )
--     =&gt; Vec n Instruction
--     -&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; Signal dom Value
--   system instrs clk rst en = memOut
--    where
--     memOut = dataMem clk rst en rdAddr dout
--     (rdAddr,dout,ipntr) = <a>mealyB</a> clk rst en cpu (<a>replicate</a> d7 0) (memOut,instr)
--     instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Create a simple program that calculates the GCD of 4 and 6:
--   
--   <pre>
--   -- Compute GCD of 4 and 6
--   prog = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   And test our system:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 32 $ system prog systemClockGen resetGen enableGen
--   [0,0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   to see that our system indeed calculates that the GCD of 6 and 4 is 2.
--   
--   <h3>Improvement 1: using <tt>asyncRam</tt></h3>
--   
--   As you can see, it's fairly straightforward to build a memory using
--   registers and read (<a>!!</a>) and write (<a>replace</a>) logic. This
--   might however not result in the most efficient hardware structure,
--   especially when building an ASIC.
--   
--   Instead it is preferable to use the <a>asyncRam</a> function which has
--   the potential to be translated to a more efficient structure:
--   
--   <pre>
--   system2
--     :: ( KnownDomain dom
--        , KnownNat n )
--     =&gt; Vec n Instruction
--     -&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; Signal dom Value
--   system2 instrs clk rst en = memOut
--    where
--     memOut = <a>asyncRam</a> clk clk en d32 rdAddr dout
--     (rdAddr,dout,ipntr) = <a>mealyB</a> clk rst en cpu (<a>replicate</a> d7 0) (memOut,instr)
--     instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Again, we can simulate our system and see that it works. This time
--   however, we need to disregard the first few output samples, because
--   the initial content of an <a>asyncRam</a> is <i>undefined</i>, and
--   consequently, the first few output samples are also <i>undefined</i>.
--   We use the utility function <a>printX</a> to conveniently filter out
--   the undefinedness and replace it with the string <tt>"undefined"</tt>
--   in the first few leading outputs.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 32 $ system2 prog systemClockGen resetGen enableGen
--   [undefined,undefined,undefined,undefined,undefined,undefined,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   <h3>Improvement 2: using <tt>blockRam</tt></h3>
--   
--   Finally we get to using <a>blockRam</a>. On FPGAs, <a>asyncRam</a>
--   will be implemented in terms of LUTs, and therefore take up logic
--   resources. FPGAs also have large(r) memory structures called <i>block
--   RAMs</i>, which are preferred, especially as the memories we need for
--   our application get bigger. The <a>blockRam</a> function will be
--   translated to such a <i>block RAM</i>.
--   
--   One important aspect of block RAMs is that they have a
--   <i>synchronous</i> read port, meaning unlike an <a>asyncRam</a>, the
--   result of a read command given at time <tt>t</tt> is output at time
--   <tt>t + 1</tt>.
--   
--   For us that means we need to change the design of our CPU. Right now,
--   upon a load instruction we generate a read address for the memory, and
--   the value at that read address is immediately available to be put in
--   the register bank. We will be using a block RAM, so the value is
--   delayed until the next cycle. Thus, we will also need to delay the
--   register address to which the memory address is loaded:
--   
--   <pre>
--   cpu2
--     :: (Vec 7 Value,Reg)    -- ^ (Register bank, Load reg addr)
--     -&gt; (Value,Instruction)  -- ^ (Memory output, Current instruction)
--     -&gt; ( (Vec 7 Value, Reg)
--        , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--        )
--   cpu2 (regbank, ldRegD) (memOut, instr) =
--     ((regbank', ldRegD'), (rdAddr, (,aluOut) <a>&lt;$&gt;</a> wrAddrM, bitCoerce ipntr))
--    where
--     -- Current instruction pointer
--     ipntr = regbank <a>!!</a> PC
--   
--     -- Decoder
--     (MachCode {..}) = case instr of
--       Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--       Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--       Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--       Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--       Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--       Nop                  -&gt; nullCode
--   
--     -- ALU
--     regX   = regbank <a>!!</a> inputX
--     regY   = regbank <a>!!</a> inputY
--     aluOut = alu aluCode regX regY
--   
--     -- next instruction
--     nextPC =
--       case jmpM of
--         Just a | aluOut /= 0 -&gt; ipntr + a
--         _                    -&gt; ipntr + 1
--   
--     -- update registers
--     ldRegD'  = ldReg  -- Delay the ldReg by 1 cycle
--     regbank' = <a>replace</a> Zero   0
--              $ <a>replace</a> PC     nextPC
--              $ <a>replace</a> result aluOut
--              $ <a>replace</a> ldRegD memOut
--              $ regbank
--   </pre>
--   
--   We can now finally instantiate our system with a <a>blockRam</a>:
--   
--   <pre>
--   system3
--     :: ( KnownDomain dom
--        , KnownNat n )
--     =&gt; Vec n Instruction
--     -&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; Signal dom Value
--   system3 instrs clk rst en = memOut
--    where
--     memOut = <a>blockRam</a> clk en (replicate d32 0) rdAddr dout
--     (rdAddr,dout,ipntr) = <a>mealyB</a> clk rst en cpu2 ((<a>replicate</a> d7 0),Zero) (memOut,instr)
--     instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   We are, however, not done. We will also need to update our program.
--   The reason being that values that we try to load in our registers
--   won't be loaded into the register until the next cycle. This is a
--   problem when the next instruction immediately depends on this memory
--   value. In our example, this was only the case when we loaded the value
--   <tt>6</tt>, which was stored at address <tt>1</tt>, into
--   <tt>RegB</tt>. Our updated program is thus:
--   
--   <pre>
--   prog2 = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          Nop :&gt; -- Extra NOP
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   When we simulate our system we see that it works. This time again, we
--   need to disregard the first sample, because the initial output of a
--   <a>blockRam</a> is <i>undefined</i>. We use the utility function
--   <a>printX</a> to conveniently filter out the undefinedness and replace
--   it with the string <tt>"undefined"</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 34 $ system3 prog2 systemClockGen resetGen enableGen
--   [undefined,0,0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   This concludes the short introduction to using <a>blockRam</a>.
module Clash.Explicit.BlockRam

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en (<a>blockRam</a>
--   clk inits) rd wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFile</a> and
--   <a>blockRamBlob</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram40
--     :: <a>Clock</a>  dom
--     -&gt; <a>Enable</a>  dom
--     -&gt; <a>Signal</a> dom (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram40 clk en = <a>blockRam</a> clk en (<a>replicate</a> d40 1)
--   </pre>
blockRam :: (KnownDomain dom, HasCallStack, NFDataX a, Enum addr, NFDataX addr) => Clock dom -> Enable dom -> Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamPow2</a> clk inits) rd wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFilePow2</a> and
--   <a>blockRamBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram32
--     :: <a>Clock</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram32 clk en = <a>blockRamPow2</a> clk en (<a>replicate</a> d32 1)
--   </pre>
blockRamPow2 :: (KnownDomain dom, HasCallStack, NFDataX a, KnownNat n) => Clock dom -> Enable dom -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that has no default values set. May be
--   cleared to an arbitrary state using a reset function.
blockRamU :: forall n dom a r addr. (KnownDomain dom, HasCallStack, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => Clock dom -> Reset dom -> Enable dom -> ResetStrategy r -> SNat n -> (Index n -> a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that is initialized with the same value
--   on all memory positions
blockRam1 :: forall n dom a r addr. (KnownDomain dom, HasCallStack, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => Clock dom -> Reset dom -> Enable dom -> ResetStrategy r -> SNat n -> a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a
data ResetStrategy (r :: Bool)
[ClearOnReset] :: ResetStrategy 'True
[NoClearOnReset] :: ResetStrategy 'False

-- | Create a read-after-write block RAM from a read-before-write one
readNew :: (KnownDomain dom, NFDataX a, Eq addr) => Clock dom -> Reset dom -> Enable dom -> (Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Produces vendor-agnostic HDL that will be inferred as a true dual-port
--   block RAM
--   
--   Any value that is being written on a particular port is also the value
--   that will be read on that port, i.e. the same-port read/write behavior
--   is: WriteFirst. For mixed-port read/write, when port A writes to the
--   address port B reads from, the output of port B is undefined, and vice
--   versa.
trueDualPortBlockRam :: forall nAddrs domA domB a. (HasCallStack, KnownNat nAddrs, KnownDomain domA, KnownDomain domB, NFDataX a) => Clock domA -> Clock domB -> Signal domA (RamOp nAddrs a) -> Signal domB (RamOp nAddrs a) -> (Signal domA a, Signal domB a)

-- | Port operation
data RamOp n a

-- | Read from address
RamRead :: Index n -> RamOp n a

-- | Write data to address
RamWrite :: Index n -> a -> RamOp n a

-- | No operation
RamNoOp :: RamOp n a

-- | blockRAM primitive
blockRam# :: forall dom a n. (KnownDomain dom, HasCallStack, NFDataX a) => Clock dom -> Enable dom -> Vec n a -> Signal dom Int -> Signal dom Bool -> Signal dom Int -> Signal dom a -> Signal dom a

-- | blockRAMU primitive
blockRamU# :: forall n dom a. (KnownDomain dom, HasCallStack, NFDataX a) => Clock dom -> Enable dom -> SNat n -> Signal dom Int -> Signal dom Bool -> Signal dom Int -> Signal dom a -> Signal dom a

-- | blockRAM1 primitive
blockRam1# :: forall n dom a. (KnownDomain dom, HasCallStack, NFDataX a) => Clock dom -> Enable dom -> SNat n -> a -> Signal dom Int -> Signal dom Bool -> Signal dom Int -> Signal dom a -> Signal dom a

-- | Primitive for <a>trueDualPortBlockRam</a>
trueDualPortBlockRam# :: forall nAddrs domA domB a. (HasCallStack, KnownNat nAddrs, KnownDomain domA, KnownDomain domB, NFDataX a) => Clock domA -> Signal domA Bool -> Signal domA Bool -> Signal domA (Index nAddrs) -> Signal domA a -> Clock domB -> Signal domB Bool -> Signal domB Bool -> Signal domB (Index nAddrs) -> Signal domB a -> (Signal domA a, Signal domB a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Explicit.BlockRam.RamOp n a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Clash.Explicit.BlockRam.RamOp n a)
instance GHC.Generics.Generic (Clash.Explicit.BlockRam.RamOp n a)


-- | Synchronizer circuits for safe clock domain crossings
module Clash.Explicit.Synchronizer

-- | Synchronizer based on two sequentially connected flip-flops.
--   
--   <ul>
--   <li><b>NB</b>: This synchronizer can be used for
--   <b>bit</b>-synchronization.</li>
--   <li><b>NB</b>: Although this synchronizer does reduce metastability,
--   it does not guarantee the proper synchronization of a whole
--   <b>word</b>. For example, given that the output is sampled twice as
--   fast as the input is running, and we have two samples in the input
--   stream that look like:<pre>[0111,1000]</pre>But the circuit driving
--   the input stream has a longer propagation delay on <b>msb</b> compared
--   to the <b>lsb</b>s. What can happen is an output stream that looks
--   like this:<pre>[0111,0111,0000,1000]</pre>Where the level-change of
--   the <b>msb</b> was not captured, but the level change of the
--   <b>lsb</b>s were.If you want to have <i>safe</i>
--   <b>word</b>-synchronization use <a>asyncFIFOSynchronizer</a>.</li>
--   </ul>
dualFlipFlopSynchronizer :: (NFDataX a, KnownDomain dom1, KnownDomain dom2) => Clock dom1 -> Clock dom2 -> Reset dom2 -> Enable dom2 -> a -> Signal dom1 a -> Signal dom2 a

-- | Synchronizer implemented as a FIFO around a synchronous RAM. Based on
--   the design described in <a>Clash.Tutorial#multiclock</a>, which is
--   itself based on the design described in
--   <a>http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf</a>.
--   However, this FIFO uses a synchronous dual-ported RAM which, unlike
--   those designs using RAM with an asynchronous read port, is nearly
--   guaranteed to actually synthesize into one of the dual-ported RAMs
--   found on most FPGAs.
--   
--   <b>NB</b>: This synchronizer can be used for
--   <b>word</b>-synchronization. <b>NB</b>: This synchronizer will only
--   work safely when you set up the proper bus skew and maximum delay
--   constraints inside your synthesis tool for the clock domain crossings
--   of the gray pointers.
asyncFIFOSynchronizer :: (KnownDomain wdom, KnownDomain rdom, 2 <= addrSize, NFDataX a) => SNat addrSize -> Clock wdom -> Clock rdom -> Reset wdom -> Reset rdom -> Enable wdom -> Enable rdom -> Signal rdom Bool -> Signal wdom (Maybe a) -> (Signal rdom a, Signal rdom Bool, Signal wdom Bool)


-- | Utilities to deal with resets.
module Clash.Explicit.Reset

-- | The resetSynchronizer will synchronize an incoming reset according to
--   whether the domain is synchronous or asynchronous.
--   
--   For asynchronous resets this synchronizer ensures the reset will only
--   be de-asserted synchronously but it can still be asserted
--   asynchronously. The reset assert is immediate, but reset de-assertion
--   is delayed by two cycles.
--   
--   Normally, asynchronous resets can be both asynchronously asserted and
--   de-asserted. Asynchronous de-assertion can induce meta-stability in
--   the component which is being reset. To ensure this doesn't happen,
--   <a>resetSynchronizer</a> ensures that de-assertion of a reset happens
--   synchronously. Assertion of the reset remains asynchronous.
--   
--   Note that asynchronous assertion does not induce meta-stability in the
--   component whose reset is asserted. However, when a component "A" in
--   another clock or reset domain depends on the value of a component "B"
--   being reset, then asynchronous assertion of the reset of component "B"
--   can induce meta-stability in component "A". To prevent this from
--   happening you need to use a proper synchronizer, for example one of
--   the synchronizers in <a>Clash.Explicit.Synchronizer</a>.
--   
--   For synchronous resets this function ensures that the reset is
--   asserted and de-asserted synchronously. Both the assertion and
--   de-assertion of the reset are delayed by two cycles.
--   
--   <h3><b>Example 1</b></h3>
--   
--   The circuit below detects a rising bit (i.e., a transition from 0 to
--   1) in a given argument. It takes a reset that is not synchronized to
--   any of the other incoming signals and synchronizes it using
--   <a>resetSynchronizer</a>.
--   
--   <pre>
--   topEntity
--     :: Clock  System
--     -&gt; Reset  System
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk asyncRst key1 =
--     withClockResetEnable clk rst enableGen leds
--    where
--     rst   = <a>resetSynchronizer</a> clk asyncRst
--     key1R = isRising 1 key1
--     leds  = mealy blinkerT (1, False, 0) key1R
--   </pre>
--   
--   <h3><b>Example 2</b></h3>
--   
--   Similar to <i>Example 1</i> this circuit detects a rising bit (i.e., a
--   transition from 0 to 1) in a given argument. It takes a clock that is
--   not stable yet and a reset signal that is not synchronized to any
--   other signals. It stabilizes the clock and then synchronizes the reset
--   signal.
--   
--   Note that the function <a>altpllSync</a> provides this functionality
--   in a convenient form, obviating the need for
--   <tt>resetSynchronizer</tt> for this use case.
--   
--   <pre>
--   topEntity
--     :: Clock  System
--     -&gt; Reset  System
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk rst key1 =
--       let  (pllOut,pllStable) = unsafeAltpll clk rst
--            rstSync            = <a>resetSynchronizer</a> pllOut (unsafeFromActiveLow pllStable)
--       in   exposeClockResetEnable leds pllOut rstSync enableGen
--     where
--       key1R  = isRising 1 key1
--       leds   = mealy blinkerT (1, False, 0) key1R
--   </pre>
--   
--   <h3><b>Implementation details</b></h3>
--   
--   <a>resetSynchronizer</a> implements the following circuit for
--   asynchronous domains:
--   
--   <pre>
--                                   rst
--   --------------------------------------+
--                       |                 |
--                  +----v----+       +----v----+
--     deasserted   |         |       |         |
--   ---------------&gt;         +-------&gt;         +--------&gt;
--                  |         |       |         |
--              +---|&gt;        |   +---|&gt;        |
--              |   |         |   |   |         |
--              |   +---------+   |   +---------+
--      clk     |                 |
--   -----------------------------+
--   </pre>
--   
--   This corresponds to figure 3d at
--   <a>https://www.embedded.com/asynchronous-reset-synchronization-and-distribution-challenges-and-solutions/</a>
--   
--   For synchronous domains two sequential dflipflops are used:
--   
--   <pre>
--                  +---------+       +---------+
--     rst          |         |       |         |
--   ---------------&gt;         +-------&gt;         +--------&gt;
--                  |         |       |         |
--              +---|&gt;        |   +---|&gt;        |
--              |   |         |   |   |         |
--              |   +---------+   |   +---------+
--      clk     |                 |
--   -----------------------------+
--   </pre>
resetSynchronizer :: forall dom. KnownDomain dom => Clock dom -> Reset dom -> Reset dom

-- | Filter glitches from reset signals by only triggering a reset after it
--   has been asserted for <i>glitchlessPeriod</i> cycles. Similarly, it
--   will stay asserted until a <i>glitchlessPeriod</i> number of
--   deasserted cycles have been observed.
--   
--   This circuit can only be used on platforms supporting initial values.
--   This restriction can be worked around by using
--   <a>unsafeResetGlitchFilter</a> but this is not recommended.
--   
--   On platforms without initial values, you should instead use
--   <a>resetGlitchFilterWithReset</a> with an additional power-on reset,
--   or <a>holdReset</a> if filtering is only needed on deassertion.
--   
--   At power-on, the reset will be asserted. If the filtered reset input
--   remains unasserted, the output reset will deassert after
--   <i>glitchlessPeriod</i> clock cycles.
--   
--   If <tt>resetGlitchFilter</tt> is used in a domain with asynchronous
--   resets (<a>Asynchronous</a>), <tt>resetGlitchFilter</tt> will first
--   synchronize the reset input with <a>dualFlipFlopSynchronizer</a>.
--   
--   <h3><b>Example 1</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let sampleResetN n = sampleN n . unsafeToActiveHigh
--   
--   &gt;&gt;&gt; let resetFromList = unsafeFromActiveHigh . fromList
--   
--   &gt;&gt;&gt; let rst = resetFromList [True, True, False, False, True, False, False, True, True, False, True, True]
--   
--   &gt;&gt;&gt; sampleResetN 12 (resetGlitchFilter d2 (clockGen @XilinxSystem) rst)
--   [True,True,True,True,False,False,False,False,False,True,True,True]
--   </pre>
resetGlitchFilter :: forall dom glitchlessPeriod. (HasCallStack, HasDefinedInitialValues dom, 1 <= glitchlessPeriod) => SNat glitchlessPeriod -> Clock dom -> Reset dom -> Reset dom

-- | Filter glitches from reset signals by only triggering a reset after it
--   has been asserted for <i>glitchlessPeriod</i> cycles. Similarly, it
--   will stay asserted until a <i>glitchlessPeriod</i> number of
--   deasserted cycles have been observed.
--   
--   Compared to <a>resetGlitchFilter</a>, this function adds an additional
--   power-on reset input. As soon as the power-on reset asserts, the reset
--   output will assert, and after the power-on reset deasserts, the reset
--   output will stay asserted for another <i>glitchlessPeriod</i> clock
--   cycles. This is identical behavior to <a>holdReset</a> where it
--   concerns the power-on reset, and differs from the filtered reset,
--   which will only cause an assertion after <i>glitchlessPeriod</i>
--   cycles.
--   
--   If <tt>resetGlitchFilterWithReset</tt> is used in a domain with
--   asynchronous resets (<a>Asynchronous</a>),
--   <tt>resetGlitchFilterWithReset</tt> will first synchronize the reset
--   input with <a>dualFlipFlopSynchronizer</a>.
resetGlitchFilterWithReset :: forall dom glitchlessPeriod. (HasCallStack, KnownDomain dom, 1 <= glitchlessPeriod) => SNat glitchlessPeriod -> Clock dom -> Reset dom -> Reset dom -> Reset dom

-- | Filter glitches from reset signals by only triggering a reset after it
--   has been asserted for <i>glitchlessPeriod</i> cycles. Similarly, it
--   will stay asserted until a <i>glitchlessPeriod</i> number of
--   deasserted cycles have been observed.
--   
--   On platforms without initial values (<a>Unknown</a>),
--   <a>resetGlitchFilter</a> cannot be used and you should use
--   <a>resetGlitchFilterWithReset</a> with an additional power-on reset,
--   or <a>holdReset</a> if filtering is only needed on deassertion.
--   
--   <tt>unsafeResetGlitchFilter</tt> allows breaking the requirement of
--   initial values, but by doing so it is possible that the design starts
--   up with a period of up to <i>2 * glitchlessPeriod</i> clock cycles
--   where the reset output is unasserted (or longer in the case of
--   glitches on the filtered reset input). This can cause a number of
--   problems. The outputs/tri-states of the design might output random
--   things, including coherent but incorrect streams of data. This might
--   have grave repercussions in the design's environment (sending network
--   packets, overwriting non-volatile memory, in extreme cases destroying
--   controlled equipment or causing harm to living beings, ...).
--   
--   Without initial values, the synthesized result of
--   <tt>unsafeResetGlitchFilter</tt> eventually correctly outputs a
--   filtered version of the reset input. However, in simulation, it will
--   indefinitely output an undefined value. This happens both in Clash
--   simulation and in HDL simulation. Therefore, simulation should not
--   include the <tt>unsafeResetGlitchFilter</tt>.
--   
--   If <tt>unsafeResetGlitchFilter</tt> is used in a domain with
--   asynchronous resets (<a>Asynchronous</a>),
--   <tt>unsafeResetGlitchFilter</tt> will first synchronize the reset
--   input with <a>dualFlipFlopSynchronizer</a>.
unsafeResetGlitchFilter :: forall dom glitchlessPeriod. (HasCallStack, KnownDomain dom, 1 <= glitchlessPeriod) => SNat glitchlessPeriod -> Clock dom -> Reset dom -> Reset dom

-- | Hold reset for a number of cycles relative to an incoming reset
--   signal.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; let sampleWithReset = sampleN 8 . unsafeToActiveHigh
--   
--   &gt;&gt;&gt; sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (resetGenN (SNat @3)))
--   [True,True,True,True,True,False,False,False]
--   </pre>
--   
--   <a>holdReset</a> holds the reset for an additional 2 clock cycles for
--   a total of 5 clock cycles where the reset is asserted.
--   <a>holdReset</a> also works on intermediate assertions of the reset
--   signal:
--   
--   <pre>
--   &gt;&gt;&gt; let rst = fromList [True, False, False, False, True, False, False, False]
--   
--   &gt;&gt;&gt; sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (unsafeFromActiveHigh rst))
--   [True,True,True,False,True,True,True,False]
--   </pre>
holdReset :: forall dom n. KnownDomain dom => Clock dom -> Enable dom -> SNat n -> Reset dom -> Reset dom

-- | Convert between different types of reset, adding a synchronizer when
--   the domains are not the same. See <a>resetSynchronizer</a> for further
--   details about reset synchronization.
--   
--   If <tt>domA</tt> has <a>Synchronous</a> resets, a flip-flop is
--   inserted in <tt>domA</tt> to filter glitches. This adds one
--   <tt>domA</tt> clock cycle delay.
convertReset :: forall domA domB. (KnownDomain domA, KnownDomain domB) => Clock domA -> Clock domB -> Reset domA -> Reset domB

-- | A reset that is never asserted
noReset :: KnownDomain dom => Reset dom

-- | Output reset will be asserted when both input resets are asserted
andReset :: forall dom. HasSynchronousReset dom => Reset dom -> Reset dom -> Reset dom

-- | Output reset will be asserted when both input resets are asserted.
--   This function is considered unsafe because it can be used on domains
--   with components with asynchronous resets, where use of this function
--   can introduce glitches triggering a reset.
unsafeAndReset :: forall dom. KnownDomain dom => Reset dom -> Reset dom -> Reset dom

-- | Output reset will be asserted when either one of the input resets is
--   asserted
orReset :: forall dom. HasSynchronousReset dom => Reset dom -> Reset dom -> Reset dom

-- | Output reset will be asserted when either one of the input resets is
--   asserted. This function is considered unsafe because it can be used on
--   domains with components with asynchronous resets, where use of this
--   function can introduce glitches triggering a reset.
unsafeOrReset :: forall dom. KnownDomain dom => Reset dom -> Reset dom -> Reset dom

-- | A reset signal belonging to a domain called <i>dom</i>.
--   
--   The underlying representation of resets is <a>Bool</a>.
data Reset (dom :: Domain)

-- | Reset generator for simulation purposes. Asserts the reset for a
--   single cycle.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem = resetGen @System
--   </pre>
--   
--   See <a>tbClockGen</a> for example usage.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGen :: forall dom. KnownDomain dom => Reset dom

-- | Reset generator for simulation purposes. Asserts the reset for the
--   first <i>n</i> cycles.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem5 = resetGen @System d5
--   </pre>
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (unsafeToActiveHigh (resetGenN @System d3))
--   [True,True,True,False,False,False,False]
--   </pre>
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGenN :: forall dom n. (KnownDomain dom, 1 <= n) => SNat n -> Reset dom

-- | Get <a>ResetKind</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetKind @dom of
--       SAsynchronous -&gt; foo
--       SSynchronous -&gt; bar
--   </pre>
resetKind :: forall dom sync. (KnownDomain dom, DomainResetKind dom ~ sync) => SResetKind sync

-- | Reset generator for use in simulation, for the <a>System</a> clock
--   domain. Asserts the reset for a single cycle.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = <a>systemResetGen</a>
--   </pre>
systemResetGen :: Reset System

-- | <a>unsafeToReset</a> is unsafe. For asynchronous resets it is unsafe
--   because it can introduce combinatorial loops. In case of synchronous
--   resets it can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeFromActiveLow</a> or
--   <a>unsafeFromActiveHigh</a>.
unsafeToReset :: KnownDomain dom => Signal dom Bool -> Reset dom

-- | <a>unsafeFromReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeToActiveLow</a> or
--   <a>unsafeToActiveHigh</a>.
unsafeFromReset :: Reset dom -> Signal dom Bool

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveHigh :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveLow :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveHigh :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveLow :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromHighPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromLowPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToHighPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToLowPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool


-- | Generic clock related utilities.
module Clash.Clocks

-- | <b>NB</b>: The documentation only shows instances up to <i>3</i>
--   output clocks. By default, instances up to and including <i>18</i>
--   clocks will exist.
class Clocks t where {
    type family ClocksCxt t :: Constraint;
    type family NumOutClocks t :: Nat;
}
clocks :: (Clocks t, KnownDomain domIn, ClocksCxt t) => Clock domIn -> Reset domIn -> t

-- | <b>NB</b>: The documentation only shows instances up to <i>3</i>
--   output clocks. By default, instances up to and including <i>18</i>
--   clocks will exist.
class ClocksSync t where {
    type family ClocksSyncClocksInst t (domIn :: Domain) :: Type;
    type family ClocksResetSynchronizerCxt t :: Constraint;
}
clocksResetSynchronizer :: (ClocksSync t, KnownDomain domIn, ClocksResetSynchronizerCxt t) => ClocksSyncClocksInst t domIn -> Clock domIn -> t
type ClocksSyncCxt t (domIn :: Domain) = (KnownDomain domIn, ClocksSync t, ClocksResetSynchronizerCxt t, Clocks (ClocksSyncClocksInst t domIn), ClocksCxt (ClocksSyncClocksInst t domIn))
type NumOutClocksSync t (domIn :: Domain) = NumOutClocks (ClocksSyncClocksInst t domIn)
instance Clash.Clocks.Internal.ClocksSync (Clash.Signal.Internal.Clock c1, Clash.Signal.Internal.Reset c1)
instance Clash.Clocks.Internal.ClocksSync (Clash.Signal.Internal.Clock c1, Clash.Signal.Internal.Reset c1, Clash.Signal.Internal.Clock c2, Clash.Signal.Internal.Reset c2)
instance Clash.Clocks.Internal.ClocksSync (Clash.Signal.Internal.Clock c1, Clash.Signal.Internal.Reset c1, Clash.Signal.Internal.Clock c2, Clash.Signal.Internal.Reset c2, Clash.Signal.Internal.Clock c3, Clash.Signal.Internal.Reset c3)
instance Clash.Clocks.Internal.Clocks (Clash.Signal.Internal.Clock c1, Clash.Signal.Internal.Signal pllLock GHC.Types.Bool)
instance Clash.Clocks.Internal.Clocks (Clash.Signal.Internal.Clock c1, Clash.Signal.Internal.Clock c2, Clash.Signal.Internal.Signal pllLock GHC.Types.Bool)
instance Clash.Clocks.Internal.Clocks (Clash.Signal.Internal.Clock c1, Clash.Signal.Internal.Clock c2, Clash.Signal.Internal.Clock c3, Clash.Signal.Internal.Signal pllLock GHC.Types.Bool)


-- | This module contains functions for instantiating clock generators on
--   Xilinx FPGA's.
--   
--   We suggest you use a clock generator even if your oscillator runs at
--   the frequency you want to run your circuit at.
--   
--   A clock generator generates a stable clock signal for your design at a
--   configurable frequency. A clock generator in an FPGA is frequently
--   referred to as a PLL (Phase-Locked Loop). However, Xilinx
--   differentiates between several types of clock generator
--   implementations in their FPGAs and uses the term PLL to refer to one
--   specific type, so we choose to use the more generic term <i>clock</i>
--   <i>generator</i> here.
--   
--   For most use cases, you would create two or more synthesis domains
--   describing the oscillator input and the domains you wish to use in
--   your design, and use the <a>regular functions</a> below to generate
--   the clocks and resets of the design from the oscillator input. There
--   are use cases not covered by this simpler approach, and the <a>unsafe
--   functions</a> are provided as a means to build advanced reset managers
--   for the output domains.
module Clash.Xilinx.ClockGen

-- | Instantiate a Xilinx MMCM clock generator corresponding to the Xilinx
--   "Clock Wizard" with 1 single-ended reference clock input and a reset
--   input, and 1 to 7 output clocks and a <tt>locked</tt> output.
--   
--   This function incorporates <a>resetSynchronizer</a>s to convert the
--   <tt>locked</tt> output port into proper <a>Reset</a> signals for the
--   output domains which will keep the circuit in reset while the clock is
--   still stabilizing.
clockWizard :: forall t domIn. (HasAsynchronousReset domIn, ClocksSyncCxt t domIn, NumOutClocksSync t domIn <= 7) => Clock domIn -> Reset domIn -> t

-- | Instantiate a Xilinx MMCM clock generator corresponding to the Xilinx
--   "Clock Wizard" with 1 differential reference clock input and a reset
--   input, and 1 to 7 output clocks and a <tt>locked</tt> output.
--   
--   This function incorporates <a>resetSynchronizer</a>s to convert the
--   <tt>locked</tt> output port into proper <a>Reset</a> signals for the
--   output domains which will keep the circuit in reset while the clock is
--   still stabilizing.
--   
--   To create a differential clock in a test bench, you can use
--   <a>clockToDiffClock</a>.
clockWizardDifferential :: forall t domIn. (HasAsynchronousReset domIn, ClocksSyncCxt t domIn, NumOutClocksSync t domIn <= 7) => DiffClock domIn -> Reset domIn -> t

-- | Instantiate a Xilinx MMCM clock generator corresponding to the Xilinx
--   "Clock Wizard" with 1 single-ended reference clock input and a reset
--   input, and 1 to 7 output clocks and a <tt>locked</tt> output.
--   
--   <b>NB</b>: Because the clock generator reacts asynchronously to the
--   incoming reset input, the signal <b>must</b> be glitch-free.
unsafeClockWizard :: forall t domIn. (KnownDomain domIn, Clocks t, ClocksCxt t, NumOutClocks t <= 7) => Clock domIn -> Reset domIn -> t

-- | Instantiate a Xilinx MMCM clock generator corresponding to the Xilinx
--   "Clock Wizard" with 1 differential reference clock input and a reset
--   input, and 1 to 7 output clocks and a <tt>locked</tt> output.
--   
--   <b>NB</b>: Because the clock generator reacts asynchronously to the
--   incoming reset input, the signal <b>must</b> be glitch-free.
--   
--   To create a differential clock in a test bench, you can use
--   <a>clockToDiffClock</a>.
unsafeClockWizardDifferential :: forall t domIn. (KnownDomain domIn, Clocks t, ClocksCxt t, NumOutClocks t <= 7) => DiffClock domIn -> Reset domIn -> t


-- | This module contains functions for instantiating clock generators on
--   Intel FPGA's.
--   
--   We suggest you use a clock generator even if your oscillator runs at
--   the frequency you want to run your circuit at.
--   
--   A clock generator generates a stable clock signal for your design at a
--   configurable frequency. A clock generator in an FPGA is frequently
--   referred to as a PLL (Phase-Locked Loop). Intel also refers to them as
--   PLL's in general but because this is not consistently the case among
--   FPGA vendors, we choose the more generic term <i>clock generator</i>.
--   
--   For most use cases, you would create two or more synthesis domains
--   describing the oscillator input and the domains you wish to use in
--   your design, and use the <a>regular functions</a> below to generate
--   the clocks and resets of the design from the oscillator input. There
--   are use cases not covered by this simpler approach, and the <a>unsafe
--   functions</a> are provided as a means to build advanced reset managers
--   for the output domains.
module Clash.Intel.ClockGen

-- | Instantiate an Intel clock generator corresponding to the
--   Intel/Quartus "ALTPLL" IP core (Arria GX, Arria II, Stratix IV,
--   Stratix III, Stratix II, Stratix, Cyclone 10 LP, Cyclone IV, Cyclone
--   III, Cyclone II, Cyclone) with 1 reference clock input and a reset
--   input and 1 to 5 output clocks and a <tt>locked</tt> output.
--   
--   This function incorporates <a>resetSynchronizer</a>s to convert the
--   <tt>locked</tt> output port into proper <a>Reset</a> signals for the
--   output domains which will keep the circuit in reset while the clock is
--   still stabilizing.
--   
--   See also the <a>ALTPLL (Phase-Locked Loop) IP Core User Guide</a>
altpllSync :: forall t domIn. (HasAsynchronousReset domIn, ClocksSyncCxt t domIn, NumOutClocksSync t domIn <= 5) => Clock domIn -> Reset domIn -> t

-- | Instantiate an Intel clock generator corresponding to the
--   Intel/Quartus "Altera PLL" IP core (Arria V, Stratix V, Cyclone V)
--   with 1 reference clock input and a reset input and 1 to 18 output
--   clocks and a <tt>locked</tt> output.
--   
--   This function incorporates <a>resetSynchronizer</a>s to convert the
--   <tt>locked</tt> output port into proper <a>Reset</a> signals for the
--   output domains which will keep the circuit in reset while the clock is
--   still stabilizing.
--   
--   See also the <a>Altera Phase-Locked Loop (Altera PLL) IP Core User
--   Guide</a>
alteraPllSync :: forall t domIn. (HasAsynchronousReset domIn, ClocksSyncCxt t domIn, NumOutClocksSync t domIn <= 18) => Clock domIn -> Reset domIn -> t

-- | Instantiate an Intel clock generator corresponding to the
--   Intel/Quartus "ALTPLL" IP core (Arria GX, Arria II, Stratix IV,
--   Stratix III, Stratix II, Stratix, Cyclone 10 LP, Cyclone IV, Cyclone
--   III, Cyclone II, Cyclone) with 1 reference clock input and a reset
--   input and 1 to 5 output clocks and a <tt>locked</tt> output.
--   
--   <b>NB</b>: Because the clock generator reacts asynchronously to the
--   incoming reset input, the signal <b>must</b> be glitch-free.
--   
--   See also the <a>ALTPLL (Phase-Locked Loop) IP Core User Guide</a>
unsafeAltpll :: forall t domIn. (KnownDomain domIn, Clocks t, ClocksCxt t, NumOutClocks t <= 5) => Clock domIn -> Reset domIn -> t

-- | Instantiate an Intel clock generator corresponding to the
--   Intel/Quartus "Altera PLL" IP core (Arria V, Stratix V, Cyclone V)
--   with 1 reference clock input and a reset input and 1 to 18 output
--   clocks and a <tt>locked</tt> output.
--   
--   <b>NB</b>: Because the clock generator reacts asynchronously to the
--   incoming reset input, the signal <b>must</b> be glitch-free.
--   
--   See also the <a>Altera Phase-Locked Loop (Altera PLL) IP Core User
--   Guide</a>
unsafeAlteraPll :: forall t domIn. (KnownDomain domIn, Clocks t, ClocksCxt t, NumOutClocks t <= 18) => Clock domIn -> Reset domIn -> t

-- | Instantiate an Intel clock generator corresponding to the
--   Intel/Quartus "ALTPLL" IP core (Arria GX, Arria II, Stratix IV,
--   Stratix III, Stratix II, Stratix, Cyclone 10 LP, Cyclone IV, Cyclone
--   III, Cyclone II, Cyclone) with 1 reference clock input and a reset
--   input and 1 output clock and a <tt>locked</tt> output.
--   
--   This function is deprecated because the <tt>locked</tt> output is an
--   asynchronous signal. This means the user is required to add a
--   synchronizer and as such this function is unsafe. The common use case
--   is now covered by <a>altpllSync</a> and <a>unsafeAltpll</a> offers the
--   functionality of this deprecated function for advanced use cases.

-- | <i>Deprecated: This function is unsafe. Please see documentation of
--   the function for alternatives.</i>
altpll :: forall domOut domIn name. (HasAsynchronousReset domIn, KnownDomain domOut) => SSymbol name -> Clock domIn -> Reset domIn -> (Clock domOut, Signal domOut Bool)

-- | Instantiate an Intel clock generator corresponding to the
--   Intel/Quartus "Altera PLL" IP core (Arria V, Stratix V, Cyclone V)
--   with 1 reference clock input and a reset input and 1 to 18 output
--   clocks and a <tt>locked</tt> output.
--   
--   This function is deprecated because the <tt>locked</tt> output is an
--   asynchronous signal. This means the user is required to add a
--   synchronizer and as such this function is unsafe. The common use case
--   is now covered by <a>alteraPllSync</a> and <a>unsafeAlteraPll</a>
--   offers the functionality of this deprecated function for advanced use
--   cases.

-- | <i>Deprecated: This function is unsafe. Please see documentation of
--   the function for alternatives.</i>
alteraPll :: forall t domIn name. (HasAsynchronousReset domIn, Clocks t, ClocksCxt t, NumOutClocks t <= 18) => SSymbol name -> Clock domIn -> Reset domIn -> t


-- | Clash has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (dom :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>dom</i> is the <i>clock-</i>
--   (and <i>reset-</i>) domain to which the memory elements manipulating
--   these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>dom</i>, is of the kind <a>Domain</a> - a
--   simple string. That string refers to a single <i>synthesis domain</i>.
--   A synthesis domain describes the behavior of certain aspects of memory
--   elements in it. More specifically, a domain looks like:
--   
--   <pre>
--   <a>DomainConfiguration</a>
--     { _name :: <a>Domain</a>
--     -- ^ Domain name
--     , _period :: <a>Nat</a>
--     -- ^ Clock period in /ps/
--     , _activeEdge :: <a>ActiveEdge</a>
--     -- ^ Active edge of the clock
--     , _resetKind :: <a>ResetKind</a>
--     -- ^ Whether resets are synchronous (edge-sensitive) or asynchronous (level-sensitive)
--     , _initBehavior :: <a>InitBehavior</a>
--     -- ^ Whether the initial (or "power up") value of memory elements is
--     -- unknown/undefined, or configurable to a specific value
--     , _resetPolarity :: ResetPolarity
--     -- ^ Whether resets are active high or active low
--     }
--   </pre>
--   
--   Check the documentation of each of the types to see the various
--   options Clash provides. In order to specify a domain, an instance of
--   <a>KnownDomain</a> should be made. Clash provides an implementation
--   <a>System</a> with some common options chosen:
--   
--   <pre>
--   instance KnownDomain <a>System</a> where
--     type KnownConf <a>System</a> = 'DomainConfiguration <a>System</a> 10000 'Rising 'Asynchronous 'Defined 'ActiveHigh
--     knownDomain = SDomainConfiguration SSymbol SNat SRising SAsynchronous SDefined SActiveHigh
--   </pre>
--   
--   In words, "System" is a synthesis domain with a clock running with a
--   period of 10000 <i>ps</i>. Memory elements respond to the rising edge
--   of the clock, asynchronously to changes in their resets, and have
--   defined power up values if applicable.
--   
--   In order to create a new domain, you don't have to instantiate it
--   explicitly. Instead, you can have <a>createDomain</a> create a domain
--   for you. You can also use the same function to subclass existing
--   domains.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   <li><b>NB</b>: Whether <a>System</a> has good defaults depends on your
--   target platform. Check out <a>IntelSystem</a> and <a>XilinxSystem</a>
--   too!</li>
--   </ul>
module Clash.Signal

-- | Clash has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (dom :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>dom</i> is the <i>clock-</i>
--   (and <i>reset-</i>) domain to which the memory elements manipulating
--   these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>dom</i>, is of the kind <a>Domain</a> - a
--   simple string. That string refers to a single <i>synthesis domain</i>.
--   A synthesis domain describes the behavior of certain aspects of memory
--   elements in it.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   <li><b>NB</b>: For the best compatibility make sure your period is
--   divisible by 2, because some VHDL simulators don't support fractions
--   of picoseconds.</li>
--   <li><b>NB</b>: Whether <a>System</a> has good defaults depends on your
--   target platform. Check out <a>IntelSystem</a> and <a>XilinxSystem</a>
--   too!</li>
--   </ul>
--   
--   Signals have the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Signal
--   type role Signal nominal representational
--   ...
--   </pre>
--   
--   as it is safe to coerce the underlying value of a signal, but not safe
--   to coerce a signal between different synthesis domains.
--   
--   See the module documentation of <a>Clash.Signal</a> for more
--   information about domains.
data Signal (dom :: Domain) a

-- | The <i>in</i> part of an <b>inout</b> port. BiSignalIn has the <a>type
--   role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalIn
--   type role BiSignalIn nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalIn (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | The <i>out</i> part of an <b>inout</b> port
--   
--   Wraps (multiple) writing signals. The semantics are such that only one
--   of the signals may write at a single time step.
--   
--   BiSignalOut has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalOut
--   type role BiSignalOut nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalOut (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | Used to specify the <i>default</i> behavior of a "BiSignal" in Haskell
--   simulation, i.e. what value is read when no value is being written to
--   it.
data BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-up resistor
PullUp :: BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-down resistor
PullDown :: BiSignalDefault

-- | <b>inout</b> port behaves as if is <i>floating</i>. Reading a
--   <i>floating</i> "BiSignal" value in simulation will yield an errorX
--   (undefined value).
Floating :: BiSignalDefault
type Domain = Symbol

-- | We either get evidence that this function was instantiated with the
--   same domains, or Nothing.
sameDomain :: forall (domA :: Domain) (domB :: Domain). (KnownDomain domA, KnownDomain domB) => Maybe (domA :~: domB)

-- | A <a>KnownDomain</a> constraint indicates that a circuit's behavior
--   depends on some properties of a domain. See <a>DomainConfiguration</a>
--   for more information.
class (KnownSymbol dom, KnownNat (DomainPeriod dom)) => KnownDomain (dom :: Domain) where {
    type family KnownConf dom :: DomainConfiguration;
}

-- | Returns <a>SDomainConfiguration</a> corresponding to an instance's
--   <a>DomainConfiguration</a>.
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; knownDomain @System
--   SDomainConfiguration {sName = SSymbol @"System", sPeriod = SNat @10000, sActiveEdge = SRising, sResetKind = SAsynchronous, sInitBehavior = SDefined, sResetPolarity = SActiveHigh}
--   </pre>
knownDomain :: KnownDomain dom => SDomainConfiguration dom (KnownConf dom)
type KnownConfiguration dom conf = (KnownDomain dom, KnownConf dom ~ conf)

-- | Determines clock edge memory elements are sensitive to. Not yet
--   implemented.
data ActiveEdge

-- | Elements are sensitive to the rising edge (low-to-high) of the clock.
Rising :: ActiveEdge

-- | Elements are sensitive to the falling edge (high-to-low) of the clock.
Falling :: ActiveEdge

-- | Singleton version of <a>ActiveEdge</a>
data SActiveEdge (edge :: ActiveEdge)
[SRising] :: SActiveEdge 'Rising
[SFalling] :: SActiveEdge 'Falling
data InitBehavior

-- | Power up value of memory elements is <i>unknown</i>.
Unknown :: InitBehavior

-- | If applicable, power up value of a memory element is defined. Applies
--   to <a>register</a>s for example, but not to <a>blockRam</a>.
Defined :: InitBehavior
data SInitBehavior (init :: InitBehavior)
[SUnknown] :: SInitBehavior 'Unknown
[SDefined] :: SInitBehavior 'Defined
data ResetKind

-- | Elements respond <i>asynchronously</i> to changes in their reset
--   input. This means that they do <i>not</i> wait for the next active
--   clock edge, but respond immediately instead. Common on Intel FPGA
--   platforms.
Asynchronous :: ResetKind

-- | Elements respond <i>synchronously</i> to changes in their reset input.
--   This means that changes in their reset input won't take effect until
--   the next active clock edge. Common on Xilinx FPGA platforms.
Synchronous :: ResetKind

-- | Singleton version of <a>ResetKind</a>
data SResetKind (resetKind :: ResetKind)
[SAsynchronous] :: SResetKind 'Asynchronous
[SSynchronous] :: SResetKind 'Synchronous

-- | Determines the value for which a reset line is considered "active"
data ResetPolarity

-- | Reset is considered active if underlying signal is <a>True</a>.
ActiveHigh :: ResetPolarity

-- | Reset is considered active if underlying signal is <a>False</a>.
ActiveLow :: ResetPolarity

-- | Singleton version of <a>ResetPolarity</a>
data SResetPolarity (polarity :: ResetPolarity)
[SActiveHigh] :: SResetPolarity 'ActiveHigh
[SActiveLow] :: SResetPolarity 'ActiveLow

-- | A domain with a name (<tt>Domain</tt>). Configures the behavior of
--   various aspects of a circuits. See the documentation of this record's
--   field types for more information on the options.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
data DomainConfiguration
DomainConfiguration :: Domain -> Nat -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> DomainConfiguration

-- | Domain name
[_name] :: DomainConfiguration -> Domain

-- | Period of clock in <i>ps</i>
[_period] :: DomainConfiguration -> Nat

-- | Active edge of the clock
[_activeEdge] :: DomainConfiguration -> ActiveEdge

-- | Whether resets are synchronous (edge-sensitive) or asynchronous
--   (level-sensitive)
[_resetKind] :: DomainConfiguration -> ResetKind

-- | Whether the initial (or "power up") value of memory elements is
--   unknown/undefined, or configurable to a specific value
[_initBehavior] :: DomainConfiguration -> InitBehavior

-- | Whether resets are active high or active low
[_resetPolarity] :: DomainConfiguration -> ResetPolarity

-- | Singleton version of <a>DomainConfiguration</a>
data SDomainConfiguration (dom :: Domain) (conf :: DomainConfiguration)
[SDomainConfiguration] :: {sName :: SSymbol dom " Domain name", sPeriod :: SNat period " Period of clock in /ps/", sActiveEdge :: SActiveEdge edge " Active edge of the clock (not yet implemented)", sResetKind :: SResetKind reset " Whether resets are synchronous (edge-sensitive) or asynchronous (level-sensitive)", sInitBehavior :: SInitBehavior init " Whether the initial (or "power up") value of memory elements is unknown/undefined, or configurable to a specific value", sResetPolarity :: SResetPolarity polarity " Whether resets are active high or active low"} -> SDomainConfiguration dom ('DomainConfiguration dom period edge reset init polarity)

-- | Convenience type to help to extract a period from a domain. Example
--   usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainPeriod dom ~ 6000) =&gt; ...
--   </pre>
type DomainPeriod (dom :: Domain) = DomainConfigurationPeriod (KnownConf dom)

-- | Convenience type to help to extract the active edge from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainActiveEdge dom ~ 'Rising) =&gt; ...
--   </pre>
type DomainActiveEdge (dom :: Domain) = DomainConfigurationActiveEdge (KnownConf dom)

-- | Convenience type to help to extract the reset synchronicity from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetKind dom ~ 'Synchronous) =&gt; ...
--   </pre>
type DomainResetKind (dom :: Domain) = DomainConfigurationResetKind (KnownConf dom)

-- | Convenience type to help to extract the initial value behavior from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainInitBehavior dom ~ 'Defined) =&gt; ...
--   </pre>
type DomainInitBehavior (dom :: Domain) = DomainConfigurationInitBehavior (KnownConf dom)

-- | Convenience type to help to extract the reset polarity from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetPolarity dom ~ 'ActiveHigh) =&gt; ...
--   </pre>
type DomainResetPolarity (dom :: Domain) = DomainConfigurationResetPolarity (KnownConf dom)

-- | Convenience type to constrain a domain to have synchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasSynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasSynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Synchronous)

-- | Convenience type to constrain a domain to have asynchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasAsynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasAsynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Asynchronous)

-- | Convenience type to constrain a domain to have initial values. Example
--   usage:
--   
--   <pre>
--   myFunc :: HasDefinedInitialValues dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   Note that there is no <tt>UnknownInitialValues dom</tt> as a component
--   that works without initial values will also work if it does have them.
--   
--   <a>Click here for usage hints</a>
type HasDefinedInitialValues (dom :: Domain) = (KnownDomain dom, DomainInitBehavior dom ~ 'Defined)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type System = ("System" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and synchronously to
--   changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type XilinxSystem = ("XilinxSystem" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type IntelSystem = ("IntelSystem" :: Domain)

-- | Convenience value to allow easy "subclassing" of System domain. Should
--   be used in combination with <a>createDomain</a>. For example, if you
--   just want to change the period but leave all other settings intact
--   use:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
vSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of IntelSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vIntelSystem{vName="Intel10", vPeriod=10}
--   </pre>
vIntelSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of XilinxSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vXilinxSystem{vName="Xilinx10", vPeriod=10}
--   </pre>
vXilinxSystem :: VDomainConfiguration

-- | Same as SDomainConfiguration but allows for easy updates through
--   record update syntax. Should be used in combination with
--   <a>vDomain</a> and <a>createDomain</a>. Example:
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
data VDomainConfiguration
VDomainConfiguration :: String -> Natural -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> VDomainConfiguration

-- | Corresponds to <a>_name</a> on <a>DomainConfiguration</a>
[vName] :: VDomainConfiguration -> String

-- | Corresponds to <a>_period</a> on <a>DomainConfiguration</a>
[vPeriod] :: VDomainConfiguration -> Natural

-- | Corresponds to <a>_activeEdge</a> on <a>DomainConfiguration</a>
[vActiveEdge] :: VDomainConfiguration -> ActiveEdge

-- | Corresponds to <a>_resetKind</a> on <a>DomainConfiguration</a>
[vResetKind] :: VDomainConfiguration -> ResetKind

-- | Corresponds to <a>_initBehavior</a> on <a>DomainConfiguration</a>
[vInitBehavior] :: VDomainConfiguration -> InitBehavior

-- | Corresponds to <a>_resetPolarity</a> on <a>DomainConfiguration</a>
[vResetPolarity] :: VDomainConfiguration -> ResetPolarity

-- | Convert <a>SDomainConfiguration</a> to <a>VDomainConfiguration</a>.
--   Should be used in combination with <a>createDomain</a> only.
vDomain :: SDomainConfiguration dom conf -> VDomainConfiguration

-- | Convenience method to express new domains in terms of others.
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
--   
--   The function will create two extra identifiers. The first:
--   
--   <pre>
--   type System10 = ..
--   </pre>
--   
--   You can use that as the dom to Clocks/Resets/Enables/Signals. For
--   example: <tt>Signal System10 Int</tt>. Additionally, it will create a
--   <a>VDomainConfiguration</a> that you can use in later calls to
--   <a>createDomain</a>:
--   
--   <pre>
--   vSystem10 = knownVDomain @System10
--   </pre>
--   
--   It will also make <tt>System10</tt> an instance of <a>KnownDomain</a>.
--   
--   If either identifier is already in scope it will not be generated a
--   second time. Note: This can be useful for example when documenting a
--   new domain:
--   
--   <pre>
--   -- | Here is some documentation for CustomDomain
--   type CustomDomain = ("CustomDomain" :: Domain)
--   
--   -- | Here is some documentation for vCustomDomain
--   createDomain vSystem{vName="CustomDomain"}
--   </pre>
createDomain :: VDomainConfiguration -> Q [Dec]

-- | Like 'knownDomain but yields a <a>VDomainConfiguration</a>. Should
--   only be used in combination with <a>createDomain</a>.
knownVDomain :: forall dom. KnownDomain dom => VDomainConfiguration

-- | Get the clock period from a KnownDomain context
clockPeriod :: forall dom period. (KnownDomain dom, DomainPeriod dom ~ period) => SNat period

-- | Get <a>ActiveEdge</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case activeEdge @dom of
--       SRising -&gt; foo
--       SFalling -&gt; bar
--   </pre>
activeEdge :: forall dom edge. (KnownDomain dom, DomainActiveEdge dom ~ edge) => SActiveEdge edge

-- | Get <a>ResetKind</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetKind @dom of
--       SAsynchronous -&gt; foo
--       SSynchronous -&gt; bar
--   </pre>
resetKind :: forall dom sync. (KnownDomain dom, DomainResetKind dom ~ sync) => SResetKind sync

-- | Get <a>InitBehavior</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case initBehavior @dom of
--       SDefined -&gt; foo
--       SUnknown -&gt; bar
--   </pre>
initBehavior :: forall dom init. (KnownDomain dom, DomainInitBehavior dom ~ init) => SInitBehavior init

-- | Get <a>ResetPolarity</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetPolarity @dom of
--       SActiveHigh -&gt; foo
--       SActiveLow -&gt; bar
--   </pre>
resetPolarity :: forall dom polarity. (KnownDomain dom, DomainResetPolarity dom ~ polarity) => SResetPolarity polarity

-- | A clock signal belonging to a domain named <i>dom</i>.
data Clock (dom :: Domain)

-- | A differential clock signal belonging to a domain named <i>dom</i>.
--   The clock input of a design with such an input has two ports which are
--   in antiphase. The first input is the positive phase, the second the
--   negative phase. When using <a>makeTopEntity</a>, the names of the
--   inputs will end in <tt>_p</tt> and <tt>_n</tt> respectively.
--   
--   To create a differential clock in a test bench, you can use
--   <a>clockToDiffClock</a>.
data DiffClock (dom :: Domain)

-- | Calculate the frequency in <b>Hz</b>, given the period in <b>ps</b>
--   
--   I.e., to calculate the clock frequency of a clock with a period of
--   5000 ps:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz 5000
--   2.0e8
--   </pre>
--   
--   Note that if <tt>p</tt> in <tt>periodToHz (<a>fromIntegral</a> p)</tt>
--   is negative, <tt>fromIntegral</tt> will give an <tt><a>Underflow</a>
--   :: <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Ratio</a>
--   <a>Natural</a>. To get the old behavior of this function, use a type
--   application:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz @(Ratio Natural) 5000
--   200000000 % 1
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
periodToHz :: (HasCallStack, Fractional a) => Natural -> a

-- | Calculate the period in <b>ps</b>, given a frequency in <b>Hz</b>
--   
--   I.e., to calculate the clock period for a circuit to run at 240 MHz we
--   get
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod 240e6
--   4166
--   </pre>
--   
--   If the value <tt>hzToPeriod</tt> is applied to is not of the type
--   <a>Ratio</a> <a>Natural</a>, you can use <tt>hzToPeriod
--   (<a>realToFrac</a> f)</tt>. Note that if <tt>f</tt> is negative,
--   <tt>realToFrac</tt> will give an <tt><a>Underflow</a> ::
--   <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Natural</a>. To
--   get the old behavior of this function, use a type application:
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod @Natural 240e6
--   4166
--   </pre>
--   
--   <ul>
--   <li><b>NB</b>: This function is not synthesizable</li>
--   <li><b>NB</b>: This function is lossy. I.e., <tt>periodToHz .
--   hzToPeriod /= id</tt>.</li>
--   </ul>
hzToPeriod :: (HasCallStack, Integral a) => Ratio Natural -> a

-- | A reset signal belonging to a domain called <i>dom</i>.
--   
--   The underlying representation of resets is <a>Bool</a>.
data Reset (dom :: Domain)

-- | <a>unsafeToReset</a> is unsafe. For asynchronous resets it is unsafe
--   because it can introduce combinatorial loops. In case of synchronous
--   resets it can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeFromActiveLow</a> or
--   <a>unsafeFromActiveHigh</a>.
unsafeToReset :: KnownDomain dom => Signal dom Bool -> Reset dom

-- | <a>unsafeFromReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeToActiveLow</a> or
--   <a>unsafeToActiveHigh</a>.
unsafeFromReset :: Reset dom -> Signal dom Bool

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveHigh :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveLow :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveHigh :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveLow :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | The resetSynchronizer will synchronize an incoming reset according to
--   whether the domain is synchronous or asynchronous.
--   
--   For asynchronous resets this synchronizer ensures the reset will only
--   be de-asserted synchronously but it can still be asserted
--   asynchronously. The reset assert is immediate, but reset de-assertion
--   is delayed by two cycles.
--   
--   Normally, asynchronous resets can be both asynchronously asserted and
--   de-asserted. Asynchronous de-assertion can induce meta-stability in
--   the component which is being reset. To ensure this doesn't happen,
--   <a>resetSynchronizer</a> ensures that de-assertion of a reset happens
--   synchronously. Assertion of the reset remains asynchronous.
--   
--   Note that asynchronous assertion does not induce meta-stability in the
--   component whose reset is asserted. However, when a component "A" in
--   another clock or reset domain depends on the value of a component "B"
--   being reset, then asynchronous assertion of the reset of component "B"
--   can induce meta-stability in component "A". To prevent this from
--   happening you need to use a proper synchronizer, for example one of
--   the synchronizers in <a>Clash.Explicit.Synchronizer</a>.
--   
--   For synchronous resets this function ensures that the reset is
--   asserted and de-asserted synchronously. Both the assertion and
--   de-assertion of the reset are delayed by two cycles.
--   
--   <h3><b>Example 1</b></h3>
--   
--   The circuit below detects a rising bit (i.e., a transition from 0 to
--   1) in a given argument. It takes a reset that is not synchronized to
--   any of the other incoming signals and synchronizes it using
--   <a>resetSynchronizer</a>.
--   
--   <pre>
--   topEntity
--     :: Clock  System
--     -&gt; Reset  System
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk asyncRst key1 =
--     withClockResetEnable clk rst enableGen leds
--    where
--     rst   = <a>resetSynchronizer</a> clk asyncRst
--     key1R = isRising 1 key1
--     leds  = mealy blinkerT (1, False, 0) key1R
--   </pre>
--   
--   <h3><b>Example 2</b></h3>
--   
--   Similar to <i>Example 1</i> this circuit detects a rising bit (i.e., a
--   transition from 0 to 1) in a given argument. It takes a clock that is
--   not stable yet and a reset signal that is not synchronized to any
--   other signals. It stabilizes the clock and then synchronizes the reset
--   signal.
--   
--   Note that the function <a>altpllSync</a> provides this functionality
--   in a convenient form, obviating the need for
--   <tt>resetSynchronizer</tt> for this use case.
--   
--   <pre>
--   topEntity
--     :: Clock  System
--     -&gt; Reset  System
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk rst key1 =
--       let  (pllOut,pllStable) = unsafeAltpll clk rst
--            rstSync            = <a>resetSynchronizer</a> pllOut (unsafeFromActiveLow pllStable)
--       in   exposeClockResetEnable leds pllOut rstSync enableGen
--     where
--       key1R  = isRising 1 key1
--       leds   = mealy blinkerT (1, False, 0) key1R
--   </pre>
--   
--   <h3><b>Implementation details</b></h3>
--   
--   <a>resetSynchronizer</a> implements the following circuit for
--   asynchronous domains:
--   
--   <pre>
--                                   rst
--   --------------------------------------+
--                       |                 |
--                  +----v----+       +----v----+
--     deasserted   |         |       |         |
--   ---------------&gt;         +-------&gt;         +--------&gt;
--                  |         |       |         |
--              +---|&gt;        |   +---|&gt;        |
--              |   |         |   |   |         |
--              |   +---------+   |   +---------+
--      clk     |                 |
--   -----------------------------+
--   </pre>
--   
--   This corresponds to figure 3d at
--   <a>https://www.embedded.com/asynchronous-reset-synchronization-and-distribution-challenges-and-solutions/</a>
--   
--   For synchronous domains two sequential dflipflops are used:
--   
--   <pre>
--                  +---------+       +---------+
--     rst          |         |       |         |
--   ---------------&gt;         +-------&gt;         +--------&gt;
--                  |         |       |         |
--              +---|&gt;        |   +---|&gt;        |
--              |   |         |   |   |         |
--              |   +---------+   |   +---------+
--      clk     |                 |
--   -----------------------------+
--   </pre>
resetSynchronizer :: forall dom. KnownDomain dom => Clock dom -> Reset dom -> Reset dom

-- | Filter glitches from reset signals by only triggering a reset after it
--   has been asserted for <i>glitchlessPeriod</i> cycles. Similarly, it
--   will stay asserted until a <i>glitchlessPeriod</i> number of
--   deasserted cycles have been observed.
--   
--   This circuit can only be used on platforms supporting initial values.
--   This restriction can be worked around by using
--   <a>unsafeResetGlitchFilter</a> but this is not recommended.
--   
--   On platforms without initial values, you should instead use
--   <a>resetGlitchFilterWithReset</a> with an additional power-on reset,
--   or <a>holdReset</a> if filtering is only needed on deassertion.
--   
--   At power-on, the reset will be asserted. If the filtered reset input
--   remains unasserted, the output reset will deassert after
--   <i>glitchlessPeriod</i> clock cycles.
--   
--   If <tt>resetGlitchFilter</tt> is used in a domain with asynchronous
--   resets (<a>Asynchronous</a>), <tt>resetGlitchFilter</tt> will first
--   synchronize the reset input with <a>dualFlipFlopSynchronizer</a>.
--   
--   <h3><b>Example 1</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let sampleResetN n = sampleN n . unsafeToActiveHigh
--   
--   &gt;&gt;&gt; let resetFromList = unsafeFromActiveHigh . fromList
--   
--   &gt;&gt;&gt; let rst = resetFromList [True, True, False, False, True, False, False, True, True, False, True, True]
--   
--   &gt;&gt;&gt; sampleResetN 12 (resetGlitchFilter d2 (clockGen @XilinxSystem) rst)
--   [True,True,True,True,False,False,False,False,False,True,True,True]
--   </pre>
resetGlitchFilter :: forall dom glitchlessPeriod. (HasCallStack, HasDefinedInitialValues dom, 1 <= glitchlessPeriod) => SNat glitchlessPeriod -> Clock dom -> Reset dom -> Reset dom

-- | Hold reset for a number of cycles relative to an implicit reset
--   signal.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 8 (unsafeToActiveHigh (holdReset (SNat @2)))
--   [True,True,True,False,False,False,False,False]
--   </pre>
--   
--   <a>holdReset</a> holds the reset for an additional 2 clock cycles for
--   a total of 3 clock cycles where the reset is asserted.
holdReset :: forall dom m. HiddenClockResetEnable dom => SNat m -> Reset dom

-- | A signal of booleans, indicating whether a component is enabled. No
--   special meaning is implied, it's up to the component itself to decide
--   how to respond to its enable line. It is used throughout Clash as a
--   global enable signal.
data Enable dom

-- | Convert a signal of bools to an <a>Enable</a> construct
toEnable :: Signal dom Bool -> Enable dom

-- | Convert <a>Enable</a> construct to its underlying representation: a
--   signal of bools.
fromEnable :: Enable dom -> Signal dom Bool

-- | Enable generator for some domain. Is simply always True.
enableGen :: Enable dom

-- | A <i>constraint</i> that indicates the component has a hidden
--   <a>Clock</a>
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenClock dom = (Hidden (HiddenClockName dom) (Clock dom), KnownDomain dom)

-- | Hide the <a>Clock</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideClock :: forall dom r. HiddenClock dom => (Clock dom -> r) -> r

-- | Expose a hidden <a>Clock</a> argument of a component, so it can be
--   applied explicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClock reg clockGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeClock</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClock @System reg clockGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
exposeClock :: forall dom r. (HiddenClock dom => r) -> KnownDomain dom => Clock dom -> r

-- | Connect an explicit <a>Clock</a> to a function with a hidden
--   <a>Clock</a>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClock clockGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withClock</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClock @System clockGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withClock :: forall dom r. KnownDomain dom => Clock dom -> (HiddenClock dom => r) -> r

-- | Connect a hidden <a>Clock</a> to an argument where a normal
--   <a>Clock</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hasClock :: forall dom. HiddenClock dom => Clock dom

-- | A <i>constraint</i> that indicates the component needs a <a>Reset</a>
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenReset dom = (Hidden (HiddenResetName dom) (Reset dom), KnownDomain dom)

-- | Hide the <a>Reset</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideReset :: forall dom r. HiddenReset dom => (Reset dom -> r) -> r

-- | Expose a hidden <a>Reset</a> argument of a component, so it can be
--   applied explicitly.
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeReset reg resetGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeReset</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeReset @System reg resetGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
exposeReset :: forall dom r. (HiddenReset dom => r) -> KnownDomain dom => Reset dom -> r

-- | Connect an explicit <a>Reset</a> to a function with a hidden
--   <a>Reset</a>.
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withReset resetGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withReset</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withReset @System resetGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withReset :: forall dom r. KnownDomain dom => Reset dom -> (HiddenReset dom => r) -> r

-- | Connect a hidden <a>Reset</a> to an argument where a normal
--   <a>Reset</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hasReset :: forall dom. HiddenReset dom => Reset dom

-- | A <i>constraint</i> that indicates the component needs an
--   <a>Enable</a>
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenEnable dom = (Hidden (HiddenEnableName dom) (Enable dom), KnownDomain dom)

-- | Hide the <a>Enable</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideEnable :: forall dom r. HiddenEnable dom => (Enable dom -> r) -> r

-- | Expose a hidden <a>Enable</a> argument of a component, so it can be
--   applied explicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeEnable reg enableGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeEnable</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeEnable @System reg enableGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
exposeEnable :: forall dom r. (HiddenEnable dom => r) -> KnownDomain dom => Enable dom -> r

-- | Connect an explicit <a>Enable</a> to a function with a hidden
--   <a>Enable</a>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withEnable enableGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withEnable</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withEnable @System enableGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withEnable :: forall dom r. KnownDomain dom => Enable dom -> (HiddenEnable dom => r) -> r

-- | Connect a hidden <a>Enable</a> to an argument where a normal
--   <a>Enable</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hasEnable :: forall dom. HiddenEnable dom => Enable dom

-- | A <i>constraint</i> that indicates the component needs a <a>Clock</a>,
--   a <a>Reset</a>, and an <a>Enable</a> belonging to the same
--   <tt>dom</tt>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenClockResetEnable dom = (HiddenClock dom, HiddenReset dom, HiddenEnable dom)

-- | Hide the <a>Clock</a>, <a>Reset</a>, and <a>Enable</a> arguments of a
--   component, so they can be routed implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideClockResetEnable :: forall dom r. HiddenClockResetEnable dom => (KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> r) -> r

-- | Expose hidden <a>Clock</a>, <a>Reset</a>, and <a>Enable</a> arguments
--   of a component, so they can be applied explicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClockResetEnable reg clockGen resetGen enableGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeClockResetEnable</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClockResetEnable @System reg clockGen resetGen enableGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Usage in a testbench context:
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst en
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = systemResetGen
--       en             = enableGen
--   </pre>
exposeClockResetEnable :: forall dom r. (HiddenClockResetEnable dom => r) -> KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> r

-- | Connect an explicit <a>Clock</a>, <a>Reset</a>, and <a>Enable</a> to a
--   function with a hidden <a>Clock</a>, <a>Reset</a>, and <a>Enable</a>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClockResetEnable clockGen resetGen enableGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withClockResetEnable</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClockResetEnable @System clockGen resetGen enableGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withClockResetEnable :: forall dom r. KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> (HiddenClockResetEnable dom => r) -> r

-- | A <i>constraint</i> that indicates the component needs a <a>Clock</a>,
--   a <a>Reset</a>, and an <a>Enable</a> belonging to the <a>System</a>
--   domain.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type SystemClockResetEnable = (Hidden (HiddenClockName System) (Clock System), Hidden (HiddenResetName System) (Reset System), Hidden (HiddenEnableName System) (Enable System))

-- | Merge enable signal with signal of bools by applying the boolean AND
--   operation.
--   
--   <b>NB: The component given to <a>andEnable</a> as an argument needs an
--   explicit type signature.</b> Please read <a>Monomorphism restriction
--   leads to surprising behavior</a>.
--   
--   The component whose enable is modified will only be enabled when both
--   the encompassing <a>HiddenEnable</a> and the <a>Signal</a>
--   <tt>dom</tt> <a>Bool</a> are asserted.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; f en = andEnable en reg
--   
--   &gt;&gt;&gt; sampleN @System 10 (f (riseEvery d2))
--   [5,5,5,6,6,7,7,8,8,9]
--   </pre>
--   
--   Force <a>andEnable</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; f en = andEnable @System en reg
--   
--   &gt;&gt;&gt; sampleN 10 (f (riseEvery d2))
--   [5,5,5,6,6,7,7,8,8,9]
--   </pre>
andEnable :: forall dom r. HiddenEnable dom => Signal dom Bool -> (HiddenEnable dom => r) -> r

-- | Special version of <a>delay</a> that doesn't take enable signals of
--   any kind. Initial value will be undefined.
dflipflop :: forall dom a. (HiddenClock dom, NFDataX a) => Signal dom a -> Signal dom a

-- | <a>delay</a> <tt>dflt</tt> <tt>s</tt> delays the values in
--   <a>Signal</a> <tt>s</tt> for once cycle, the value at time 0 is
--   <i>dflt</i>.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 3 (delay 0 (fromList [1,2,3,4]))
--   [0,1,2]
--   </pre>
delay :: forall dom a. (NFDataX a, HiddenClock dom, HiddenEnable dom) => a -> Signal dom a -> Signal dom a

-- | Version of <a>delay</a> that only updates when its second argument is
--   a <a>Just</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; let input = fromList [Just 1, Just 2, Nothing, Nothing, Just 5, Just 6, Just (7::Int)]
--   
--   &gt;&gt;&gt; sampleN @System 7 (delayMaybe 0 input)
--   [0,1,2,2,2,5,6]
--   </pre>
delayMaybe :: forall dom a. (NFDataX a, HiddenClock dom, HiddenEnable dom) => a -> Signal dom (Maybe a) -> Signal dom a

-- | Version of <a>delay</a> that only updates when its second argument is
--   asserted.
--   
--   <pre>
--   &gt;&gt;&gt; let input = fromList [1,2,3,4,5,6,7::Int]
--   
--   &gt;&gt;&gt; let enable = fromList [True,True,False,False,True,True,True]
--   
--   &gt;&gt;&gt; sampleN @System 7 (delayEn 0 enable input)
--   [0,1,2,2,2,5,6]
--   </pre>
delayEn :: forall dom a. (NFDataX a, HiddenClock dom, HiddenEnable dom) => a -> Signal dom Bool -> Signal dom a -> Signal dom a

-- | <a>register</a> <tt>i s</tt> delays the values in <a>Signal</a>
--   <tt>s</tt> for one cycle, and sets the value at time 0 to <tt>i</tt>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 5 (register 8 (fromList [1,1,2,3,4]))
--   [8,8,1,2,3]
--   </pre>
register :: forall dom a. (HiddenClockResetEnable dom, NFDataX a) => a -> Signal dom a -> Signal dom a
infixr 3 `register`

-- | Version of <a>register</a> that only updates its content when its
--   second argument is a <a>Just</a> value. So given:
--   
--   <pre>
--   sometimes1 = s where
--     s = <a>register</a> Nothing (switch <a>&lt;$&gt;</a> s)
--   
--     switch Nothing = Just 1
--     switch _       = Nothing
--   
--   countSometimes = s where
--     s     = <a>regMaybe</a> 0 (plusM (<a>pure</a> <a>&lt;$&gt;</a> s) sometimes1)
--     plusM = <a>liftA2</a> (liftA2 (+))
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 9 sometimes1
--   [Nothing,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]
--   
--   &gt;&gt;&gt; sampleN @System 9 countSometimes
--   [0,0,0,1,1,2,2,3,3]
--   </pre>
regMaybe :: forall dom a. (HiddenClockResetEnable dom, NFDataX a) => a -> Signal dom (Maybe a) -> Signal dom a
infixr 3 `regMaybe`

-- | Version of <a>register</a> that only updates its content when its
--   second argument is asserted. So given:
--   
--   <pre>
--   oscillate = <a>register</a> False (<a>not</a> <a>&lt;$&gt;</a> oscillate)
--   count     = <a>regEn</a> 0 oscillate (count + 1)
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 9 oscillate
--   [False,False,True,False,True,False,True,False,True]
--   
--   &gt;&gt;&gt; sampleN @System 9 count
--   [0,0,0,1,1,2,2,3,3]
--   </pre>
regEn :: forall dom a. (HiddenClockResetEnable dom, NFDataX a) => a -> Signal dom Bool -> Signal dom a -> Signal dom a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>mux</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a
--   </pre>
--   
--   A multiplexer. Given "<tt><a>mux</a> b t f</tt>", output <tt>t</tt>
--   when <tt>b</tt> is <a>True</a>, and <tt>f</tt> when <tt>b</tt> is
--   <a>False</a>.
mux :: Applicative f => f Bool -> f a -> f a -> f a

-- | Clock generator for simulations. Do <b>not</b> use this clock
--   generator for the <i>testBench</i> function, use <a>tbClockGen</a>
--   instead.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem = clockGen @System
--   </pre>
--   
--   See <a>DomainConfiguration</a> for more information on how to use
--   synthesis domains.
clockGen :: KnownDomain dom => Clock dom

-- | Reset generator for simulation purposes. Asserts the reset for a
--   single cycle.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem = resetGen @System
--   </pre>
--   
--   See <a>tbClockGen</a> for example usage.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGen :: forall dom. KnownDomain dom => Reset dom

-- | Reset generator for simulation purposes. Asserts the reset for the
--   first <i>n</i> cycles.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem5 = resetGen @System d5
--   </pre>
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (unsafeToActiveHigh (resetGenN @System d3))
--   [True,True,True,False,False,False,False]
--   </pre>
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGenN :: forall dom n. (KnownDomain dom, 1 <= n) => SNat n -> Reset dom

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: Should only be used for simulation, and <b>not</b> for the
--   <i>testBench</i> function. For the <i>testBench</i> function, used
--   <a>tbSystemClockGen</a>
systemClockGen :: Clock System

-- | Reset generator for use in simulation, for the <a>System</a> clock
--   domain. Asserts the reset for a single cycle.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = <a>systemResetGen</a>
--   </pre>
systemResetGen :: Reset System

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&amp;&amp;.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&amp;&amp;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.&&.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 3 .&&.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.||.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>||</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.||.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 2 .||.

-- | Isomorphism between a <a>Signal</a> of a product type (e.g. a tuple)
--   and a product type of <a>Signal</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <a>Unbundled</a> clk D = <a>Signal</a> clk D
--     <a>bundle</a>   s = s
--     <a>unbundle</a> s = s
--   </pre>
--   
--   For custom product types you'll have to write the instance manually:
--   
--   <pre>
--   data Pair a b = MkPair { getA :: a, getB :: b }
--   
--   instance Bundle (Pair a b) where
--     type Unbundled dom (Pair a b) = Pair (Signal dom a) (Signal dom b)
--   
--     -- bundle :: Pair (Signal dom a) (Signal dom b) -&gt; Signal dom (Pair a b)
--     bundle   (MkPair as bs) = MkPair <a>&lt;$&gt;</a> as <a>&lt;*&gt;</a> bs
--   
--     -- unbundle :: Signal dom (Pair a b) -&gt; Pair (Signal dom a) (Signal dom b)
--     unbundle pairs = MkPair (getA <a>&lt;$&gt;</a> pairs) (getB <a>&lt;$&gt;</a> pairs)
--   </pre>
class Bundle a where {
    type family Unbundled (dom :: Domain) a = res | res -> dom a;
    type Unbundled dom a = Signal dom a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: (Bundle a, Signal dom a ~ Unbundled dom a) => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: Bundle a => Signal dom a -> Unbundled dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, Unbundled dom a ~ Signal dom a) => Signal dom a -> Unbundled dom a

-- | See <a>TaggedEmptyTuple</a>
data EmptyTuple
EmptyTuple :: EmptyTuple

-- | Helper type to emulate the "old" behavior of Bundle's unit instance.
--   I.e., the instance for <tt>Bundle ()</tt> used to be defined as:
--   
--   <pre>
--   class Bundle () where
--     bundle   :: () -&gt; Signal dom ()
--     unbundle :: Signal dom () -&gt; ()
--   </pre>
--   
--   In order to have sensible type inference, the <a>Bundle</a> class
--   specifies that the argument type of <a>bundle</a> should uniquely
--   identify the result type, and vice versa for <a>unbundle</a>. The type
--   signatures in the snippet above don't though, as <tt>()</tt> doesn't
--   uniquely map to a specific domain. In other words, <tt>domain</tt>
--   should occur in both the argument and result of both functions.
--   
--   <a>TaggedEmptyTuple</a> tackles this by carrying the domain in its
--   type. The <a>bundle</a> and <a>unbundle</a> instance now looks like:
--   
--   <pre>
--   class Bundle EmptyTuple where
--     bundle   :: TaggedEmptyTuple dom -&gt; Signal dom EmptyTuple
--     unbundle :: Signal dom EmptyTuple -&gt; TaggedEmptyTuple dom
--   </pre>
--   
--   <tt>dom</tt> is now mentioned both the argument and result for both
--   <a>bundle</a> and <a>unbundle</a>.
data TaggedEmptyTuple (dom :: Domain)
TaggedEmptyTuple :: TaggedEmptyTuple (dom :: Domain)

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System (register 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   Where <a>System</a> denotes the <i>domain</i> to simulate on. The
--   reset line is asserted for a single cycle. The first value is
--   therefore supplied twice to the circuit: once while reset is high, and
--   once directly after. The first <i>output</i> value (the value produced
--   while the reset is asserted) is dropped.
--   
--   If you only want to simulate a finite number of samples, see
--   <a>simulateN</a>. If you need the reset line to be asserted for more
--   than one cycle or if you need a custom reset value, see
--   <a>simulateWithReset</a> and <a>simulateWithResetN</a>.
--   
--   <b>NB</b>: This function is not synthesizable
simulate :: forall dom a b. (KnownDomain dom, NFDataX a, NFDataX b) => (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Simulate a (<tt><a>Unbundled</a> a -&gt; <a>Unbundled</a> b</tt>)
--   function given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System (unbundle . register (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulateB :: forall dom a b. (KnownDomain dom, Bundle a, Bundle b, NFDataX a, NFDataX b) => (HiddenClockResetEnable dom => Unbundled dom a -> Unbundled dom b) -> [a] -> [b]

-- | Same as <a>simulate</a>, but only sample the first <i>Int</i> output
--   values.
--   
--   <b>NB</b>: This function is not synthesizable
simulateN :: forall dom a b. (KnownDomain dom, NFDataX a, NFDataX b) => Int -> (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Same as <a>simulate</a>, but with the reset line asserted for <i>n</i>
--   cycles. Similar to <a>simulate</a>, <a>simulateWithReset</a> will drop
--   the output values produced while the reset is asserted. While the
--   reset is asserted, the reset value <i>a</i> is supplied to the
--   circuit.
simulateWithReset :: forall dom a b m. (KnownDomain dom, NFDataX a, NFDataX b, 1 <= m) => SNat m -> a -> (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Same as <a>simulateWithReset</a>, but only sample the first <i>Int</i>
--   output values.
simulateWithResetN :: forall dom a b m. (KnownDomain dom, NFDataX a, NFDataX b, 1 <= m) => SNat m -> a -> Int -> (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Simulate a component until it matches a condition
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>runUntil</a> will supply them. The reset will be
--   asserted for a single cycle.
--   
--   It prints a message of the form
--   
--   <pre>
--   Signal sampled for N cycles until value X
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
--   
--   <h3><b>Example with test bench</b></h3>
--   
--   A common usage is with a test bench using <a>outputVerifier</a>.
--   
--   <b>NB</b>: Since this uses <a>assert</a>, when using <tt>clashi</tt>,
--   read the note at <a>Clash.Explicit.Testbench#assert-clashi</a>.
--   
--   <pre>
--   import Clash.Prelude
--   import Clash.Explicit.Testbench
--   
--   topEntity
--     :: <a>Signal</a> <a>System</a> Int
--     -&gt; <a>Signal</a> <a>System</a> Int
--   topEntity = id
--   
--   testBench
--     :: <a>Signal</a> <a>System</a> Bool
--   testBench = done
--    where
--     testInput = <a>stimuliGenerator</a> clk rst $(<a>listToVecTH</a> [1 :: Int .. 10])
--     expectedOutput =
--       <a>outputVerifier'</a> clk rst $(<a>listToVecTH</a> $ [1 :: Int .. 9] <a>&lt;&gt;</a> [42])
--     done = expectedOutput $ topEntity testInput
--     clk = <a>tbSystemClockGen</a> (not &lt;$&gt; done)
--     rst = <a>systemResetGen</a>
--   </pre>
--   
--   <pre>
--   &gt; runUntil id testBench
--   
--   
--   cycle(&lt;Clock: System&gt;): 10, outputVerifier
--   expected value: 42, not equal to actual value: 10
--   Signal sampled for 11 cycles until value True
--   </pre>
--   
--   When you need to verify multiple test benches, the following
--   invocations come in handy:
--   
--   <pre>
--   &gt; <a>mapM_</a> (runUntil id) [ testBenchA, testBenchB ]
--   </pre>
--   
--   or when the test benches are in different clock domains:
--   
--   <pre>
--   testBenchA :: Signal DomA Bool
--   testBenchB :: Signal DomB Bool
--   </pre>
--   
--   <pre>
--   &gt; <a>sequence_</a> [ runUntil id testBenchA, runUntil id testBenchB ]
--   </pre>
runUntil :: forall dom a. (KnownDomain dom, NFDataX a, ShowX a) => (a -> Bool) -> (HiddenClockResetEnable dom => Signal dom a) -> IO ()

-- | <i>Lazily</i> simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a>
--   b</tt>) function given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System (register 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulate_lazy :: forall dom a b. KnownDomain dom => (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | <i>Lazily</i> simulate a (<tt><a>Unbundled</a> a -&gt;
--   <a>Unbundled</a> b</tt>) function given a list of samples of type
--   <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System (unbundle . register (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulateB_lazy :: forall dom a b. (KnownDomain dom, Bundle a, Bundle b) => (HiddenClockResetEnable dom => Unbundled dom a -> Unbundled dom b) -> [a] -> [b]

-- | Build an <a>Automaton</a> from a function over <a>Signal</a>s.
--   
--   <b>NB</b>: Consumption of continuation of the <a>Automaton</a> must be
--   affine; that is, you can only apply the continuation associated with a
--   particular element at most once.
signalAutomaton :: forall dom a b. KnownDomain dom => (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> Automaton (->) a b

-- | Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sample</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sample</a> will not drop the value
--   produced by the circuit while the reset was asserted. If you want
--   this, or if you want more than a single cycle reset, consider using
--   <a>sampleWithReset</a>.
--   
--   <b>NB</b>: This function is not synthesizable
sample :: forall dom a. (KnownDomain dom, NFDataX a) => (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Get a list of <i>n</i> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN @System 3 s == [s0, s1, s2]
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sampleN</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sampleN</a> will not drop the value
--   produced by the circuit while the reset was asserted. If you want
--   this, or if you want more than a single cycle reset, consider using
--   <a>sampleWithResetN</a>.
--   
--   <b>NB</b>: This function is not synthesizable
sampleN :: forall dom a. (KnownDomain dom, NFDataX a) => Int -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Get an infinite list of samples from a <a>Signal</a>, while asserting
--   the reset line for <i>m</i> clock cycles. <a>sampleWithReset</a> does
--   not return the first <i>m</i> cycles, i.e., when the reset is
--   asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleWithReset :: forall dom a m. (KnownDomain dom, NFDataX a, 1 <= m) => SNat m -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Get a list of <i>n</i> samples from a <a>Signal</a>, while asserting
--   the reset line for <i>m</i> clock cycles. <a>sampleWithReset</a> does
--   not return the first <i>m</i> cycles, i.e., while the reset is
--   asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleWithResetN :: forall dom a m. (KnownDomain dom, NFDataX a, 1 <= m) => SNat m -> Int -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList :: NFDataX a => [a] -> Signal dom a

-- | Like <a>fromList</a>, but resets on reset and has a defined reset
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; let rst = unsafeFromActiveHigh (fromList [True, True, False, False, True, False])
--   
--   &gt;&gt;&gt; let res = withReset rst (fromListWithReset Nothing [Just 'a', Just 'b', Just 'c'])
--   
--   &gt;&gt;&gt; sampleN @System 6 res
--   [Nothing,Nothing,Just 'a',Just 'b',Nothing,Just 'a']
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromListWithReset :: forall dom a. (HiddenReset dom, NFDataX a) => a -> [a] -> Signal dom a

-- | <i>Lazily</i> get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sample_lazy</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sample_lazy</a> will not drop the
--   value produced by the circuit while the reset was asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sample_lazy :: forall dom a. KnownDomain dom => (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Lazily get a list of <i>n</i> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN @System 3 s == [s0, s1, s2]
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sampleN_lazy</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sampleN_lazy</a> will not drop the
--   value produced by the circuit while the reset was asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleN_lazy :: forall dom a. KnownDomain dom => Int -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5] :: Signal System Int)
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList_lazy :: [a] -> Signal dom a

-- | <tt>testFor n s</tt> tests the signal <i>s</i> for <i>n</i> cycles.
--   
--   <b>NB</b>: This function is not synthesizable
testFor :: KnownDomain dom => Int -> (HiddenClockResetEnable dom => Signal dom Bool) -> Property

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.==.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>==</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.==.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 .==.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(./=.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>/=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(./=.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 ./=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>.

-- | Converts the <tt>out</tt> part of a BiSignal to an <tt>in</tt> part.
--   In simulation it checks whether multiple components are writing and
--   will error accordingly. Make sure this is only called ONCE for every
--   BiSignal.
veryUnsafeToBiSignalIn :: (HasCallStack, KnownNat n, Given (SBiSignalDefault ds)) => BiSignalOut ds d n -> BiSignalIn ds d n

-- | Read the value from an <b>inout</b> port
readFromBiSignal :: (HasCallStack, BitPack a) => BiSignalIn ds d (BitSize a) -> Signal d a

-- | Write to an <b>inout</b> port
writeToBiSignal :: (HasCallStack, BitPack a, NFDataX a) => BiSignalIn ds d (BitSize a) -> Signal d (Maybe a) -> BiSignalOut ds d (BitSize a)

-- | Combine several <b>inout</b> signals into one.
mergeBiSignalOuts :: (HasCallStack, KnownNat n) => Vec n (BiSignalOut defaultState dom m) -> BiSignalOut defaultState dom m
type HiddenClockName (dom :: Domain) = "clock"
type HiddenResetName (dom :: Domain) = "reset"
type HiddenEnableName (dom :: Domain) = "enable"

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromHighPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromLowPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToHighPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToLowPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool


-- | See <a>Clash.Explicit.Verification</a> for an introduction.
--   
--   The verification API is currently experimental and subject to change.
module Clash.Verification
data Assertion (dom :: Domain)

-- | A property is a temporal or basic assertion that's specified to either
--   used as an _assert_ or _cover_ statement. See <a>assert</a> and
--   <a>cover</a>.
data Property (dom :: Domain)

-- | Render target for HDL
data RenderAs

-- | Property Specification Language
PSL :: RenderAs

-- | SystemVerilog Assertions
SVA :: RenderAs

-- | Use SVA for SystemVerilog, PSL for others
AutoRenderAs :: RenderAs

-- | Yosys Formal Extensions for Verilog and SystemVerilog. See:
--   <a>https://symbiyosys.readthedocs.io/en/latest/verilog.html</a> and
--   <a>https://symbiyosys.readthedocs.io/en/latest/verific.html</a>
--   
--   Falls back to PSL for VHDL, however currently Clash's PSL syntax isn't
--   suported by GHDL+SymbiYosys;
YosysFormal :: RenderAs

-- | Convert a signal to a cv expression with a name hint. Clash will try
--   its best to use this name in the rendered assertion, but might run
--   into collisions. You can skip using <a>name</a> altogether. Clash will
--   then try its best to get a readable name from context.
name :: Text -> Signal dom Bool -> Assertion dom

-- | For using a literal (either True or False) in assertions
lit :: Bool -> Assertion dom

-- | Truth table for <a>not</a>:
--   
--   <pre>
--   a     | not a
--   ------------
--   True  | False
--   False | True
--   </pre>
not :: AssertionValue dom a => a -> Assertion dom

-- | Truth table for <a>and</a>:
--   
--   <pre>
--   a     | b     | a `and` b
--   --------------|----------
--   False | False | False
--   False | True  | False
--   True  | False | False
--   True  | True  | True
--   </pre>
and :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Truth table for <a>or</a>:
--   
--   <pre>
--   a     | b     | a `or` b
--   --------------|---------
--   False | False | False
--   False | True  | True
--   True  | False | True
--   True  | True  | True
--   </pre>
or :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Truth table for <a>implies</a>:
--   
--   <pre>
--   a     | b     | a `implies` b
--   --------------|--------------
--   False | False | True
--   False | True  | True
--   True  | False | False
--   True  | True  | True
--   </pre>
implies :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Truth table for <a>next</a>:
--   
--   <pre>
--   a[n]  | a[n+1] | a `implies` next a
--   ---------------|-------------------
--   False | False  | True
--   False | True   | True
--   True  | False  | False
--   True  | True   | True
--   </pre>
--   
--   where a[n] represents the value of <tt>a</tt> at cycle <tt>n</tt> and
--   <tt>a[n+1]</tt> represents the value of <tt>a</tt> at cycle
--   <tt>n+1</tt>. Cycle n is an arbitrary cycle.
next :: AssertionValue dom a => a -> Assertion dom

-- | Truth table for <a>nextN</a>:
--   
--   <pre>
--   a[n]  | a[n+m] | a `implies` next m a
--   ---------------|---------------------
--   False | False  | True
--   False | True   | True
--   True  | False  | False
--   True  | True   | True
--   </pre>
--   
--   where a[n] represents the value of <tt>a</tt> at cycle <tt>n</tt> and
--   a[n+m] represents the value of <tt>a</tt> at cycle <tt>n+m</tt>. Cycle
--   n is an arbitrary cycle.
nextN :: AssertionValue dom a => Word -> a -> Assertion dom

-- | Same as <tt>a &amp;&amp; next b</tt> but with a nice syntax. E.g.,
--   <tt>a &amp;&amp; next b</tt> could be written as <tt>a <a>before</a>
--   b</tt>. Might be read as "a happens one cycle before b".
before :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Same as <tt>a <a>implies</a> next b</tt> but with a nice syntax. E.g.,
--   <tt>a <a>implies</a> next b</tt> could be written as <tt>a
--   <a>timplies</a> b</tt>. Might be read as "a at cycle n implies b at
--   cycle n+1".
timplies :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Same as <a>implies</a> but strictly temporal.
timpliesOverlapping :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom

-- | Specify assertion should _always_ hold
always :: AssertionValue dom a => a -> Assertion dom

-- | Specify assertion should _never_ hold (not supported by SVA)
never :: AssertionValue dom a => a -> Assertion dom

-- | Specify assertion should _eventually_ hold
eventually :: AssertionValue dom a => a -> Assertion dom

-- | Check whether given assertion always holds. Results can be collected
--   with <a>check</a>.
assert :: AssertionValue dom a => a -> Property dom

-- | Check whether given assertion holds for at least a single cycle.
--   Results can be collected with <a>check</a>.
cover :: AssertionValue dom a => a -> Property dom
check :: (KnownDomain dom, HiddenClock dom, HiddenReset dom) => Text -> RenderAs -> Property dom -> Signal dom AssertionResult
checkI :: (KnownDomain dom, HiddenClock dom, HiddenReset dom) => Text -> RenderAs -> Property dom -> Signal dom a -> Signal dom a

-- | Print assertions in HDL
hideAssertion :: Signal dom AssertionResult -> Signal dom a -> Signal dom a

module Clash.Verification.DSL
(|&|) :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom
infixr 5 |&|
(|||) :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom
infixr 4 |||
(~>) :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom
infixr 0 ~>
(|=>) :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom
infixr 1 |=>
(|->) :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom
infixr 1 |->
(#|#) :: (AssertionValue dom a, AssertionValue dom b) => a -> b -> Assertion dom
infixr 3 #|#


module Clash.Signal.Delayed

-- | A synchronized signal with samples of type <tt>a</tt>, synchronized to
--   clock <tt>clk</tt>, that has accumulated <tt>delay</tt> amount of
--   samples delay along its path.
--   
--   DSignal has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i DSignal
--   type role DSignal nominal nominal representational
--   ...
--   </pre>
--   
--   as it is safe to coerce the values in the signal, but not safe to
--   coerce the synthesis domain or delay in the signal.
data DSignal (dom :: Domain) (delay :: Nat) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> periods.
--   
--   <pre>
--   delay3
--     :: HiddenClockResetEnable dom
--     =&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 3) Int
--   delay3 = <a>delayed</a> (-1 <a>:&gt;</a> -1 <a>:&gt;</a> -1 <a>:&gt;</a> <a>Nil</a>)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 7 (toSignal (delay3 (dfromList [0..])))
--   [-1,-1,-1,-1,1,2,3]
--   </pre>
delayed :: (KnownNat d, HiddenClockResetEnable dom, NFDataX a) => Vec d a -> DSignal dom n a -> DSignal dom (n + d) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> periods, where <tt>d</tt> is
--   derived from the context.
--   
--   <pre>
--   delay2
--     :: HiddenClockResetEnable dom
--     =&gt; Int
--     -&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 2) Int
--   delay2 = <a>delayedI</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 7 (toSignal (delay2 (-1) (dfromList [0..])))
--   [-1,-1,-1,1,2,3,4]
--   </pre>
--   
--   Or <tt>d</tt> can be specified using type application:
--   
--   <pre>
--   &gt;&gt;&gt; :t delayedI @3
--   delayedI @3
--     :: (...
--         ...
--         ...
--         ...) =&gt;
--        a -&gt; DSignal dom n a -&gt; DSignal dom (n + 3) a
--   </pre>
delayedI :: (KnownNat d, NFDataX a, HiddenClockResetEnable dom) => a -> DSignal dom n a -> DSignal dom (n + d) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> cycles, the value at time 0..d-1
--   is <i>a</i>.
--   
--   <pre>
--   delayN2
--     :: ( HiddenClock dom
--        , HiddenEnable dom )
--     =&gt; Int
--     -&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 2) Int
--   delayN2 = <a>delayN</a> d2
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN @System 6 (toSignal (delayN2 (-1) (dfromList [1..])))
--   [-1,-1,1,2,3,4]
--   </pre>
delayN :: forall dom a d n. (HiddenClock dom, HiddenEnable dom, NFDataX a) => SNat d -> a -> DSignal dom n a -> DSignal dom (n + d) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> cycles, where <tt>d</tt> is
--   derived from the context. The value at time 0..d-1 is a default value.
--   
--   <pre>
--   delayI2
--     :: ( HiddenClock dom
--        , HiddenEnable dom )
--     =&gt; Int
--     -&gt; <a>DSignal</a> dom n Int
--     -&gt; <a>DSignal</a> dom (n + 2) Int
--   delayI2 = <a>delayI</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 6 (toSignal (delayI2 (-1) (dfromList [1..])))
--   [-1,-1,1,2,3,4]
--   </pre>
--   
--   You can also use type application to do the same:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 6 (toSignal (delayI @2 (-1) (dfromList [1..])))
--   [-1,-1,1,2,3,4]
--   </pre>
delayI :: forall d n a dom. (HiddenClock dom, HiddenEnable dom, NFDataX a, KnownNat d) => a -> DSignal dom n a -> DSignal dom (n + d) a

-- | Tree fold over a <a>Vec</a> of <a>DSignal</a>s with a combinatorial
--   function, and delaying <tt>delay</tt> cycles after each application.
--   Values at times 0..(delay*k)-1 are set to a default.
--   
--   <pre>
--   countingSignals :: Vec 4 (DSignal dom 0 Int)
--   countingSignals = repeat (dfromList [0..])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN @System 6 (toSignal (delayedFold d1 (-1) (+) countingSignals))
--   [-1,-2,0,4,8,12]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN @System 8 (toSignal (delayedFold d2 (-1) (*) countingSignals))
--   [-1,-1,1,1,0,1,16,81]
--   </pre>
delayedFold :: forall dom n delay k a. (HiddenClock dom, HiddenEnable dom, NFDataX a, KnownNat delay, KnownNat k) => SNat delay -> a -> (a -> a -> a) -> Vec (2 ^ k) (DSignal dom n a) -> DSignal dom (n + (delay * k)) a

-- | Feed the delayed result of a function back to its input:
--   
--   <pre>
--   mac
--     :: forall dom
--      . KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--   mac clk rst en x y = <a>feedback</a> (mac' x y)
--     where
--       mac'
--         :: <a>DSignal</a> dom 0 Int
--         -&gt; <a>DSignal</a> dom 0 Int
--         -&gt; <a>DSignal</a> dom 0 Int
--         -&gt; (<a>DSignal</a> dom 0 Int, <a>DSignal</a> dom 1 Int)
--       mac' a b acc = let acc' = a * b + acc
--                      in  (acc, <a>delayedI</a> clk rst en 0 acc')
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (toSignal (mac systemClockGen systemResetGen enableGen (dfromList [0..]) (dfromList [0..])))
--   [0,0,1,5,14,30,55]
--   </pre>
feedback :: (DSignal dom n a -> (DSignal dom n a, DSignal dom ((n + m) + 1) a)) -> DSignal dom n a

-- | <a>Signal</a>s are not delayed
fromSignal :: Signal dom a -> DSignal dom 0 a

-- | Strip a <a>DSignal</a> of its delay information.
toSignal :: DSignal dom delay a -> Signal dom a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (toSignal (dfromList [1,2,3,4,5]))
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
dfromList :: NFDataX a => [a] -> DSignal dom 0 a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (toSignal (dfromList [1,2,3,4,5]))
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
dfromList_lazy :: [a] -> DSignal dom 0 a

-- | <b>EXPERIMENTAL</b>
--   
--   <b>Unsafely</b> convert a <a>Signal</a> to a <a>DSignal</a> with an
--   arbitrary <tt>delay</tt>.
--   
--   <b>NB</b>: Should only be used to interface with functions specified
--   in terms of <a>Signal</a>.
unsafeFromSignal :: Signal dom a -> DSignal dom n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal from the future in the present. Often
--   required When writing a circuit that requires feedback from itself.
--   
--   <pre>
--   mac
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--     -&gt; <a>DSignal</a> dom 0 Int
--   mac clk rst en x y = acc'
--     where
--       acc' = (x * y) + <a>antiDelay</a> d1 acc
--       acc  = <a>delayedI</a> clk rst en 0 acc'
--   </pre>
antiDelay :: SNat d -> DSignal dom (n + d) a -> DSignal dom n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal from the past in the present. In
--   contrast with <a>delayed</a> and friends forward does not insert any
--   logic. This means using this function violates the delay invariant of
--   <a>DSignal</a>. This is sometimes useful when combining unrelated
--   delayed signals where inserting logic is not wanted or when
--   abstracting over internal delayed signals where the internal delay
--   information should not be leaked.
--   
--   For example, the circuit below returns a sequence of numbers as a pair
--   but the internal delay information between the elements of the pair
--   should not leak into the type.
--   
--   <pre>
--   numbers
--     :: forall dom
--      . KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; Enable dom
--     -&gt; <a>DSignal</a> dom 5 (Int, Int)
--   numbers clk rst en = DB.bundle (forward d1 s1, s2)
--     where
--       s1 :: <a>DSignal</a> dom 4 Int
--       s1 = <a>delayed</a> clk rst en (100 :&gt; 10 :&gt; 5 :&gt; 1 :&gt; Nil) (pure 200)
--       s2 :: <a>DSignal</a> dom 5 Int
--       s2 = fmap (2*) $ <a>delayN</a> d1 0 en clk s1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 8 (toSignal (numbers systemClockGen systemResetGen enableGen))
--   [(1,0),(1,2),(5,2),(10,10),(100,20),(200,200),(200,400),(200,400)]
--   </pre>
forward :: SNat d -> DSignal dom n a -> DSignal dom (n + d) a


module Clash.Signal.Delayed.Bundle

-- | Isomorphism between a <a>DSignal</a> of a product type (e.g. a tuple)
--   and a product type of <a>DSignal</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <a>Unbundled</a> dom delay D = <a>DSignal</a> dom delay D
--     <a>bundle</a>   s = s
--     <a>unbundle</a> s = s
--   </pre>
class Bundle a where {
    type family Unbundled (dom :: Domain) (d :: Nat) a = res | res -> dom d a;
    type Unbundled dom d a = DSignal dom d a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>DSignal</a> dom d a, <a>DSignal</a> dom d b) -&gt; <a>DSignal</a> dom d (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>DSignal</a> dom <a>Bit</a> -&gt; <a>DSignal</a> dom <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled dom d a -> DSignal dom d a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>DSignal</a> dom d a, <a>DSignal</a> dom d b) -&gt; <a>DSignal</a> dom d (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>DSignal</a> dom <a>Bit</a> -&gt; <a>DSignal</a> dom <a>Bit</a>
--   </pre>
bundle :: (Bundle a, DSignal dom d a ~ Unbundled dom d a) => Unbundled dom d a -> DSignal dom d a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>DSignal</a> dom d (a,b) -&gt; (<a>DSignal</a> dom d a, <a>DSignal</a> dom d b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>DSignal</a> dom <a>Bit</a> -&gt; <a>DSignal</a> dom <a>Bit</a>
--   </pre>
unbundle :: Bundle a => DSignal dom d a -> Unbundled dom d a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>DSignal</a> dom d (a,b) -&gt; (<a>DSignal</a> dom d a, <a>DSignal</a> dom d b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>DSignal</a> dom <a>Bit</a> -&gt; <a>DSignal</a> dom <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, Unbundled dom d a ~ DSignal dom d a) => DSignal dom d a -> Unbundled dom d a

-- | See <a>TaggedEmptyTuple</a>
data EmptyTuple
EmptyTuple :: EmptyTuple

-- | Same as <a>TaggedEmptyTuple</a> in <a>Clash.Signal.Bundle</a>, but
--   adapted for <a>DSignal</a>.
data TaggedEmptyTuple (dom :: Domain) (d :: Nat)
TaggedEmptyTuple :: TaggedEmptyTuple (dom :: Domain) (d :: Nat)
instance Clash.Signal.Delayed.Bundle.Bundle Clash.Signal.Bundle.EmptyTuple
instance Clash.Signal.Delayed.Bundle.Bundle ()
instance Clash.Signal.Delayed.Bundle.Bundle GHC.Types.Bool
instance Clash.Signal.Delayed.Bundle.Bundle GHC.Integer.Type.Integer
instance Clash.Signal.Delayed.Bundle.Bundle GHC.Types.Int
instance Clash.Signal.Delayed.Bundle.Bundle GHC.Types.Float
instance Clash.Signal.Delayed.Bundle.Bundle GHC.Types.Double
instance Clash.Signal.Delayed.Bundle.Bundle (GHC.Maybe.Maybe a)
instance Clash.Signal.Delayed.Bundle.Bundle (Data.Either.Either a b)
instance Clash.Signal.Delayed.Bundle.Bundle Clash.Sized.Internal.BitVector.Bit
instance Clash.Signal.Delayed.Bundle.Bundle (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Signal.Delayed.Bundle.Bundle (Clash.Sized.Internal.Index.Index n)
instance Clash.Signal.Delayed.Bundle.Bundle (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Signal.Delayed.Bundle.Bundle (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Signal.Delayed.Bundle.Bundle (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.Signal.Delayed.Bundle.Bundle (a, b)
instance Clash.Signal.Delayed.Bundle.Bundle (a, b, c)
instance Clash.Signal.Delayed.Bundle.Bundle (a, b, c, d)
instance Clash.Signal.Delayed.Bundle.Bundle (a, b, c, d, e)
instance Clash.Signal.Delayed.Bundle.Bundle (a, b, c, d, e, f)
instance Clash.Signal.Delayed.Bundle.Bundle (a, b, c, d, e, f, g)
instance Clash.Signal.Delayed.Bundle.Bundle (a, b, c, d, e, f, g, h)
instance GHC.TypeNats.KnownNat n => Clash.Signal.Delayed.Bundle.Bundle (Clash.Sized.Vector.Vec n a)
instance GHC.TypeNats.KnownNat d => Clash.Signal.Delayed.Bundle.Bundle (Clash.Sized.RTree.RTree d a)


-- | <h1>Initializing a ROM with a data file </h1>
--   
--   ROMs initialized with a data file. The BNF grammar for this data file
--   is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned numbers <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   Such a file can be produced with <a>memFile</a>:
--   
--   <pre>
--   writeFile "memory.bin" (memFile Nothing [7 :: Unsigned 9 .. 13])
--   </pre>
--   
--   We can instantiate a synchronous ROM using the contents of the file
--   above like so:
--   
--   <pre>
--   f :: (HiddenClock dom, HiddenEnable dom)
--      =&gt; Signal dom (Unsigned 3)
--      -&gt; Signal dom (Unsigned 9)
--   f rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> d7 "memory.bin" rd
--   </pre>
--   
--   And see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g :: (HiddenClock dom, HiddenEnable dom)
--     =&gt; Signal dom (Unsigned 3)
--     -&gt; Signal dom (Unsigned 6,Signed 3)
--   g rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> d7 "memory.bin" rd
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Prelude.ROM.File

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFile</a> is significantly slowing
--   down your simulation, give it a <i>monomorphic</i> type signature. So
--   instead of leaving the type to be inferred:<pre>myRomData =
--   asyncRomFile d512 "memory.bin" </pre>or giving it a <i>polymorphic</i>
--   type signature:<pre>myRomData :: Enum addr =&gt; addr -&gt; BitVector
--   16 myRomData = asyncRomFile d512 "memory.bin" </pre>you <b>should</b>
--   give it a <i>monomorphic</i> type signature:<pre>myRomData :: Unsigned
--   9 -&gt; BitVector 16 myRomData = asyncRomFile d512 "memory.bin"
--   </pre></li>
--   </ul>
asyncRomFile :: (KnownNat m, Enum addr) => SNat n -> FilePath -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFilePow2</a> is significantly
--   slowing down your simulation, give it a <i>monomorphic</i> type
--   signature. So instead of leaving the type to be
--   inferred:<pre>myRomData = asyncRomFilePow2 "memory.bin" </pre>you
--   <b>should</b> give it a <i>monomorphic</i> type
--   signature:<pre>myRomData :: Unsigned 9 -&gt; BitVector 16 myRomData =
--   asyncRomFilePow2 "memory.bin" </pre></li>
--   </ul>
asyncRomFilePow2 :: forall n m. (KnownNat m, KnownNat n) => FilePath -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, KnownNat n, HiddenClock dom, HiddenEnable dom, Enum addr) => SNat n -> FilePath -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFilePow2 :: forall n m dom. (KnownNat m, KnownNat n, HiddenClock dom, HiddenEnable dom) => FilePath -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Convert data to the <a>String</a> contents of a memory file.
--   
--   <ul>
--   <li><b>NB</b>: Not synthesizable</li>
--   <li>The following document the several ways to instantiate components
--   with
--   files:<ul><li><a>Clash.Prelude.BlockRam.File#usingramfiles</a></li><li><a>Clash.Prelude.ROM.File#usingromfiles</a></li><li><a>Clash.Explicit.BlockRam.File#usingramfiles</a></li><li><a>Clash.Explicit.ROM.File#usingromfiles</a></li></ul></li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
--   
--   <h1>Example</h1>
--   
--   The <tt>Maybe</tt> datatype has don't care bits, where the actual
--   value does not matter. But the bits need a defined value in the
--   memory. Either 0 or 1 can be used, and both are valid representations
--   of the data.
--   
--   <pre>
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8]
--   
--   &gt;&gt;&gt; mapM_ (putStrLn . show . pack) es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 0) es)
--   000000000
--   100000111
--   100001000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 1) es)
--   011111111
--   100000111
--   100001000
--   </pre>
memFile :: forall a f. (BitPack a, Foldable f, HasCallStack) => Maybe Bit -> f a -> String

-- | asyncRomFile primitive
asyncRomFile# :: KnownNat m => SNat n -> FilePath -> Int -> BitVector m


-- | <h1>Efficient bundling of ROM content with the compiled code</h1>
--   
--   Leveraging Template Haskell, the content for the ROM components in
--   this module is stored alongside the compiled Haskell code. It covers
--   use cases where passing the initial content as a <a>Vec</a> turns out
--   to be problematically slow.
--   
--   The data is stored efficiently, with very little overhead (worst-case
--   7%, often no overhead at all).
--   
--   Unlike <a>Clash.Prelude.ROM.File</a>, <a>Clash.Prelude.ROM.Blob</a>
--   generates practically the same HDL as <a>Clash.Prelude.ROM</a> and is
--   compatible with all tools consuming the generated HDL.
module Clash.Prelude.ROM.Blob

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlob :: Enum addr => MemBlob n m -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlobPow2 :: KnownNat n => MemBlob (2 ^ n) m -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlob :: forall dom addr m n. (HiddenClock dom, HiddenEnable dom, Enum addr) => MemBlob n m -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlobPow2 :: forall dom m n. (HiddenClock dom, HiddenEnable dom, KnownNat n) => MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]

-- | asyncRomBlob primitive
asyncRomBlob# :: forall m n. MemBlob n m -> Int -> BitVector m


-- | ROMs
module Clash.Prelude.ROM

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFile</a> and
--   <a>asyncRomBlob</a> for different approaches that scale well.</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr, NFDataX a) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFilePow2</a> and
--   <a>asyncRomBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
asyncRomPow2 :: (KnownNat n, NFDataX a) => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFile</a> and
--   <a>romBlob</a> for different approaches that scale well.</li>
--   </ul>
rom :: forall dom n m a. (NFDataX a, KnownNat n, KnownNat m, HiddenClock dom, HiddenEnable dom) => Vec n a -> Signal dom (Unsigned m) -> Signal dom a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFilePow2</a> and
--   <a>romBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
romPow2 :: forall dom n a. (KnownNat n, NFDataX a, HiddenClock dom, HiddenEnable dom) => Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom a

-- | asyncRom primitive
asyncRom# :: forall n a. (KnownNat n, NFDataX a) => Vec n a -> Int -> a


-- | RAM primitives with a combinational read port
module Clash.Prelude.RAM

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, NFDataX addr, HiddenClock dom, HiddenEnable dom, HasCallStack, NFDataX a) => SNat n -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: (KnownNat n, HiddenClock dom, HiddenEnable dom, HasCallStack, NFDataX a) => Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a


-- | Whereas the output of a Mealy machine depends on <i>current
--   transition</i>, the output of a Moore machine depends on the
--   <i>previous state</i>.
--   
--   Moore machines are strictly less expressive, but may impose laxer
--   timing requirements.
module Clash.Prelude.Moore

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; Int        -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: HiddenClockResetEnable dom
--     =&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac = <a>moore</a> mac id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14,30,...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockResetEnable dom
--     =&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> macT id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> macT id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: (HiddenClockResetEnable dom, NFDataX s) => (s -> i -> s) -> (s -> o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>moore</a> t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>moore</a> t o 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> t o 3 (c,i1)
--   </pre>
mooreB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> s) -> (s -> o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a synchronous function from a combinational function describing
--   a moore machine without any output logic
medvedev :: (HiddenClockResetEnable dom, NFDataX s) => (s -> i -> s) -> s -> Signal dom i -> Signal dom s

-- | A version of <a>medvedev</a> that does automatic <a>Bundle</a>ing
medvedevB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle s) => (s -> i -> s) -> s -> Unbundled dom i -> Unbundled dom s


-- | Whereas the output of a Moore machine depends on the <i>previous
--   state</i>, the output of a Mealy machine depends on <i>current
--   transition</i>.
--   
--   Mealy machines are strictly more expressive, but may impose stricter
--   timing requirements.
module Clash.Prelude.Mealy

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac :: HiddenClockResetEnable dom  =&gt; <a>Signal</a> dom (Int, Int) -&gt; <a>Signal</a> dom Int
--   mac = <a>mealy</a> macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockResetEnable dom
--     =&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> macT 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> macT 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: (HiddenClockResetEnable dom, NFDataX s) => (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o

-- | Create a synchronous function from a combinational function describing
--   a mealy machine using the state monad. This can be particularly useful
--   when combined with lenses or optics to replicate imperative
--   algorithms.
--   
--   <pre>
--   data DelayState = DelayState
--     { _history    :: Vec 4 Int
--     , _untilValid :: Index 4
--     }
--     deriving (Generic, NFDataX)
--   makeLenses ''DelayState
--   
--   initialDelayState = DelayState (repeat 0) maxBound
--   
--   delayS :: Int -&gt; State DelayState (Maybe Int)
--   delayS n = do
--     history   %= (n +&gt;&gt;)
--     remaining &lt;- use untilValid
--     if remaining &gt; 0
--     then do
--        untilValid -= 1
--        return Nothing
--      else do
--        out &lt;- uses history last
--        return (Just out)
--   
--   delayTop :: HiddenClockResetEnable dom  =&gt; <a>Signal</a> dom Int -&gt; <a>Signal</a> dom (Maybe Int)
--   delayTop = <a>mealyS</a> delayS initialDelayState
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; L.take 7 $ simulate @System delayTop [1,2,3,4,5,6,7,8]
--   [Nothing,Nothing,Nothing,Just 1,Just 2,Just 3,Just 4]
--   ...
--   </pre>
mealyS :: (HiddenClockResetEnable dom, NFDataX s) => (i -> State s o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool, Int) -&gt; (Int, (Int, Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>mealy</a> f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>mealy</a> f 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> f 3 (c,i1)
--   </pre>
mealyB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | A version of <a>mealyS</a> that does automatic <a>Bundle</a>ing, see
--   <a>mealyB</a> for details.
mealySB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (i -> State s o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Infix version of <a>mealyB</a>
(<^>) :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o


-- | Self-synchronizing circuits based on data-flow principles.

-- | <i>Deprecated: Module will be removed in Clash 1.10 in favor of
--   clash-protocols. See:
--   <a>https://github.com/clash-lang/clash-protocols/</a>.</i>
module Clash.Prelude.DataFlow

-- | Dataflow circuit with bidirectional synchronization channels.
--   
--   In the <i>forward</i> direction we assert <i>validity</i> of the data.
--   In the <i>backward</i> direction we assert that the circuit is
--   <i>ready</i> to receive new data. A circuit adhering to the
--   <a>DataFlow</a> type should:
--   
--   <ul>
--   <li>Not consume data when validity is deasserted.</li>
--   <li>Only update its output when readiness is asserted.</li>
--   </ul>
--   
--   The <a>DataFlow</a> type is defined as:
--   
--   <pre>
--   newtype DataFlow' dom iEn oEn i o
--     = DF
--     { df :: <a>Signal</a> dom i     -- Incoming data
--          -&gt; <a>Signal</a> dom iEn   -- Flagged with /valid/ bits @iEn@.
--          -&gt; <a>Signal</a> dom oEn   -- Incoming back-pressure, /ready/ edge.
--          -&gt; ( <a>Signal</a> dom o   -- Outgoing data.
--             , <a>Signal</a> dom oEn -- Flagged with /valid/ bits @oEn@.
--             , <a>Signal</a> dom iEn -- Outgoing back-pressure, /ready/ edge.
--             )
--     }
--   </pre>
--   
--   where:
--   
--   <ul>
--   <li><tt>dom</tt> is the domain to which the circuit is
--   synchronized.</li>
--   <li><tt>iEn</tt> is the type of the bidirectional incoming
--   synchronization channel.</li>
--   <li><tt>oEn</tt> is the type of the bidirectional outgoing
--   synchronization channel.</li>
--   <li><tt>i</tt> is the incoming data type.</li>
--   <li><tt>o</tt> is the outgoing data type.</li>
--   </ul>
--   
--   We define several composition operators for our <a>DataFlow</a>
--   circuits:
--   
--   <ul>
--   <li><a>seqDF</a> sequential composition.</li>
--   <li><a>parDF</a> parallel composition.</li>
--   <li><a>loopDF</a> add a feedback arc.</li>
--   <li><a>lockStep</a> proceed in lock-step.</li>
--   </ul>
--   
--   When you look at the types of the above operators it becomes clear why
--   we parametrize in the types of the synchronization channels.
newtype DataFlow dom iEn oEn i o
DF :: (Signal dom i -> Signal dom iEn -> Signal dom oEn -> (Signal dom o, Signal dom oEn, Signal dom iEn)) -> DataFlow dom iEn oEn i o

-- | Create an ordinary circuit from a <a>DataFlow</a> circuit
[df] :: DataFlow dom iEn oEn i o -> Signal dom i -> Signal dom iEn -> Signal dom oEn -> (Signal dom o, Signal dom oEn, Signal dom iEn)

-- | Dataflow circuit synchronized to the <a>systemClockGen</a>. type
--   DataFlow iEn oEn i o = DataFlow' systemClockGen iEn oEn i o
--   
--   Create a <a>DataFlow</a> circuit from a circuit description with the
--   appropriate type:
--   
--   <pre>
--   <a>Signal</a> dom i        -- Incoming data.
--   -&gt; <a>Signal</a> dom Bool  -- Flagged with a single /valid/ bit.
--   -&gt; <a>Signal</a> dom Bool  -- Incoming back-pressure, /ready/ bit.
--   -&gt; ( <a>Signal</a> dom o   -- Outgoing data.
--      , <a>Signal</a> dom oEn -- Flagged with a single /valid/ bit.
--      , <a>Signal</a> dom iEn -- Outgoing back-pressure, /ready/ bit.
--      )
--   </pre>
--   
--   A circuit adhering to the <a>DataFlow</a> type should:
--   
--   <ul>
--   <li>Not consume data when validity is deasserted.</li>
--   <li>Only update its output when readiness is asserted.</li>
--   </ul>
liftDF :: (Signal dom i -> Signal dom Bool -> Signal dom Bool -> (Signal dom o, Signal dom Bool, Signal dom Bool)) -> DataFlow dom Bool Bool i o

-- | Create a <a>DataFlow</a> circuit where the given function <tt>f</tt>
--   operates on the data, and the synchronization channels are passed
--   unaltered.
pureDF :: (i -> o) -> DataFlow dom Bool Bool i o

-- | Create a <a>DataFlow</a> circuit from a Mealy machine description as
--   those of <a>Clash.Prelude.Mealy</a>
mealyDF :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> (s, o)) -> s -> DataFlow dom Bool Bool i o

-- | Create a <a>DataFlow</a> circuit from a Moore machine description as
--   those of <a>Clash.Prelude.Moore</a>
mooreDF :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> (s -> o) -> s -> DataFlow dom Bool Bool i o

-- | Create a FIFO buffer adhering to the <a>DataFlow</a> protocol. Can be
--   filled with initial content.
--   
--   To create a FIFO of size 4, with two initial values 2 and 3 you would
--   write:
--   
--   <pre>
--   fifo4 = <a>fifoDF</a> d4 (2 :&gt; 3 :&gt; Nil)
--   </pre>
fifoDF :: forall addrSize m n a dom. (KnownDomain dom, NFDataX a, KnownNat addrSize, KnownNat n, KnownNat m, (m + n) ~ (2 ^ addrSize)) => Clock dom -> Reset dom -> Enable dom -> SNat (m + n) -> Vec m a -> DataFlow dom Bool Bool a a

-- | Identity circuit
--   
idDF :: DataFlow dom en en a a

-- | Sequential composition of two <a>DataFlow</a> circuits.
--   
seqDF :: DataFlow dom aEn bEn a b -> DataFlow dom bEn cEn b c -> DataFlow dom aEn cEn a c

-- | Apply the circuit to the first halve of the communication channels,
--   leave the second halve unchanged.
--   
firstDF :: DataFlow dom aEn bEn a b -> DataFlow dom (aEn, cEn) (bEn, cEn) (a, c) (b, c)

-- | Swap the two communication channels.
--   
swapDF :: DataFlow dom (aEn, bEn) (bEn, aEn) (a, b) (b, a)

-- | Apply the circuit to the second halve of the communication channels,
--   leave the first halve unchanged.
--   
secondDF :: DataFlow dom aEn bEn a b -> DataFlow dom (cEn, aEn) (cEn, bEn) (c, a) (c, b)

-- | Compose two <a>DataFlow</a> circuits in parallel.
--   
parDF :: DataFlow dom aEn bEn a b -> DataFlow dom cEn dEn c d -> DataFlow dom (aEn, cEn) (bEn, dEn) (a, c) (b, d)

-- | Compose <i>n</i> <a>DataFlow</a> circuits in parallel.
parNDF :: KnownNat n => Vec n (DataFlow dom aEn bEn a b) -> DataFlow dom (Vec n aEn) (Vec n bEn) (Vec n a) (Vec n b)

-- | Feed back the second halve of the communication channel. The feedback
--   loop is buffered by a <a>fifoDF</a> circuit.
--   
--   So given a circuit <i>h</i> with two synchronization channels:
--   
--   <pre>
--   <b>h</b> :: <a>DataFlow</a> (Bool,Bool) (Bool,Bool) (a,d) (b,d)
--   </pre>
--   
--   Feeding back the <i>d</i> part (including its synchronization
--   channels) results in:
--   
--   <pre>
--   <a>loopDF</a> d4 Nil h
--   </pre>
--   
--   
--   When you have a circuit <tt>h'</tt>, with only a single
--   synchronization channel:
--   
--   <pre>
--   <b>h'</b> :: <a>DataFlow</a> Bool Bool (a,d) (b,d)
--   </pre>
--   
--   and you want to compose <i>h'</i> in a feedback loop, the following
--   will not work:
--   
--   <pre>
--   f `<tt><a>seqDF</a></tt>` (<a>loopDF</a> d4 Nil h') `<tt><a>seqDF</a></tt>` g
--   </pre>
--   
--   The circuits <tt>f</tt>, <tt>h</tt>, and <tt>g</tt>, must operate in
--   <i>lock-step</i> because the <i>h'</i> circuit only has a single
--   synchronization channel. Consequently, there should only be progress
--   when all three circuits are producing <i>valid</i> data and all three
--   circuits are <i>ready</i> to receive new data. We need to compose
--   <i>h'</i> with the <a>lockStep</a> and <a>stepLock</a> functions to
--   achieve the <i>lock-step</i> operation.
--   
--   <pre>
--   f `<tt><a>seqDF</a></tt>` (<a>lockStep</a> `<tt><a>seqDF</a></tt>` <a>loopDF</a> d4 Nil h' `<tt><a>seqDF</a></tt>` <a>stepLock</a>) `<tt><a>seqDF</a></tt>` g
--   </pre>
--   
loopDF :: (KnownDomain dom, NFDataX d, KnownNat m, KnownNat n, KnownNat addrSize, (m + n) ~ (2 ^ addrSize)) => Clock dom -> Reset dom -> Enable dom -> SNat (m + n) -> Vec m d -> DataFlow dom (Bool, Bool) (Bool, Bool) (a, d) (b, d) -> DataFlow dom Bool Bool a b

-- | Feed back the second halve of the communication channel. Unlike
--   <a>loopDF</a>, the feedback loop is <i>not</i> buffered.
loopDF_nobuf :: DataFlow dom (Bool, Bool) (Bool, Bool) (a, d) (b, d) -> DataFlow dom Bool Bool a b

-- | Reduce or extend the synchronization granularity of parallel
--   compositions.
class LockStep a b

-- | Reduce the synchronization granularity to a single <a>Bool</a>ean
--   value.
--   
--   Given:
--   
--   <pre>
--   <b>f</b> :: <a>DataFlow</a> Bool Bool a b
--   <b>g</b> :: <a>DataFlow</a> Bool Bool c d
--   <b>h</b> :: <a>DataFlow</a> Bool Bool (b,d) (p,q)
--   </pre>
--   
--   We <i>cannot</i> simply write:
--   
--   <pre>
--   (f `<tt><a>parDF</a></tt>` g) `<tt><a>seqDF</a></tt>` h
--   </pre>
--   
--   because, <tt>f `parDF` g</tt>, has type, <tt><a>DataFlow</a>
--   (Bool,Bool) (Bool,Bool) (a,c) (b,d)</tt>, which does not match the
--   expected synchronization granularity of <tt>h</tt>. We need a circuit
--   in between that has the type:
--   
--   <pre>
--   <a>DataFlow</a> (Bool,Bool) Bool (b,d) (b,d)
--   </pre>
--   
--   Simply <a>&amp;&amp;</a>-ing the <i>valid</i> signals in the forward
--   direction, and duplicating the <i>ready</i> signal in the backward
--   direction is however not enough. We also need to make sure that
--   <tt>f</tt> does not update its output when <tt>g</tt>'s output is
--   invalid and visa versa, as <tt>h</tt> can only consume its input when
--   both <tt>f</tt> and <tt>g</tt> are producing valid data. <tt>g</tt>'s
--   <i>ready</i> port is hence only asserted when <tt>h</tt> is ready and
--   <tt>f</tt> is producing <i>valid</i> data. And <tt>f</tt>'s ready port
--   is only asserted when <tt>h</tt> is ready and <tt>g</tt> is producing
--   valid data. <tt>f</tt> and <tt>g</tt> will hence be proceeding in
--   <i>lock-step</i>.
--   
--   The <a>lockStep</a> function ensures that all synchronization signals
--   are properly connected:
--   
--   <pre>
--   (f `<tt><a>parDF</a></tt>` g) `<tt><a>seqDF</a></tt>` <a>lockStep</a> `<tt><a>seqDF</a></tt>` h
--   </pre>
--   
--   
--   <b>Note 1</b>: ensure that the components that you are synchronizing
--   have buffered/delayed <tt>ready</tt> and <tt>valid</tt> signals, or
--   <a>lockStep</a> has the potential to introduce combinational loops.
--   You can do this by placing <a>fifoDF</a>s on the parallel channels.
--   Extending the above example, you would write:
--   
--   <pre>
--   ((f `<tt><a>seqDF</a></tt>` <a>fifoDF</a> d4 Nil) `<tt><a>parDF</a></tt>` (g `<tt><a>seqDF</a></tt>` <a>fifoDF</a> d4 Nil)) `<tt><a>seqDF</a></tt>` <a>lockStep</a> `<tt><a>seqDF</a></tt>` h
--   </pre>
--   
--   <b>Note 2</b>: <a>lockStep</a> works for arbitrarily nested tuples.
--   That is:
--   
--   <pre>
--   p :: <a>DataFlow</a> Bool Bool ((b,d),d) z
--   
--   q :: <a>DataFlow</a> ((Bool,Bool),Bool) ((Bool,Bool),Bool) ((a,c),c) ((b,d),d)
--   q = f `<tt><a>parDF</a></tt>` g `<tt><a>parDF</a></tt>` g
--   
--   r = q `<tt><a>seqDF</a></tt>` <a>lockStep</a> `<tt><a>seqDF</a></tt>` p
--   </pre>
--   
--   Does the right thing.
lockStep :: LockStep a b => DataFlow dom a Bool b b

-- | Extend the synchronization granularity from a single <a>Bool</a>ean
--   value.
--   
--   Given:
--   
--   <pre>
--   <b>f</b> :: <a>DataFlow</a> Bool Bool a b
--   <b>g</b> :: <a>DataFlow</a> Bool Bool c d
--   <b>h</b> :: <a>DataFlow</a> Bool Bool (p,q) (a,c)
--   </pre>
--   
--   We <i>cannot</i> simply write:
--   
--   <pre>
--   h `<tt><a>seqDF</a></tt>` (f `<tt><a>parDF</a></tt>` g)
--   </pre>
--   
--   because, <tt>f `parDF` g</tt>, has type, <tt><a>DataFlow</a>
--   (Bool,Bool) (Bool,Bool) (a,c) (b,d)</tt>, which does not match the
--   expected synchronization granularity of <tt>h</tt>. We need a circuit
--   in between that has the type:
--   
--   <pre>
--   <a>DataFlow</a> Bool (Bool,Bool) (a,c) (a,c)
--   </pre>
--   
--   Simply <a>&amp;&amp;</a>-ing the <i>ready</i> signals in the backward
--   direction, and duplicating the <i>valid</i> signal in the forward
--   direction is however not enough. We need to make sure that <tt>f</tt>
--   does not consume values when <tt>g</tt> is not <i>ready</i> and visa
--   versa, because <tt>h</tt> cannot update the values of its output tuple
--   independently. <tt>f</tt>'s <i>valid</i> port is hence only asserted
--   when <tt>h</tt> is valid and <tt>g</tt> is ready to receive new
--   values. <tt>g</tt>'s <i>valid</i> port is only asserted when
--   <tt>h</tt> is valid and <tt>f</tt> is ready to receive new values.
--   <tt>f</tt> and <tt>g</tt> will hence be proceeding in
--   <i>lock-step</i>.
--   
--   The <a>stepLock</a> function ensures that all synchronization signals
--   are properly connected:
--   
--   <pre>
--   h `<tt><a>seqDF</a></tt>` <a>stepLock</a> `<tt><a>seqDF</a></tt>` (f `<tt><a>parDF</a></tt>` g)
--   </pre>
--   
--   
--   <b>Note 1</b>: ensure that the components that you are synchronizing
--   have buffered/delayed <tt>ready</tt> and <tt>valid</tt> signals, or
--   <a>stepLock</a> has the potential to introduce combinational loops.
--   You can do this by placing <a>fifoDF</a>s on the parallel channels.
--   Extending the above example, you would write:
--   
--   <pre>
--   h `<tt><a>seqDF</a></tt>` <a>stepLock</a> `<tt><a>seqDF</a></tt>` ((<a>fifoDF</a> d4 Nil `<tt><a>seqDF</a></tt>` f) `<tt><a>parDF</a></tt>` (<a>fifoDF</a> d4 Nil `<tt><a>seqDF</a></tt>` g))
--   </pre>
--   
--   <b>Note 2</b>: <a>stepLock</a> works for arbitrarily nested tuples.
--   That is:
--   
--   <pre>
--   p :: <a>DataFlow</a> Bool Bool z ((a,c),c)
--   
--   q :: <a>DataFlow</a> ((Bool,Bool),Bool) ((Bool,Bool),Bool) ((a,c),c) ((b,d),d)
--   q = f `<tt><a>parDF</a></tt>` g `<tt><a>parDF</a></tt>` g
--   
--   r = p `<tt><a>seqDF</a></tt>` <a>stepLock</a> `<tt><a>seqDF</a></tt>` q
--   </pre>
--   
--   Does the right thing.
stepLock :: LockStep a b => DataFlow dom Bool a b b
instance Clash.Prelude.DataFlow.LockStep GHC.Types.Bool c
instance (Clash.Prelude.DataFlow.LockStep a x, Clash.Prelude.DataFlow.LockStep b y) => Clash.Prelude.DataFlow.LockStep (a, b) (x, y)
instance (Clash.Prelude.DataFlow.LockStep en a, GHC.TypeNats.KnownNat n) => Clash.Prelude.DataFlow.LockStep (Clash.Sized.Vector.Vec n en) (Clash.Sized.Vector.Vec n a)


-- | <h1>Initializing a block RAM with a data file </h1>
--   
--   Block RAM primitives that can be initialized with a data file. The BNF
--   grammar for this data file is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned numbers <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   Such a file can be produced with <a>memFile</a>:
--   
--   <pre>
--   writeFile "memory.bin" (memFile Nothing [7 :: Unsigned 9 .. 13])
--   </pre>
--   
--   We can instantiate a block RAM using the contents of the file above
--   like so:
--   
--   <pre>
--   f :: (HiddenClock dom, HiddenEnable dom)
--     =&gt; Signal dom (Unsigned 3)
--     -&gt; Signal dom (Unsigned 9)
--   f rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>blockRamFile</a> d7 "memory.bin" rd (pure Nothing)
--   </pre>
--   
--   In the example above, we basically treat the block RAM as a
--   synchronous ROM. We can see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g :: (HiddenClock dom, HiddenEnable dom)
--      =&gt; Signal dom (Unsigned 3)
--      -&gt; Signal dom (Unsigned 6,Signed 3)
--   g clk rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>blockRamFile</a> d7 "memory.bin" rd (pure Nothing)
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Prelude.BlockRam.File

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamFile</a> size
--   file) rd wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFile :: (KnownNat m, Enum addr, NFDataX addr, HiddenClock dom, HiddenEnable dom, HasCallStack) => SNat n -> FilePath -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamFilePow2</a> file)
--   rd wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall dom n m. (KnownNat m, KnownNat n, HiddenClock dom, HiddenEnable dom, HasCallStack) => FilePath -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Convert data to the <a>String</a> contents of a memory file.
--   
--   <ul>
--   <li><b>NB</b>: Not synthesizable</li>
--   <li>The following document the several ways to instantiate components
--   with
--   files:<ul><li><a>Clash.Prelude.BlockRam.File#usingramfiles</a></li><li><a>Clash.Prelude.ROM.File#usingromfiles</a></li><li><a>Clash.Explicit.BlockRam.File#usingramfiles</a></li><li><a>Clash.Explicit.ROM.File#usingromfiles</a></li></ul></li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
--   
--   <h1>Example</h1>
--   
--   The <tt>Maybe</tt> datatype has don't care bits, where the actual
--   value does not matter. But the bits need a defined value in the
--   memory. Either 0 or 1 can be used, and both are valid representations
--   of the data.
--   
--   <pre>
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8]
--   
--   &gt;&gt;&gt; mapM_ (putStrLn . show . pack) es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 0) es)
--   000000000
--   100000111
--   100001000
--   
--   &gt;&gt;&gt; putStr (memFile (Just 1) es)
--   011111111
--   100000111
--   100001000
--   </pre>
memFile :: forall a f. (BitPack a, Foldable f, HasCallStack) => Maybe Bit -> f a -> String


-- | <h1>Efficient bundling of initial RAM content with the compiled
--   code</h1>
--   
--   Leveraging Template Haskell, the initial content for the block RAM
--   components in this module is stored alongside the compiled Haskell
--   code. It covers use cases where passing the initial content as a
--   <a>Vec</a> turns out to be problematically slow.
--   
--   The data is stored efficiently, with very little overhead (worst-case
--   7%, often no overhead at all).
--   
--   Unlike <a>Clash.Prelude.BlockRam.File</a>,
--   <a>Clash.Prelude.BlockRam.Blob</a> generates practically the same HDL
--   as <a>Clash.Prelude.BlockRam</a> and is compatible with all tools
--   consuming the generated HDL.
module Clash.Prelude.BlockRam.Blob

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamBlob</a> content)
--   rd wrM</tt>.</li>
--   </ul>
blockRamBlob :: forall dom addr m n. (HiddenClock dom, HiddenEnable dom, Enum addr, NFDataX addr) => MemBlob n m -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamBlobPow2</a>
--   content) rd wrM</tt>.</li>
--   </ul>
blockRamBlobPow2 :: forall dom m n. (HiddenClock dom, HiddenEnable dom, KnownNat n) => MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]


-- | Block RAM primitives
--   
--   <h1>Using RAMs </h1>
--   
--   We will show a rather elaborate example on how you can, and why you
--   might want to use <a>blockRam</a>s. We will build a "small" CPU +
--   Memory + Program ROM where we will slowly evolve to using
--   <a>blockRam</a>s. Note that the code is <i>not</i> meant as a de-facto
--   standard on how to do CPU design in Clash.
--   
--   We start with the definition of the Instructions, Register names and
--   machine codes:
--   
--   <pre>
--   {-# LANGUAGE RecordWildCards, TupleSections, DeriveAnyClass #-}
--   
--   module CPU where
--   
--   import Clash.Prelude
--   
--   type InstrAddr = Unsigned 8
--   type MemAddr   = Unsigned 5
--   type Value     = Signed 8
--   
--   data Instruction
--     = Compute Operator Reg Reg Reg
--     | Branch Reg Value
--     | Jump Value
--     | Load MemAddr Reg
--     | Store Reg MemAddr
--     | Nop
--     deriving (Eq, Show, Generic, NFDataX)
--   
--   data Reg
--     = Zero
--     | PC
--     | RegA
--     | RegB
--     | RegC
--     | RegD
--     | RegE
--     deriving (Eq, Show, Enum, Generic, NFDataX)
--   
--   data Operator = Add | Sub | Incr | Imm | CmpGt
--     deriving (Eq, Show, Generic, NFDataX)
--   
--   data MachCode
--     = MachCode
--     { inputX  :: Reg
--     , inputY  :: Reg
--     , result  :: Reg
--     , aluCode :: Operator
--     , ldReg   :: Reg
--     , rdAddr  :: MemAddr
--     , wrAddrM :: Maybe MemAddr
--     , jmpM    :: Maybe Value
--     }
--   
--   nullCode =
--     MachCode
--       { inputX = Zero
--       , inputY = Zero
--       , result = Zero
--       , aluCode = Imm
--       , ldReg = Zero
--       , rdAddr = 0
--       , wrAddrM = Nothing
--       , jmpM = Nothing
--       }
--   </pre>
--   
--   Next we define the CPU and its ALU:
--   
--   <pre>
--   cpu
--     :: Vec 7 Value          -- ^ Register bank
--     -&gt; (Value,Instruction)  -- ^ (Memory output, Current instruction)
--     -&gt; ( Vec 7 Value
--        , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--        )
--   cpu regbank (memOut, instr) =
--     (regbank', (rdAddr, (,aluOut) <a>&lt;$&gt;</a> wrAddrM, bitCoerce ipntr))
--    where
--     -- Current instruction pointer
--     ipntr = regbank <a>!!</a> PC
--   
--     -- Decoder
--     (MachCode {..}) = case instr of
--       Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--       Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--       Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--       Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--       Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--       Nop                  -&gt; nullCode
--   
--     -- ALU
--     regX   = regbank <a>!!</a> inputX
--     regY   = regbank <a>!!</a> inputY
--     aluOut = alu aluCode regX regY
--   
--     -- next instruction
--     nextPC =
--       case jmpM of
--         Just a | aluOut /= 0 -&gt; ipntr + a
--         _                    -&gt; ipntr + 1
--   
--     -- update registers
--     regbank' = <a>replace</a> Zero   0
--              $ <a>replace</a> PC     nextPC
--              $ <a>replace</a> result aluOut
--              $ <a>replace</a> ldReg  memOut
--              $ regbank
--   
--   alu Add   x y = x + y
--   alu Sub   x y = x - y
--   alu Incr  x _ = x + 1
--   alu Imm   x _ = x
--   alu CmpGt x y = if x &gt; y then 1 else 0
--   </pre>
--   
--   We initially create a memory out of simple registers:
--   
--   <pre>
--   dataMem
--     :: HiddenClockResetEnable dom
--     =&gt; Signal dom MemAddr
--     -- ^ Read address
--     -&gt; Signal dom (Maybe (MemAddr,Value))
--     -- ^ (write address, data in)
--     -&gt; Signal dom Value
--     -- ^ data out
--   dataMem rd wrM =
--     <a>mealy</a> dataMemT (<a>replicate</a> d32 0) (bundle (rd,wrM))
--    where
--     dataMemT mem (rd,wrM) = (mem',dout)
--       where
--         dout = mem <a>!!</a> rd
--         mem' =
--           case wrM of
--             Just (wr,din) -&gt; <a>replace</a> wr din mem
--             _             -&gt; mem
--   </pre>
--   
--   And then connect everything:
--   
--   <pre>
--   system
--     :: ( KnownNat n
--        , HiddenClockResetEnable dom
--        )
--     =&gt; Vec n Instruction
--     -&gt; Signal dom Value
--   system instrs = memOut
--    where
--     memOut = dataMem rdAddr dout
--     (rdAddr, dout, ipntr) = <a>mealyB</a> cpu (<a>replicate</a> d7 0) (memOut,instr)
--     instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Create a simple program that calculates the GCD of 4 and 6:
--   
--   <pre>
--   -- Compute GCD of 4 and 6
--   prog = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   And test our system:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 32 (system prog)
--   [0,0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   to see that our system indeed calculates that the GCD of 6 and 4 is 2.
--   
--   <h3>Improvement 1: using <tt>asyncRam</tt></h3>
--   
--   As you can see, it's fairly straightforward to build a memory using
--   registers and read (<a>!!</a>) and write (<a>replace</a>) logic. This
--   might however not result in the most efficient hardware structure,
--   especially when building an ASIC.
--   
--   Instead it is preferable to use the <a>asyncRam</a> function which has
--   the potential to be translated to a more efficient structure:
--   
--   <pre>
--   system2
--     :: ( KnownNat n
--        , HiddenClockResetEnable dom  )
--     =&gt; Vec n Instruction
--     -&gt; Signal dom Value
--   system2 instrs = memOut
--    where
--     memOut = <a>asyncRam</a> d32 rdAddr dout
--     (rdAddr,dout,ipntr) = <a>mealyB</a> cpu (<a>replicate</a> d7 0) (memOut,instr)
--     instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Again, we can simulate our system and see that it works. This time
--   however, we need to disregard the first few output samples, because
--   the initial content of an <a>asyncRam</a> is <i>undefined</i>, and
--   consequently, the first few output samples are also <i>undefined</i>.
--   We use the utility function <a>printX</a> to conveniently filter out
--   the undefinedness and replace it with the string <tt>"undefined"</tt>
--   in the first few leading outputs.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN @System 32 (system2 prog)
--   [undefined,undefined,undefined,undefined,undefined,undefined,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   <h3>Improvement 2: using <tt>blockRam</tt></h3>
--   
--   Finally we get to using <a>blockRam</a>. On FPGAs, <a>asyncRam</a>
--   will be implemented in terms of LUTs, and therefore take up logic
--   resources. FPGAs also have large(r) memory structures called <i>block
--   RAMs</i>, which are preferred, especially as the memories we need for
--   our application get bigger. The <a>blockRam</a> function will be
--   translated to such a <i>block RAM</i>.
--   
--   One important aspect of block RAMs is that they have a
--   <i>synchronous</i> read port, meaning that, unlike the behavior of
--   <a>asyncRam</a>, given a read address <tt>r</tt> at time <tt>t</tt>,
--   the value <tt>v</tt> in the RAM at address <tt>r</tt> is only
--   available at time <tt>t+1</tt>.
--   
--   For us that means we need to change the design of our CPU. Right now,
--   upon a load instruction we generate a read address for the memory, and
--   the value at that read address is immediately available to be put in
--   the register bank. Because we will be using a block RAM, the value is
--   delayed until the next cycle. Thus, we will need to also delay the
--   register address to which the memory address is loaded:
--   
--   <pre>
--   cpu2
--     :: (Vec 7 Value,Reg)    -- ^ (Register bank, Load reg addr)
--     -&gt; (Value,Instruction)  -- ^ (Memory output, Current instruction)
--     -&gt; ( (Vec 7 Value, Reg)
--        , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--        )
--   cpu2 (regbank,ldRegD) (memOut,instr) =
--     ((regbank', ldRegD'), (rdAddr, (,aluOut) <a>&lt;$&gt;</a> wrAddrM, bitCoerce ipntr))
--    where
--     -- Current instruction pointer
--     ipntr = regbank <a>!!</a> PC
--   
--     -- Decoder
--     (MachCode {..}) = case instr of
--       Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--       Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--       Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--       Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--       Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--       Nop                  -&gt; nullCode
--   
--     -- ALU
--     regX   = regbank <a>!!</a> inputX
--     regY   = regbank <a>!!</a> inputY
--     aluOut = alu aluCode regX regY
--   
--     -- next instruction
--     nextPC =
--       case jmpM of
--         Just a | aluOut /= 0 -&gt; ipntr + a
--         _                    -&gt; ipntr + 1
--   
--     -- update registers
--     ldRegD'  = ldReg  -- Delay the ldReg by 1 cycle
--     regbank' = <a>replace</a> Zero   0
--              $ <a>replace</a> PC     nextPC
--              $ <a>replace</a> result aluOut
--              $ <a>replace</a> ldRegD memOut
--              $ regbank
--   </pre>
--   
--   We can now finally instantiate our system with a <a>blockRam</a>:
--   
--   <pre>
--   system3
--     :: (KnownNat n
--        , HiddenClockResetEnable dom  )
--     =&gt; Vec n Instruction
--     -&gt; Signal dom Value
--   system3 instrs = memOut
--    where
--     memOut = <a>blockRam</a> (replicate d32 0) rdAddr dout
--     (rdAddr,dout,ipntr) = <a>mealyB</a> cpu2 ((<a>replicate</a> d7 0),Zero) (memOut,instr)
--     instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   We are, however, not done. We will also need to update our program.
--   The reason being that values that we try to load in our registers
--   won't be loaded into the register until the next cycle. This is a
--   problem when the next instruction immediately depends on this memory
--   value. In our case, this was only the case when we loaded the value
--   <tt>6</tt>, which was stored at address <tt>1</tt>, into
--   <tt>RegB</tt>. Our updated program is thus:
--   
--   <pre>
--   prog2 = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          Nop :&gt; -- Extra NOP
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   When we simulate our system we see that it works. This time again, we
--   need to disregard the first sample, because the initial output of a
--   <a>blockRam</a> is <i>undefined</i>. We use the utility function
--   <a>printX</a> to conveniently filter out the undefinedness and replace
--   it with the string <tt>"undefined"</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN @System 34 (system3 prog2)
--   [undefined,0,0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   This concludes the short introduction to using <a>blockRam</a>.
module Clash.Prelude.BlockRam

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRam</a> inits) rd
--   wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFile</a> and
--   <a>blockRamBlob</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram40
--     :: <a>HiddenClock</a> dom
--     =&gt; <a>Signal</a> dom (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram40 = <a>blockRam</a> (<a>replicate</a> d40 1)
--   </pre>
blockRam :: (HasCallStack, HiddenClock dom, HiddenEnable dom, NFDataX a, Enum addr, NFDataX addr) => Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamPow2</a> inits) rd
--   wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFilePow2</a> and
--   <a>blockRamBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram32
--     :: <a>HiddenClock</a> dom
--     =&gt; <a>Signal</a> dom (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram32 = <a>blockRamPow2</a> (<a>replicate</a> d32 1)
--   </pre>
blockRamPow2 :: (HasCallStack, HiddenClock dom, HiddenEnable dom, NFDataX a, KnownNat n) => Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that has no default values set. May be
--   cleared to an arbitrary state using a reset function.
blockRamU :: forall n dom a r addr. (HasCallStack, HiddenClockResetEnable dom, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => ResetStrategy r -> SNat n -> (Index n -> a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that is initialized with the same value
--   on all memory positions
blockRam1 :: forall n dom a r addr. (HasCallStack, HiddenClockResetEnable dom, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => ResetStrategy r -> SNat n -> a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a
data ResetStrategy (r :: Bool)
[ClearOnReset] :: ResetStrategy 'True
[NoClearOnReset] :: ResetStrategy 'False

-- | Create a read-after-write block RAM from a read-before-write one
--   
--   <pre>
--   &gt;&gt;&gt; :t readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--   readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--     :: ...
--        ...
--        ...
--        ...
--        ... =&gt;
--        Signal dom addr -&gt; Signal dom (Maybe (addr, a)) -&gt; Signal dom a
--   </pre>
readNew :: (HiddenClockResetEnable dom, NFDataX a, Eq addr) => (Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Produces vendor-agnostic HDL that will be inferred as a true dual-port
--   block RAM
--   
--   Any value that is being written on a particular port is also the value
--   that will be read on that port, i.e. the same-port read/write behavior
--   is: WriteFirst. For mixed-port read/write, when port A writes to the
--   address port B reads from, the output of port B is undefined, and vice
--   versa.
trueDualPortBlockRam :: forall nAddrs dom a. (HasCallStack, KnownNat nAddrs, HiddenClock dom, NFDataX a) => Signal dom (RamOp nAddrs a) -> Signal dom (RamOp nAddrs a) -> (Signal dom a, Signal dom a)

-- | Port operation
data RamOp n a

-- | Read from address
RamRead :: Index n -> RamOp n a

-- | Write data to address
RamWrite :: Index n -> a -> RamOp n a

-- | No operation
RamNoOp :: RamOp n a


module Clash.Explicit.Testbench

-- | Compares the first two <a>Signal</a>s for equality and logs a warning
--   when they are not equal. The second <a>Signal</a> is considered the
--   expected value. This function simply returns the third <a>Signal</a>
--   unaltered as its result. This function is used by
--   <a>outputVerifier</a>.
--   
--   <h3>Usage in <tt>clashi</tt> </h3>
--   
--   <b>NB</b>: When simulating a component that uses <a>assert</a> in
--   <tt>clashi</tt>, usually, the warnings are only logged the first time
--   the component is simulated. Issuing <tt>:reload</tt> in
--   <tt>clashi</tt> will discard the cached result of the computation, and
--   warnings will once again be emitted.
--   
--   <b>NB</b>: This function <i>can</i> be used in synthesizable designs.
assert :: (KnownDomain dom, Eq a, ShowX a) => Clock dom -> Reset dom -> String -> Signal dom a -> Signal dom a -> Signal dom b -> Signal dom b

-- | The same as <a>assert</a>, but can handle don't care bits in its
--   expected value.
assertBitVector :: (KnownDomain dom, KnownNat n) => Clock dom -> Reset dom -> String -> Signal dom (BitVector n) -> Signal dom (BitVector n) -> Signal dom b -> Signal dom b

-- | Ignore signal for a number of cycles, while outputting a static value.
ignoreFor :: forall dom n a. KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> SNat n -> a -> Signal dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   testInput
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; <a>Signal</a> dom Int
--   testInput clk rst = <a>stimuliGenerator</a> clk rst $(<a>listToVecTH</a> [(1::Int),3..21])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 14 (testInput systemClockGen resetGen)
--   [1,1,3,5,7,9,11,13,15,17,19,21,21,21]
--   </pre>
stimuliGenerator :: forall l dom a. (KnownNat l, KnownDomain dom) => Clock dom -> Reset dom -> Vec l a -> Signal dom a

-- | Clock generator to be used in the <i>testBench</i> function.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem en = tbClockGen @System en
--   </pre>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   module Example where
--   
--   import <a>Clash.Explicit.Prelude</a>
--   import <a>Clash.Explicit.Testbench</a>
--   
--   -- Fast domain: twice as fast as "Slow"
--   <a>createDomain</a> <a>vSystem</a>{vName="Fast", vPeriod=10}
--   
--   -- Slow domain: twice as slow as "Fast"
--   <a>createDomain</a> <a>vSystem</a>{vName="Slow", vPeriod=20}
--   
--   topEntity
--     :: <a>Clock</a> "Fast"
--     -&gt; <a>Reset</a> "Fast"
--     -&gt; <a>Enable</a> "Fast"
--     -&gt; <a>Clock</a> "Slow"
--     -&gt; <a>Signal</a> "Fast" (Unsigned 8)
--     -&gt; <a>Signal</a> "Slow" (Unsigned 8, Unsigned 8)
--   topEntity clk1 rst1 en1 clk2 i =
--     let h = register clk1 rst1 en1 0 (register clk1 rst1 en1 0 i)
--         l = register clk1 rst1 en1 0 i
--     in  unsafeSynchronizer clk1 clk2 (bundle (h, l))
--   
--   testBench
--     :: <a>Signal</a> "Slow" Bool
--   testBench = done
--     where
--       testInput      = <a>stimuliGenerator</a> clkA1 rstA1 $(<a>listToVecTH</a> [1::Unsigned 8,2,3,4,5,6,7,8])
--       expectedOutput = <a>outputVerifier</a>   clkB2 rstB2 $(<a>listToVecTH</a> [(0,0) :: (Unsigned 8, Unsigned 8),(1,2),(3,4),(5,6),(7,8)])
--       done           = expectedOutput (topEntity clkA1 rstA1 enableGen clkB2 testInput)
--       notDone        = not &lt;$&gt; done
--       clkA1          = <a>tbClockGen</a> @"Fast" (unsafeSynchronizer clkB2 clkA1 notDone)
--       clkB2          = <a>tbClockGen</a> @"Slow" notDone
--       rstA1          = <a>resetGen</a> @"Fast"
--       rstB2          = <a>resetGen</a> @"Slow"
--   </pre>
tbClockGen :: KnownDomain testDom => Signal testDom Bool -> Clock testDom

-- | Enable signal that's always enabled. Because it has a blackbox
--   definition this enable signal is opaque to other blackboxes. It will
--   therefore never be optimized away.
tbEnableGen :: Enable tag

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: Can be used in the <i>testBench</i> function
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst
--       clk            = <a>tbSystemClockGen</a> (not &lt;$&gt; done)
--       rst            = systemResetGen
--   </pre>
tbSystemClockGen :: Signal System Bool -> Clock System

-- | Convert a single-ended clock to a differential clock
--   
--   The <a>tbClockGen</a> function generates a single-ended clock. This
--   function will output the two phases of a differential clock
--   corresponding to that single-ended clock.
--   
--   This function is only meant to be used in the <i>testBench</i>
--   function, not to create a differential output in hardware.
--   
--   Example:
--   
--   <pre>
--   clk = clockToDiffClock $ tbClockGen (not &lt;$&gt; done)
--   </pre>
clockToDiffClock :: KnownDomain dom => Clock dom -> DiffClock dom

-- | Compare a signal (coming from a circuit) to a vector of samples. If a
--   sample from the signal is not equal to the corresponding sample in the
--   vector, print to stderr and continue testing. This function is
--   synthesizable in the sense that HDL simulators will run it. If
--   <tt>testDom</tt> and <tt>circuitDom</tt> refer to the same domain, it
--   can also be synthesized into hardware.
--   
--   <b>NB</b>: This function uses <a>assert</a>. When simulating this
--   function in <tt>clashi</tt>, read the <a>note</a>.
--   
--   Example:
--   
--   <pre>
--   expectedOutput
--     :: Clock dom -&gt; Reset dom
--     -&gt; <a>Signal</a> dom Int -&gt; <a>Signal</a> dom Bool
--   expectedOutput clk rst = <a>outputVerifier</a> clk rst $(<a>listToVecTH</a> ([70,99,2,3,4,5,7,8,9,10]::[Int]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; sampleN 12 (expectedOutput systemClockGen resetGen (fromList (0:[0..10] List.++ [10,10,10])))
--   
--   cycle(&lt;Clock: System&gt;): 0, outputVerifier
--   expected value: 70, not equal to actual value: 0
--   [False
--   cycle(&lt;Clock: System&gt;): 1, outputVerifier
--   expected value: 70, not equal to actual value: 0
--   ,False
--   cycle(&lt;Clock: System&gt;): 2, outputVerifier
--   expected value: 99, not equal to actual value: 1
--   ,False,False,False,False,False
--   cycle(&lt;Clock: System&gt;): 7, outputVerifier
--   expected value: 7, not equal to actual value: 6
--   ,False
--   cycle(&lt;Clock: System&gt;): 8, outputVerifier
--   expected value: 8, not equal to actual value: 7
--   ,False
--   cycle(&lt;Clock: System&gt;): 9, outputVerifier
--   expected value: 9, not equal to actual value: 8
--   ,False
--   cycle(&lt;Clock: System&gt;): 10, outputVerifier
--   expected value: 10, not equal to actual value: 9
--   ,False,True]
--   </pre>
--   
--   If you're working with <a>BitVector</a>s containing don't care bits
--   you should use <a>outputVerifierBitVector</a>.
outputVerifier :: forall l a testDom circuitDom. (KnownNat l, KnownDomain testDom, KnownDomain circuitDom, Eq a, ShowX a, 1 <= l) => Clock testDom -> Clock circuitDom -> Reset testDom -> Vec l a -> Signal circuitDom a -> Signal testDom Bool

-- | Same as <a>outputVerifier</a> but used in cases where the test bench
--   domain and the domain of the circuit under test are the same.
outputVerifier' :: forall l a dom. (KnownNat l, KnownDomain dom, Eq a, ShowX a, 1 <= l) => Clock dom -> Reset dom -> Vec l a -> Signal dom a -> Signal dom Bool

-- | Same as <a>outputVerifier</a>, but can handle don't care bits in its
--   expected values.
outputVerifierBitVector :: forall l n testDom circuitDom. (KnownNat l, KnownNat n, KnownDomain testDom, KnownDomain circuitDom, 1 <= l) => Clock testDom -> Clock circuitDom -> Reset testDom -> Vec l (BitVector n) -> Signal circuitDom (BitVector n) -> Signal testDom Bool

-- | Same as <a>outputVerifier'</a>, but can handle don't care bits in its
--   expected values.
outputVerifierBitVector' :: forall l n dom. (KnownNat l, KnownNat n, KnownDomain dom, 1 <= l) => Clock dom -> Reset dom -> Vec l (BitVector n) -> Signal dom (BitVector n) -> Signal dom Bool

-- | Same as <a>tbClockGen</a>, but returns two clocks on potentially
--   different domains. To be used in situations where the test circuit
--   potentially operates on a different clock than the device under test.
biTbClockGen :: forall testDom circuitDom. (KnownDomain testDom, KnownDomain circuitDom) => Signal testDom Bool -> (Clock testDom, Clock circuitDom)

-- | Cross clock domains in a way that is unsuitable for hardware but good
--   enough for simulation.
--   
--   It's equal to <a>unsafeSynchronizer</a> but will warn when used
--   outside of a test bench. <a>outputVerifier</a> uses this function when
--   it needs to cross between clock domains, which will render it
--   unsuitable for synthesis, but good enough for simulating the generated
--   HDL.
unsafeSimSynchronizer :: forall dom1 dom2 a. (KnownDomain dom1, KnownDomain dom2) => Clock dom1 -> Clock dom2 -> Signal dom1 a -> Signal dom2 a
outputVerifierWith :: forall l a testDom circuitDom. (KnownNat l, KnownDomain testDom, KnownDomain circuitDom, Eq a, ShowX a, 1 <= l) => (Clock testDom -> Reset testDom -> Signal testDom a -> Signal testDom a -> Signal testDom Bool -> Signal testDom Bool) -> Clock testDom -> Clock circuitDom -> Reset testDom -> Vec l a -> Signal circuitDom a -> Signal testDom Bool


module Clash.Prelude.Testbench

-- | Compares the first two <a>Signal</a>s for equality and logs a warning
--   when they are not equal. The second <a>Signal</a> is considered the
--   expected value. This function simply returns the third <a>Signal</a>
--   unaltered as its result. This function is used by
--   <a>outputVerifier'</a>.
--   
--   <h3>Usage in <tt>clashi</tt> </h3>
--   
--   <b>NB</b>: When simulating a component that uses <a>assert</a> in
--   <tt>clashi</tt>, usually, the warnings are only logged the first time
--   the component is simulated. Issuing <tt>:reload</tt> in
--   <tt>clashi</tt> will discard the cached result of the computation, and
--   warnings will once again be emitted.
--   
--   <b>NB</b>: This function <i>can</i> be used in synthesizable designs.
assert :: (Eq a, ShowX a, HiddenClock dom, HiddenReset dom) => String -> Signal dom a -> Signal dom a -> Signal dom b -> Signal dom b

-- | The same as <a>assert</a>, but can handle don't care bits in its
--   expected value.
assertBitVector :: (KnownNat n, HiddenClock dom, HiddenReset dom) => String -> Signal dom (BitVector n) -> Signal dom (BitVector n) -> Signal dom b -> Signal dom b

-- | Ignore signal for a number of cycles, while outputting a static value.
ignoreFor :: HiddenClockResetEnable dom => SNat n -> a -> Signal dom a -> Signal dom a

-- | Compare a signal (coming from a circuit) to a vector of samples. If a
--   sample from the signal is not equal to the corresponding sample in the
--   vector, print to stderr and continue testing. This function is
--   synthesizable in the sense that HDL simulators will run it.
--   
--   <b>NB</b>: This function uses <a>assert</a>. When simulating this
--   function in <tt>clashi</tt>, read the <a>note</a>.
--   
--   Example:
--   
--   <pre>
--   expectedOutput
--     :: HiddenClockResetEnable dom
--     -&gt; <a>Signal</a> dom Int -&gt; <a>Signal</a> dom Bool
--   expectedOutput = <a>outputVerifier'</a> $(<a>listToVecTH</a> ([70,99,2,3,4,5,7,8,9,10]::[Int]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; sampleN @System 12 (expectedOutput (fromList (0:[0..10] List.++ [10,10,10])))
--   
--   cycle(&lt;Clock: System&gt;): 0, outputVerifier
--   expected value: 70, not equal to actual value: 0
--   [False
--   cycle(&lt;Clock: System&gt;): 1, outputVerifier
--   expected value: 70, not equal to actual value: 0
--   ,False
--   cycle(&lt;Clock: System&gt;): 2, outputVerifier
--   expected value: 99, not equal to actual value: 1
--   ,False,False,False,False,False
--   cycle(&lt;Clock: System&gt;): 7, outputVerifier
--   expected value: 7, not equal to actual value: 6
--   ,False
--   cycle(&lt;Clock: System&gt;): 8, outputVerifier
--   expected value: 8, not equal to actual value: 7
--   ,False
--   cycle(&lt;Clock: System&gt;): 9, outputVerifier
--   expected value: 9, not equal to actual value: 8
--   ,False
--   cycle(&lt;Clock: System&gt;): 10, outputVerifier
--   expected value: 10, not equal to actual value: 9
--   ,False,True]
--   </pre>
--   
--   If you're working with <a>BitVector</a>s containing don't care bits
--   you should use <a>outputVerifierBitVector'</a>.
outputVerifier' :: (KnownNat l, Eq a, ShowX a, HiddenClock dom, HiddenReset dom, 1 <= l) => Vec l a -> Signal dom a -> Signal dom Bool

-- | Same as <a>outputVerifier'</a>, but can handle don't care bits in its
--   expected values.
outputVerifierBitVector' :: (KnownNat l, KnownNat n, HiddenClock dom, HiddenReset dom, 1 <= l) => Vec l (BitVector n) -> Signal dom (BitVector n) -> Signal dom Bool

-- | Example:
--   
--   <pre>
--   testInput
--     :: HiddenClockResetEnable dom
--     =&gt; <a>Signal</a> dom Int
--   testInput = <a>stimuliGenerator</a> $(<a>listToVecTH</a> [(1::Int),3..21])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 13 testInput
--   [1,1,3,5,7,9,11,13,15,17,19,21,21]
--   </pre>
stimuliGenerator :: (KnownNat l, HiddenClock dom, HiddenReset dom) => Vec l a -> Signal dom a

-- | Clock generator to be used in the <i>testBench</i> function.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem en = tbClockGen @System en
--   </pre>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   module Example where
--   
--   import <a>Clash.Explicit.Prelude</a>
--   import <a>Clash.Explicit.Testbench</a>
--   
--   -- Fast domain: twice as fast as "Slow"
--   <a>createDomain</a> <a>vSystem</a>{vName="Fast", vPeriod=10}
--   
--   -- Slow domain: twice as slow as "Fast"
--   <a>createDomain</a> <a>vSystem</a>{vName="Slow", vPeriod=20}
--   
--   topEntity
--     :: <a>Clock</a> "Fast"
--     -&gt; <a>Reset</a> "Fast"
--     -&gt; <a>Enable</a> "Fast"
--     -&gt; <a>Clock</a> "Slow"
--     -&gt; <a>Signal</a> "Fast" (Unsigned 8)
--     -&gt; <a>Signal</a> "Slow" (Unsigned 8, Unsigned 8)
--   topEntity clk1 rst1 en1 clk2 i =
--     let h = register clk1 rst1 en1 0 (register clk1 rst1 en1 0 i)
--         l = register clk1 rst1 en1 0 i
--     in  unsafeSynchronizer clk1 clk2 (bundle (h, l))
--   
--   testBench
--     :: <a>Signal</a> "Slow" Bool
--   testBench = done
--     where
--       testInput      = <a>stimuliGenerator</a> clkA1 rstA1 $(<a>listToVecTH</a> [1::Unsigned 8,2,3,4,5,6,7,8])
--       expectedOutput = <a>outputVerifier</a>   clkB2 rstB2 $(<a>listToVecTH</a> [(0,0) :: (Unsigned 8, Unsigned 8),(1,2),(3,4),(5,6),(7,8)])
--       done           = expectedOutput (topEntity clkA1 rstA1 enableGen clkB2 testInput)
--       notDone        = not &lt;$&gt; done
--       clkA1          = <a>tbClockGen</a> @"Fast" (unsafeSynchronizer clkB2 clkA1 notDone)
--       clkB2          = <a>tbClockGen</a> @"Slow" notDone
--       rstA1          = <a>resetGen</a> @"Fast"
--       rstB2          = <a>resetGen</a> @"Slow"
--   </pre>
tbClockGen :: KnownDomain testDom => Signal testDom Bool -> Clock testDom

-- | Enable signal that's always enabled. Because it has a blackbox
--   definition this enable signal is opaque to other blackboxes. It will
--   therefore never be optimized away.
tbEnableGen :: Enable tag

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: Can be used in the <i>testBench</i> function
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst
--       clk            = <a>tbSystemClockGen</a> (not &lt;$&gt; done)
--       rst            = systemResetGen
--   </pre>
tbSystemClockGen :: Signal System Bool -> Clock System

-- | Convert a single-ended clock to a differential clock
--   
--   The <a>tbClockGen</a> function generates a single-ended clock. This
--   function will output the two phases of a differential clock
--   corresponding to that single-ended clock.
--   
--   This function is only meant to be used in the <i>testBench</i>
--   function, not to create a differential output in hardware.
--   
--   Example:
--   
--   <pre>
--   clk = clockToDiffClock $ tbClockGen (not &lt;$&gt; done)
--   </pre>
clockToDiffClock :: KnownDomain dom => Clock dom -> DiffClock dom

module Clash.Class.Counter.Internal

-- | <a>Counter</a> is a class that composes multiple counters into a
--   single one. It is similar to odometers found in olds cars, once all
--   counters reach their maximum they reset to zero - i.e. odometer
--   rollover. See <a>countSucc</a> and <a>countPred</a> for API usage
--   examples.
--   
--   Example use case: when driving a monitor through VGA you would like to
--   keep track at least two counters: one counting a horizontal position,
--   and one vertical. Perhaps a fancy VGA driver would also like to keep
--   track of the number of drawn frames. To do so, the three counters are
--   setup with different types. On each <i>round</i> of the horizontal
--   counter the vertical counter should be increased. On each <i>round</i>
--   of the vertical counter the frame counter should be increased. With
--   this class you could simply use the type:
--   
--   <pre>
--   (FrameCount, VerticalCount, HorizontalCount)
--   </pre>
--   
--   and have <a>countSucc</a> work as described.
--   
--   <b>NB</b>: This class exposes four functions <a>countMin</a>,
--   <a>countMax</a>, <a>countSuccOverflow</a>, and
--   <a>countPredOverflow</a>. These functions are considered an internal
--   API. Users are encouraged to use <a>countSucc</a> and
--   <a>countPred</a>.
class Counter a

-- | Value counter wraps around to on a <a>countSuccOverflow</a> overflow
countMin :: Counter a => a

-- | Value counter wraps around to on a <a>countSuccOverflow</a> overflow
countMin :: (Counter a, Bounded a) => a

-- | Value counter wraps around to on a <a>countPredOverflow</a> overflow
countMax :: Counter a => a

-- | Value counter wraps around to on a <a>countPredOverflow</a> overflow
countMax :: (Counter a, Bounded a) => a

-- | Gets the successor of <tt>a</tt>. If it overflows, the first part of
--   the tuple will be set to True and the second part wraps around to
--   <a>countMin</a>.
countSuccOverflow :: Counter a => a -> (Bool, a)

-- | Gets the successor of <tt>a</tt>. If it overflows, the first part of
--   the tuple will be set to True and the second part wraps around to
--   <a>countMin</a>.
countSuccOverflow :: (Counter a, Eq a, Enum a, Bounded a) => a -> (Bool, a)

-- | Gets the predecessor of <tt>a</tt>. If it underflows, the first part
--   of the tuple will be set to True and the second part wraps around to
--   <a>countMax</a>.
countPredOverflow :: Counter a => a -> (Bool, a)

-- | Gets the predecessor of <tt>a</tt>. If it underflows, the first part
--   of the tuple will be set to True and the second part wraps around to
--   <a>countMax</a>.
countPredOverflow :: (Counter a, Eq a, Enum a, Bounded a) => a -> (Bool, a)
instance (Clash.Class.Counter.Internal.Counter a0, Clash.Class.Counter.Internal.Counter a1, Clash.Class.Counter.Internal.Counter a2) => Clash.Class.Counter.Internal.Counter (a0, a1, a2)
instance (1 GHC.TypeNats.<= n, GHC.TypeNats.KnownNat n) => Clash.Class.Counter.Internal.Counter (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Counter.Internal.Counter (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Counter.Internal.Counter (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Counter.Internal.Counter (Clash.Sized.Internal.BitVector.BitVector n)
instance (Clash.Class.Counter.Internal.Counter a, Clash.Class.Counter.Internal.Counter b) => Clash.Class.Counter.Internal.Counter (Data.Either.Either a b)
instance (Clash.Class.Counter.Internal.Counter a0, Clash.Class.Counter.Internal.Counter a1) => Clash.Class.Counter.Internal.Counter (a0, a1)


-- | Utilities for wrapping counters consisting of multiple individual
--   counters
module Clash.Class.Counter

-- | <a>Counter</a> is a class that composes multiple counters into a
--   single one. It is similar to odometers found in olds cars, once all
--   counters reach their maximum they reset to zero - i.e. odometer
--   rollover. See <a>countSucc</a> and <a>countPred</a> for API usage
--   examples.
--   
--   Example use case: when driving a monitor through VGA you would like to
--   keep track at least two counters: one counting a horizontal position,
--   and one vertical. Perhaps a fancy VGA driver would also like to keep
--   track of the number of drawn frames. To do so, the three counters are
--   setup with different types. On each <i>round</i> of the horizontal
--   counter the vertical counter should be increased. On each <i>round</i>
--   of the vertical counter the frame counter should be increased. With
--   this class you could simply use the type:
--   
--   <pre>
--   (FrameCount, VerticalCount, HorizontalCount)
--   </pre>
--   
--   and have <a>countSucc</a> work as described.
--   
--   <b>NB</b>: This class exposes four functions <a>countMin</a>,
--   <a>countMax</a>, <a>countSuccOverflow</a>, and
--   <a>countPredOverflow</a>. These functions are considered an internal
--   API. Users are encouraged to use <a>countSucc</a> and
--   <a>countPred</a>.
class Counter a

-- | Successor of a counter.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; type T = (Unsigned 2, Unsigned 2)
--   
--   &gt;&gt;&gt; countSucc @T (1, 1)
--   (1,2)
--   
--   &gt;&gt;&gt; countSucc @T (1, 2)
--   (1,3)
--   
--   &gt;&gt;&gt; countSucc @T (1, 3)
--   (2,0)
--   
--   &gt;&gt;&gt; countSucc @T (3, 3)
--   (0,0)
--   
--   &gt;&gt;&gt; countSucc @(Index 9, Index 2) (0, 1)
--   (1,0)
--   
--   &gt;&gt;&gt; countSucc @(Either (Index 9) (Index 9)) (Left 8)
--   Right 0
--   </pre>
countSucc :: Counter a => a -> a

-- | Predecessor of a counter
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; type T = (Unsigned 2, Unsigned 2)
--   
--   &gt;&gt;&gt; countPred @T (1, 2)
--   (1,1)
--   
--   &gt;&gt;&gt; countPred @T (1, 3)
--   (1,2)
--   
--   &gt;&gt;&gt; countPred @T (2, 0)
--   (1,3)
--   
--   &gt;&gt;&gt; countPred @T (0, 0)
--   (3,3)
--   
--   &gt;&gt;&gt; countPred @(Index 9, Index 2) (1, 0)
--   (0,1)
--   
--   &gt;&gt;&gt; countPred @(Either (Index 9) (Index 9)) (Right 0)
--   Left 8
--   </pre>
countPred :: Counter a => a -> a


module Clash.Class.AutoReg.Internal

-- | <a>autoReg</a> is a "smart" version of <a>register</a>. It does two
--   things:
--   
--   <ol>
--   <li>It splits product types over their fields. For example, given a
--   3-tuple, the corresponding HDL will end up with three instances of a
--   register (or more if the three fields can be split up similarly).</li>
--   <li>Given a data type where a constructor indicates (parts) of the
--   data will (not) be updated a given cycle, it will split the data in
--   two parts. The first part will contain the "always interesting" parts
--   (the constructor bits). The second holds the "potentially
--   uninteresting" data (the rest). Both parts will be stored in separate
--   registers. The register holding the "potentially uninteresting" part
--   will only be enabled if the constructor bits indicate they're
--   interesting.</li>
--   </ol>
--   
--   The most important example of this is <a>Maybe</a>. Consider <tt>Maybe
--   (Signed 16)</tt>; when viewed as bits, a <a>Nothing</a> would look
--   like:
--   
--   <pre>
--   &gt;&gt;&gt; pack @(Maybe (Signed 16)) Nothing
--   0b0_...._...._...._....
--   </pre>
--   
--   and <a>Just</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack @(Maybe (Signed 16)) (Just 3)
--   0b1_0000_0000_0000_0011
--   </pre>
--   
--   In the first case, Nothing, we don't particularly care about updating
--   the register holding the <tt>Signed 16</tt> field, as they'll be
--   unknown anyway. We can therefore deassert its enable line.
--   
--   Making Clash lay it out like this increases the chances of synthesis
--   tools clock gating the registers, saving energy.
--   
--   This version of <a>autoReg</a> will split the given data type up
--   recursively. For example, given <tt>a :: Maybe (Maybe Int, Maybe
--   Int)</tt>, a total of five registers will be rendered. Both the
--   "interesting" and "uninteresting" enable lines of the inner Maybe
--   types will be controlled by the outer one, in addition to the inner
--   parts controlling their "uninteresting" parts as described in (2).
--   
--   The default implementation is just <a>register</a>. If you don't need
--   or want the special features of <a>AutoReg</a>, you can use that by
--   writing an empty instance.
--   
--   <pre>
--   data MyDataType = ...
--   instance AutoReg MyDataType
--   </pre>
--   
--   If you have a product type you can use <a>deriveAutoReg</a> to derive
--   an instance.
class NFDataX a => AutoReg a

-- | For documentation see class <a>AutoReg</a>.
--   
--   This is the version with explicit clock/reset/enable inputs,
--   <a>Clash.Prelude</a> exports an implicit version of this:
--   <a>autoReg</a>
autoReg :: (AutoReg a, HasCallStack, KnownDomain dom) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom a -> Signal dom a

-- | Automatically derives an <a>AutoReg</a> instance for a product type
--   
--   Usage:
--   
--   <pre>
--   data Pair a b = MkPair { getA :: a, getB :: b } deriving (Generic, NFDataX)
--   data Tup3 a b c = MkTup3 { getAB :: Pair a b, getC :: c } deriving (Generic, NFDataX)
--   deriveAutoReg ''Pair
--   deriveAutoReg ''Tup3
--   </pre>
--   
--   <b>NB</b>: Because of the way template haskell works the order here
--   matters, if you try to <tt>deriveAutoReg ''Tup3</tt> before
--   <tt>Pair</tt> it will complain about missing an <tt>instance AutoReg
--   (Pair a b)</tt>.
deriveAutoReg :: Name -> DecsQ
deriveAutoRegTuples :: [Int] -> DecsQ
instance Clash.Class.AutoReg.Internal.AutoReg ()
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Types.Bool
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Types.Double
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Types.Float
instance Clash.Class.AutoReg.Internal.AutoReg Foreign.C.Types.CUShort
instance Clash.Class.AutoReg.Internal.AutoReg Numeric.Half.Internal.Half
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Types.Char
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Integer.Type.Integer
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Types.Int
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Int.Int8
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Int.Int16
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Int.Int32
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Int.Int64
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Types.Word
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Word.Word8
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Word.Word16
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Word.Word32
instance Clash.Class.AutoReg.Internal.AutoReg GHC.Word.Word64
instance Clash.Class.AutoReg.Internal.AutoReg Clash.Sized.Internal.BitVector.Bit
instance GHC.TypeNats.KnownNat n => Clash.Class.AutoReg.Internal.AutoReg (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Class.AutoReg.Internal.AutoReg (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Class.AutoReg.Internal.AutoReg (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.Class.AutoReg.Internal.AutoReg (Clash.Sized.Internal.Index.Index n)
instance Clash.XException.NFDataX (rep (int GHC.TypeNats.+ frac)) => Clash.Class.AutoReg.Internal.AutoReg (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Class.AutoReg.Internal.AutoReg a => Clash.Class.AutoReg.Internal.AutoReg (GHC.Maybe.Maybe a)
instance (GHC.TypeNats.KnownNat n, Clash.Class.AutoReg.Internal.AutoReg a) => Clash.Class.AutoReg.Internal.AutoReg (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat d, Clash.Class.AutoReg.Internal.AutoReg a) => Clash.Class.AutoReg.Internal.AutoReg (Clash.Sized.RTree.RTree d a)


module Clash.Class.AutoReg

-- | <a>autoReg</a> is a "smart" version of <a>register</a>. It does two
--   things:
--   
--   <ol>
--   <li>It splits product types over their fields. For example, given a
--   3-tuple, the corresponding HDL will end up with three instances of a
--   register (or more if the three fields can be split up similarly).</li>
--   <li>Given a data type where a constructor indicates (parts) of the
--   data will (not) be updated a given cycle, it will split the data in
--   two parts. The first part will contain the "always interesting" parts
--   (the constructor bits). The second holds the "potentially
--   uninteresting" data (the rest). Both parts will be stored in separate
--   registers. The register holding the "potentially uninteresting" part
--   will only be enabled if the constructor bits indicate they're
--   interesting.</li>
--   </ol>
--   
--   The most important example of this is <a>Maybe</a>. Consider <tt>Maybe
--   (Signed 16)</tt>; when viewed as bits, a <a>Nothing</a> would look
--   like:
--   
--   <pre>
--   &gt;&gt;&gt; pack @(Maybe (Signed 16)) Nothing
--   0b0_...._...._...._....
--   </pre>
--   
--   and <a>Just</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack @(Maybe (Signed 16)) (Just 3)
--   0b1_0000_0000_0000_0011
--   </pre>
--   
--   In the first case, Nothing, we don't particularly care about updating
--   the register holding the <tt>Signed 16</tt> field, as they'll be
--   unknown anyway. We can therefore deassert its enable line.
--   
--   Making Clash lay it out like this increases the chances of synthesis
--   tools clock gating the registers, saving energy.
--   
--   This version of <a>autoReg</a> will split the given data type up
--   recursively. For example, given <tt>a :: Maybe (Maybe Int, Maybe
--   Int)</tt>, a total of five registers will be rendered. Both the
--   "interesting" and "uninteresting" enable lines of the inner Maybe
--   types will be controlled by the outer one, in addition to the inner
--   parts controlling their "uninteresting" parts as described in (2).
--   
--   The default implementation is just <a>register</a>. If you don't need
--   or want the special features of <a>AutoReg</a>, you can use that by
--   writing an empty instance.
--   
--   <pre>
--   data MyDataType = ...
--   instance AutoReg MyDataType
--   </pre>
--   
--   If you have a product type you can use <a>deriveAutoReg</a> to derive
--   an instance.
class NFDataX a => AutoReg a

-- | For documentation see class <a>AutoReg</a>.
--   
--   This is the version with explicit clock/reset/enable inputs,
--   <a>Clash.Prelude</a> exports an implicit version of this:
--   <a>autoReg</a>
autoReg :: (AutoReg a, HasCallStack, KnownDomain dom) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom a -> Signal dom a

-- | Automatically derives an <a>AutoReg</a> instance for a product type
--   
--   Usage:
--   
--   <pre>
--   data Pair a b = MkPair { getA :: a, getB :: b } deriving (Generic, NFDataX)
--   data Tup3 a b c = MkTup3 { getAB :: Pair a b, getC :: c } deriving (Generic, NFDataX)
--   deriveAutoReg ''Pair
--   deriveAutoReg ''Tup3
--   </pre>
--   
--   <b>NB</b>: Because of the way template haskell works the order here
--   matters, if you try to <tt>deriveAutoReg ''Tup3</tt> before
--   <tt>Pair</tt> it will complain about missing an <tt>instance AutoReg
--   (Pair a b)</tt>.
deriveAutoReg :: Name -> DecsQ


module Clash.Class.Exp

-- | Type class implementing exponentiation with explicitly resizing
--   results.
class Exp a
type family ExpResult a (n :: Nat)

-- | Exponentiation with known exponent.
(^) :: Exp a => a -> SNat n -> ExpResult a n
infixr 8 ^
instance GHC.TypeNats.KnownNat m => Clash.Class.Exp.Exp (Clash.Sized.Internal.Index.Index m)
instance GHC.TypeNats.KnownNat m => Clash.Class.Exp.Exp (Clash.Sized.Internal.Signed.Signed m)
instance GHC.TypeNats.KnownNat m => Clash.Class.Exp.Exp (Clash.Sized.Internal.Unsigned.Unsigned m)

module Clash.Num.Zeroing

-- | A zeroing number type is one where all operations return zero if they
--   go out of bounds for the underlying type.
--   
--   Numbers can be converted to zero by default using <a>toZeroing</a>.
data Zeroing a
fromZeroing :: Zeroing a -> a
toZeroing :: SaturatingNum a => a -> Zeroing a
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Num.Zeroing.Zeroing a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Num.Zeroing.Zeroing a)
instance Clash.Class.Parity.Parity a => Clash.Class.Parity.Parity (Clash.Num.Zeroing.Zeroing a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Clash.Num.Zeroing.Zeroing a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Clash.Num.Zeroing.Zeroing a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Num.Zeroing.Zeroing a)
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Clash.Num.Zeroing.Zeroing a)
instance Data.Bits.FiniteBits a => Data.Bits.FiniteBits (Clash.Num.Zeroing.Zeroing a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Num.Zeroing.Zeroing a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Clash.Num.Zeroing.Zeroing a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Clash.Num.Zeroing.Zeroing a)
instance Data.Bits.Bits a => Data.Bits.Bits (Clash.Num.Zeroing.Zeroing a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Clash.Num.Zeroing.Zeroing a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Num.Zeroing.Zeroing a)
instance Clash.Class.Resize.Resize f => Clash.Class.Resize.Resize (Data.Functor.Compose.Compose Clash.Num.Zeroing.Zeroing f)
instance (GHC.Enum.Bounded a, GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Num.Num (Clash.Num.Zeroing.Zeroing a)
instance (GHC.Enum.Enum a, Clash.Class.Num.SaturatingNum a) => GHC.Enum.Enum (Clash.Num.Zeroing.Zeroing a)
instance (GHC.Real.Real a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Real (Clash.Num.Zeroing.Zeroing a)
instance (GHC.Real.Integral a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Integral (Clash.Num.Zeroing.Zeroing a)
instance (GHC.Real.Fractional a, GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Fractional (Clash.Num.Zeroing.Zeroing a)
instance (GHC.Real.RealFrac a, Clash.Class.Num.SaturatingNum a) => GHC.Real.RealFrac (Clash.Num.Zeroing.Zeroing a)

module Clash.Num.Wrapping

-- | A wrapping number type is one where all operations wrap between
--   minBound and maxBound (and vice-versa) if the result goes out of
--   bounds for the underlying type.
--   
--   Numbers can be converted to wrap by default using <a>toWrapping</a>.
newtype Wrapping a
Wrapping :: a -> Wrapping a
[fromWrapping] :: Wrapping a -> a
toWrapping :: SaturatingNum a => a -> Wrapping a
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Num.Wrapping.Wrapping a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Num.Wrapping.Wrapping a)
instance Clash.Class.Parity.Parity a => Clash.Class.Parity.Parity (Clash.Num.Wrapping.Wrapping a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Clash.Num.Wrapping.Wrapping a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Clash.Num.Wrapping.Wrapping a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Num.Wrapping.Wrapping a)
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Clash.Num.Wrapping.Wrapping a)
instance Data.Bits.FiniteBits a => Data.Bits.FiniteBits (Clash.Num.Wrapping.Wrapping a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Num.Wrapping.Wrapping a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Clash.Num.Wrapping.Wrapping a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Clash.Num.Wrapping.Wrapping a)
instance Data.Bits.Bits a => Data.Bits.Bits (Clash.Num.Wrapping.Wrapping a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Clash.Num.Wrapping.Wrapping a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Num.Wrapping.Wrapping a)
instance Clash.Class.Resize.Resize f => Clash.Class.Resize.Resize (Data.Functor.Compose.Compose Clash.Num.Wrapping.Wrapping f)
instance Clash.Class.Num.SaturatingNum a => GHC.Num.Num (Clash.Num.Wrapping.Wrapping a)
instance (GHC.Enum.Enum a, Clash.Class.Num.SaturatingNum a) => GHC.Enum.Enum (Clash.Num.Wrapping.Wrapping a)
instance (GHC.Real.Real a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Real (Clash.Num.Wrapping.Wrapping a)
instance (GHC.Real.Integral a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Integral (Clash.Num.Wrapping.Wrapping a)
instance (GHC.Real.Fractional a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Fractional (Clash.Num.Wrapping.Wrapping a)
instance (GHC.Real.RealFrac a, Clash.Class.Num.SaturatingNum a) => GHC.Real.RealFrac (Clash.Num.Wrapping.Wrapping a)

module Clash.Num.Saturating

-- | A saturating number type is one where all operations saturate at the
--   bounds of the underlying type, i.e. operations which overflow return
--   <a>maxBound</a> and operations that underflow return <a>minBound</a>.
--   
--   Numbers can be converted to saturate by default using
--   <a>toSaturating</a>.
data Saturating a
fromSaturating :: Saturating a -> a
toSaturating :: SaturatingNum a => a -> Saturating a
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Num.Saturating.Saturating a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Num.Saturating.Saturating a)
instance Clash.Class.Parity.Parity a => Clash.Class.Parity.Parity (Clash.Num.Saturating.Saturating a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Clash.Num.Saturating.Saturating a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Clash.Num.Saturating.Saturating a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Num.Saturating.Saturating a)
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Clash.Num.Saturating.Saturating a)
instance Data.Bits.FiniteBits a => Data.Bits.FiniteBits (Clash.Num.Saturating.Saturating a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Num.Saturating.Saturating a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Clash.Num.Saturating.Saturating a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Clash.Num.Saturating.Saturating a)
instance Data.Bits.Bits a => Data.Bits.Bits (Clash.Num.Saturating.Saturating a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Clash.Num.Saturating.Saturating a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Num.Saturating.Saturating a)
instance Clash.Class.Resize.Resize f => Clash.Class.Resize.Resize (Data.Functor.Compose.Compose Clash.Num.Saturating.Saturating f)
instance (GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Num.Num (Clash.Num.Saturating.Saturating a)
instance (GHC.Enum.Enum a, Clash.Class.Num.SaturatingNum a) => GHC.Enum.Enum (Clash.Num.Saturating.Saturating a)
instance (GHC.Real.Real a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Real (Clash.Num.Saturating.Saturating a)
instance (GHC.Real.Integral a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Integral (Clash.Num.Saturating.Saturating a)
instance (GHC.Real.Fractional a, GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Fractional (Clash.Num.Saturating.Saturating a)
instance (GHC.Classes.Ord a, GHC.Real.RealFrac a, Clash.Class.Num.SaturatingNum a) => GHC.Real.RealFrac (Clash.Num.Saturating.Saturating a)


module Clash.Num.Overflowing

-- | An overflowing number behaves similarly to a <a>Wrapping</a> number,
--   but also includes an overflow status flag which can be used to more
--   easily check if an overflow has occurred.
--   
--   Numbers can be converted to be <a>Overflowing</a> using
--   <a>toOverflowing</a>.
data Overflowing a

-- | Retrieve the value
fromOverflowing :: Overflowing a -> a

-- | <a>True</a> when a computation has overflowed
hasOverflowed :: Overflowing a -> Bool
toOverflowing :: a -> Overflowing a

-- | Reset the overflow status flag to False.
clearOverflow :: Overflowing a -> Overflowing a
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Num.Overflowing.Overflowing a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Clash.Num.Overflowing.Overflowing a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Num.Overflowing.Overflowing a)
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Clash.Num.Overflowing.Overflowing a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Clash.Num.Overflowing.Overflowing a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Num.Overflowing.Overflowing a)
instance GHC.Generics.Generic (Clash.Num.Overflowing.Overflowing a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Num.Overflowing.Overflowing a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Clash.Num.Overflowing.Overflowing a)
instance (Clash.Class.BitPack.Internal.BitPack a, GHC.TypeNats.KnownNat (Clash.Class.BitPack.Internal.BitSize a GHC.TypeNats.+ 1)) => Clash.Class.BitPack.Internal.BitPack (Clash.Num.Overflowing.Overflowing a)
instance Clash.Class.Parity.Parity a => Clash.Class.Parity.Parity (Clash.Num.Overflowing.Overflowing a)
instance (GHC.Enum.Bounded a, GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Num.Num (Clash.Num.Overflowing.Overflowing a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Clash.Num.Overflowing.Overflowing a)
instance (GHC.Enum.Enum a, GHC.Classes.Eq a, Clash.Class.Num.SaturatingNum a) => GHC.Enum.Enum (Clash.Num.Overflowing.Overflowing a)
instance (GHC.Real.Real a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Real (Clash.Num.Overflowing.Overflowing a)
instance (GHC.Real.Integral a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Integral (Clash.Num.Overflowing.Overflowing a)
instance (GHC.Real.Fractional a, GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Fractional (Clash.Num.Overflowing.Overflowing a)
instance (GHC.Real.RealFrac a, Clash.Class.Num.SaturatingNum a) => GHC.Real.RealFrac (Clash.Num.Overflowing.Overflowing a)

module Clash.Num.Erroring

-- | An erroring number type is one where all operations return a
--   <a>XExecption</a> if they would go out of bounds for the underlying
--   type.
--   
--   Numbers can be converted to error by default using <a>toErroring</a>.
data Erroring a
fromErroring :: Erroring a -> a
toErroring :: SaturatingNum a => a -> Erroring a
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Num.Erroring.Erroring a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Num.Erroring.Erroring a)
instance Clash.Class.Parity.Parity a => Clash.Class.Parity.Parity (Clash.Num.Erroring.Erroring a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Clash.Num.Erroring.Erroring a)
instance Clash.XException.NFDataX a => Clash.XException.NFDataX (Clash.Num.Erroring.Erroring a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Num.Erroring.Erroring a)
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Clash.Num.Erroring.Erroring a)
instance Data.Bits.FiniteBits a => Data.Bits.FiniteBits (Clash.Num.Erroring.Erroring a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Clash.Num.Erroring.Erroring a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Clash.Num.Erroring.Erroring a)
instance Clash.Class.BitPack.Internal.BitPack a => Clash.Class.BitPack.Internal.BitPack (Clash.Num.Erroring.Erroring a)
instance Data.Bits.Bits a => Data.Bits.Bits (Clash.Num.Erroring.Erroring a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Clash.Num.Erroring.Erroring a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Num.Erroring.Erroring a)
instance Clash.Class.Resize.Resize f => Clash.Class.Resize.Resize (Data.Functor.Compose.Compose Clash.Num.Erroring.Erroring f)
instance (GHC.Enum.Bounded a, GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Num.Num (Clash.Num.Erroring.Erroring a)
instance (GHC.Enum.Enum a, Clash.Class.Num.SaturatingNum a) => GHC.Enum.Enum (Clash.Num.Erroring.Erroring a)
instance (GHC.Real.Real a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Real (Clash.Num.Erroring.Erroring a)
instance (GHC.Real.Integral a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Integral (Clash.Num.Erroring.Erroring a)
instance (GHC.Real.Fractional a, GHC.Classes.Ord a, Clash.Class.Num.SaturatingNum a) => GHC.Real.Fractional (Clash.Num.Erroring.Erroring a)
instance (GHC.Real.RealFrac a, Clash.Class.Num.SaturatingNum a) => GHC.Real.RealFrac (Clash.Num.Erroring.Erroring a)


-- | <a>TopEntity</a> annotations allow us to control hierarchy and naming
--   aspects of the Clash compiler. We have the <a>Synthesize</a> and
--   <a>TestBench</a> annotation.
--   
--   <h3><a>Synthesize</a> annotation</h3>
--   
--   The <a>Synthesize</a> annotation allows us to:
--   
--   <ul>
--   <li>Assign names to entities (VHDL) / modules ((System)Verilog), and
--   their ports.</li>
--   <li>Put generated HDL files of a logical (sub)entity in their own
--   directory.</li>
--   <li>Use cached versions of generated HDL, i.e., prevent recompilation
--   of (sub)entities that have not changed since the last run. Caching is
--   based on a <tt>.manifest</tt> which is generated alongside the HDL;
--   deleting this file means deleting the cache; changing this file will
--   result in <i>undefined</i> behavior.</li>
--   </ul>
--   
--   Functions with a <a>Synthesize</a> annotation must adhere to the
--   following restrictions:
--   
--   <ul>
--   <li>Although functions with a <a>Synthesize</a> annotation can of
--   course depend on functions with another <a>Synthesize</a> annotation,
--   they must not be mutually recursive.</li>
--   <li>Functions with a <a>Synthesize</a> annotation must be completely
--   <i>monomorphic</i> and <i>first-order</i>, and cannot have any
--   <i>non-representable</i> arguments or result.</li>
--   </ul>
--   
--   Also take the following into account when using <a>Synthesize</a>
--   annotations.
--   
--   <ul>
--   <li>The Clash compiler is based on the GHC Haskell compiler, and the
--   GHC machinery does not understand <a>Synthesize</a> annotations and it
--   might subsequently decide to inline those functions. You should
--   therefor also add a <tt>{-# NOINLINE f #-}</tt> pragma to the
--   functions which you give a <a>Synthesize</a> functions.</li>
--   <li>Functions with a <a>Synthesize</a> annotation will not be
--   specialized on constants.</li>
--   </ul>
--   
--   Finally, the root module, the module which you pass as an argument to
--   the Clash compiler must either have:
--   
--   <ul>
--   <li>A function with a <a>Synthesize</a> annotation.</li>
--   <li>A function called <i>topEntity</i>.</li>
--   </ul>
--   
--   You apply <a>Synthesize</a> annotations to functions using an
--   <tt>ANN</tt> pragma:
--   
--   <pre>
--   {-# ANN f (Synthesize {t_name = ..., ...  }) #-}
--   f x = ...
--   </pre>
--   
--   For example, given the following specification:
--   
--   <pre>
--   module Blinker where
--   
--   import Clash.Prelude
--   import Clash.Intel.ClockGen
--   
--   -- Define a synthesis domain with a clock with a period of 20000 /ps/. Signal
--   -- coming from the reset button is low when pressed, and high when not pressed.
--   <a>createDomain</a>
--     vSystem{vName="DomInput", vPeriod=20000, vResetPolarity=ActiveLow}
--   -- Define a synthesis domain with a clock with a period of 50000 /ps/.
--   <a>createDomain</a> vSystem{vName="Dom50", vPeriod=50000}
--   
--   topEntity
--     :: Clock DomInput
--     -&gt; Reset DomInput
--     -&gt; Enable Dom50
--     -&gt; Signal Dom50 Bit
--     -&gt; Signal Dom50 (BitVector 8)
--   topEntity clk20 rstBtn enaBtn modeBtn =
--     <a>exposeClockResetEnable</a>
--       (<a>mealy</a> blinkerT initialStateBlinkerT . <a>isRising</a> 1)
--       clk50
--       rst50
--       enaBtn
--       modeBtn
--    where
--     -- Start with the first LED turned on, in rotate mode, with the counter on zero
--     initialStateBlinkerT = (1, False, 0)
--   
--     -- Instantiate a PLL: this stabilizes the incoming clock signal and releases
--     -- the reset output when the signal is stable. We're also using it to
--     -- transform an incoming clock signal running at 20 MHz to a clock signal
--     -- running at 50 MHz. Since the signature of topEntity already specifies the
--     -- Dom50 domain, we don't need any type signatures to specify the domain here.
--     (clk50, rst50) = <a>altpllSync</a> clk20 rstBtn
--   
--   blinkerT
--     :: (BitVector 8, Bool, Index 16650001)
--     -&gt; Bool
--     -&gt; ((BitVector 8, Bool, Index 16650001), BitVector 8)
--   blinkerT (leds,mode,cntr) key1R = ((leds',mode',cntr'),leds)
--     where
--       -- clock frequency = 50e6  (50 MHz)
--       -- led update rate = 333e-3 (every 333ms)
--       cnt_max = 16650000 -- 50e6 * 333e-3
--   
--       cntr' | cntr == cnt_max = 0
--             | otherwise       = cntr + 1
--   
--       mode' | key1R     = not mode
--             | otherwise = mode
--   
--       leds' | cntr == 0 = if mode then complement leds
--                                   else rotateL leds 1
--             | otherwise = leds
--   </pre>
--   
--   The Clash compiler would normally generate the following
--   <tt>topEntity.vhdl</tt> file:
--   
--   <pre>
--   -- Automatically generated VHDL-93
--   library IEEE;
--   use IEEE.STD_LOGIC_1164.ALL;
--   use IEEE.NUMERIC_STD.ALL;
--   use IEEE.MATH_REAL.ALL;
--   use std.textio.all;
--   use work.all;
--   use work.Blinker_topEntity_types.all;
--   
--   entity topEntity is
--     port(-- clock
--          clk20   : in Blinker_topEntity_types.clk_DomInput;
--          -- reset
--          rstBtn  : in Blinker_topEntity_types.rst_DomInput;
--          -- enable
--          enaBtn  : in Blinker_topEntity_types.en_Dom50;
--          modeBtn : in std_logic;
--          result  : out std_logic_vector(7 downto 0));
--   end;
--   
--   architecture structural of topEntity is
--     ...
--   end;
--   </pre>
--   
--   However, if we add the following <a>Synthesize</a> annotation in the
--   file:
--   
--   <pre>
--   {-# ANN topEntity
--     (<a>Synthesize</a>
--       { t_name   = "blinker"
--       , t_inputs = [ PortName "CLOCK_50"
--                    , PortName "KEY0"
--                    , PortName "KEY1"
--                    , PortName "KEY2" ]
--       , t_output = PortName "LED"
--       }) #-}
--   </pre>
--   
--   The Clash compiler will generate the following <tt>blinker.vhdl</tt>
--   file instead:
--   
--   <pre>
--   -- Automatically generated VHDL-93
--   library IEEE;
--   use IEEE.STD_LOGIC_1164.ALL;
--   use IEEE.NUMERIC_STD.ALL;
--   use IEEE.MATH_REAL.ALL;
--   use std.textio.all;
--   use work.all;
--   use work.blinker_types.all;
--   
--   entity blinker is
--     port(-- clock
--          CLOCK_50 : in blinker_types.clk_DomInput;
--          -- reset
--          KEY0     : in blinker_types.rst_DomInput;
--          -- enable
--          KEY1     : in blinker_types.en_Dom50;
--          KEY2     : in std_logic;
--          LED      : out std_logic_vector(7 downto 0));
--   end;
--   
--   architecture structural of blinker is
--     ...
--   end;
--   </pre>
--   
--   Where we now have:
--   
--   <ul>
--   <li>A top-level component that is called <tt>blinker</tt>.</li>
--   <li>Inputs and outputs that have a <i>user</i>-chosen name:
--   <tt>CLOCK_50</tt>, <tt>KEY0</tt>, <tt>KEY1</tt>, <tt>KEY2</tt>,
--   <tt>LED</tt>, etc.</li>
--   </ul>
--   
--   See the documentation of <a>Synthesize</a> for the meaning of all its
--   fields.
--   
--   <h3><a>TestBench</a> annotation</h3>
--   
--   Tell what binder is the test bench for a <a>Synthesize</a>-annotated
--   binder.
--   
--   <pre>
--   entityBeingTested :: ...
--   entityBeingTested = ...
--   {-# NOINLINE entityBeingTested #-}
--   {-# ANN entityBeingTested (defSyn "entityBeingTested") #-}
--   
--   
--   myTestBench :: Signal System Bool
--   myTestBench = ... entityBeingTested ...
--   {-# NOINLINE myTestBench #-}
--   {-# ANN myTestBench (TestBench 'entityBeingTested) #-}
--   </pre>
--   
--   The <a>TestBench</a> annotation actually already implies a
--   <a>Synthesize</a> annotation on the device under test, so the
--   <a>defSyn</a> in the example could have been omitted. We recommend you
--   supply <a>defSyn</a> explicitly nonetheless. In any case, it will
--   still need the <tt>NOINLINE</tt> annotation.
module Clash.Annotations.TopEntity

-- | TopEntity annotation
data TopEntity

-- | Instruct the Clash compiler to use this top-level function as a
--   separately synthesizable component.
Synthesize :: String -> [PortName] -> PortName -> TopEntity

-- | The name the top-level component should have, put in a correspondingly
--   named file.
[t_name] :: TopEntity -> String

-- | List of names that are assigned in-order to the inputs of the
--   component.
[t_inputs] :: TopEntity -> [PortName]

-- | Name assigned in-order to the outputs of the component. As a Haskell
--   function can only truly return a single value -- with multiple values
--   "wrapped" by a tuple -- this field is not a list, but a single
--   <tt><a>PortName</a></tt>. Use <tt><a>PortProduct</a></tt> to give
--   names to the individual components of the output tuple.
[t_output] :: TopEntity -> PortName

-- | Tell what binder is the <a>TestBench</a> for a
--   <a>Synthesize</a>-annotated binder.
--   
--   <pre>
--   {-# NOINLINE myTestBench #-}
--   {-# ANN myTestBench (TestBench 'entityBeingTested) #-}
--   </pre>
TestBench :: Name -> TopEntity

-- | Give port names for arguments/results.
--   
--   Give a data type and function:
--   
--   <pre>
--   data T = MkT Int Bool
--   
--   {-# ANN f (defSyn "f") #-}
--   f :: Int -&gt; T -&gt; (T,Bool)
--   f a b = ...
--   </pre>
--   
--   Clash would normally generate the following VHDL entity:
--   
--   <pre>
--   entity f is
--     port(a      : in signed(63 downto 0);
--          b_0    : in signed(63 downto 0);
--          b_1    : in boolean;
--          result : out std_logic_vector(65 downto 0));
--   end;
--   </pre>
--   
--   However, we can change this by using <a>PortName</a>s. So by:
--   
--   <pre>
--   {-# ANN f
--      (Synthesize
--         { t_name   = "f"
--         , t_inputs = [ PortName "a"
--                      , PortName "b" ]
--         , t_output = PortName "res" }) #-}
--   f :: Int -&gt; T -&gt; (T,Bool)
--   f a b = ...
--   </pre>
--   
--   we get:
--   
--   <pre>
--   entity f is
--     port(a   : in signed(63 downto 0);
--          b   : in std_logic_vector(64 downto 0);
--          res : out std_logic_vector(65 downto 0));
--   end;
--   </pre>
--   
--   If we want to name fields for tuples/records we have to use
--   <a>PortProduct</a>
--   
--   <pre>
--   {-# ANN f
--      (Synthesize
--         { t_name   = "f"
--         , t_inputs = [ PortName "a"
--                      , PortProduct "" [ PortName "b", PortName "c" ] ]
--         , t_output = PortProduct "res" [PortName "q"] }) #-}
--   f :: Int -&gt; T -&gt; (T,Bool)
--   f a b = ...
--   </pre>
--   
--   So that we get:
--   
--   <pre>
--   entity f is
--     port(a     : in signed(63 downto 0);
--          b     : in signed(63 downto 0);
--          c     : in boolean;
--          res_q : out std_logic_vector(64 downto 0);
--          res_1 : out boolean);
--   end;
--   </pre>
--   
--   Notice how we didn't name the second field of the result, and the
--   second output port got <a>PortProduct</a> name, "res", as a prefix for
--   its name.
data PortName

-- | You want a port, with the given name, for the entire argument/type
--   
--   You can use an empty String ,<tt>""</tt> , in case you want an
--   auto-generated name.
PortName :: String -> PortName

-- | You want to assign ports to fields of a product argument/type
--   
--   The first argument of <a>PortProduct</a> is the name of:
--   
--   <ol>
--   <li>The signal/wire to which the individual ports are aggregated.</li>
--   <li>The prefix for any unnamed ports below the <a>PortProduct</a></li>
--   </ol>
--   
--   You can use an empty String ,<tt>""</tt> , in case you want an
--   auto-generated name.
PortProduct :: String -> [PortName] -> PortName

-- | Default <a>Synthesize</a> annotation which has no specified names for
--   the input and output ports.
--   
--   <pre>
--   &gt;&gt;&gt; defSyn "foo"
--   Synthesize {t_name = "foo", t_inputs = [], t_output = PortName ""}
--   </pre>
defSyn :: String -> TopEntity
instance Language.Haskell.TH.Syntax.Lift Clash.Annotations.TopEntity.PortName
instance GHC.Generics.Generic Clash.Annotations.TopEntity.PortName
instance GHC.Show.Show Clash.Annotations.TopEntity.PortName
instance Data.Data.Data Clash.Annotations.TopEntity.PortName
instance GHC.Classes.Eq Clash.Annotations.TopEntity.PortName
instance GHC.Generics.Generic Clash.Annotations.TopEntity.TopEntity
instance GHC.Show.Show Clash.Annotations.TopEntity.TopEntity
instance Data.Data.Data Clash.Annotations.TopEntity.TopEntity
instance GHC.Classes.Eq Clash.Annotations.TopEntity.TopEntity
instance Language.Haskell.TH.Syntax.Lift Clash.Annotations.TopEntity.TopEntity


-- | <b>This is the <a>Safe</a> API only of
--   <a>Clash.Explicit.Prelude</a></b>
--   
--   This module defines the explicitly clocked counterparts of the
--   functions defined in <a>Clash.Prelude</a>.
module Clash.Explicit.Prelude.Safe

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   import qualified Data.List as L
--   
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac clk rst en = <a>mealy</a> clk rst en macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen enableGen) [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac clk rst en (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> clk rst en macT 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> clk rst en macT 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool,Int) -&gt; (Int,(Int,Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (mealy clk rst en f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (mealy clk rst en f 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> clk rst en f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> clk rst en f 3 (c,i1)
--   </pre>
mealyB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac clk rst en = <a>moore</a> clk rst en macT id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen enableGen) [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac clk rst en (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> clk rst en macT id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> clk rst en macT id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> (s -> o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (moore clk rst en t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (moore clk rst en t o 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> clk rst en t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> clk rst en t o 3 (c,i1)
--   </pre>
mooreB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> (s -> o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   <tt>(<a>Signal</a> a, <a>Signal</a> b)</tt>)
--   
--   <pre>
--   rP :: Clock dom -&gt; Reset dom -&gt; Enable dom
--      -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--      -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--   rP clk rst en = <a>registerB</a> clk rst en (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (rP systemClockGen systemResetGen enableGen) [(1,1),(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: (KnownDomain dom, NFDataX a, Bundle a) => Clock dom -> Reset dom -> Enable dom -> a -> Unbundled dom a -> Unbundled dom a

-- | Synchronizer based on two sequentially connected flip-flops.
--   
--   <ul>
--   <li><b>NB</b>: This synchronizer can be used for
--   <b>bit</b>-synchronization.</li>
--   <li><b>NB</b>: Although this synchronizer does reduce metastability,
--   it does not guarantee the proper synchronization of a whole
--   <b>word</b>. For example, given that the output is sampled twice as
--   fast as the input is running, and we have two samples in the input
--   stream that look like:<pre>[0111,1000]</pre>But the circuit driving
--   the input stream has a longer propagation delay on <b>msb</b> compared
--   to the <b>lsb</b>s. What can happen is an output stream that looks
--   like this:<pre>[0111,0111,0000,1000]</pre>Where the level-change of
--   the <b>msb</b> was not captured, but the level change of the
--   <b>lsb</b>s were.If you want to have <i>safe</i>
--   <b>word</b>-synchronization use <a>asyncFIFOSynchronizer</a>.</li>
--   </ul>
dualFlipFlopSynchronizer :: (NFDataX a, KnownDomain dom1, KnownDomain dom2) => Clock dom1 -> Clock dom2 -> Reset dom2 -> Enable dom2 -> a -> Signal dom1 a -> Signal dom2 a

-- | Synchronizer implemented as a FIFO around a synchronous RAM. Based on
--   the design described in <a>Clash.Tutorial#multiclock</a>, which is
--   itself based on the design described in
--   <a>http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf</a>.
--   However, this FIFO uses a synchronous dual-ported RAM which, unlike
--   those designs using RAM with an asynchronous read port, is nearly
--   guaranteed to actually synthesize into one of the dual-ported RAMs
--   found on most FPGAs.
--   
--   <b>NB</b>: This synchronizer can be used for
--   <b>word</b>-synchronization. <b>NB</b>: This synchronizer will only
--   work safely when you set up the proper bus skew and maximum delay
--   constraints inside your synthesis tool for the clock domain crossings
--   of the gray pointers.
asyncFIFOSynchronizer :: (KnownDomain wdom, KnownDomain rdom, 2 <= addrSize, NFDataX a) => SNat addrSize -> Clock wdom -> Clock rdom -> Reset wdom -> Reset rdom -> Enable wdom -> Enable rdom -> Signal rdom Bool -> Signal wdom (Maybe a) -> (Signal rdom a, Signal rdom Bool, Signal wdom Bool)

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFile</a> and
--   <a>asyncRomBlob</a> for different approaches that scale well.</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr, NFDataX a) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFilePow2</a> and
--   <a>asyncRomBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
asyncRomPow2 :: (KnownNat n, NFDataX a) => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFile</a> and
--   <a>romBlob</a> for different approaches that scale well.</li>
--   </ul>
rom :: (KnownDomain dom, KnownNat n, NFDataX a, Enum addr) => Clock dom -> Enable dom -> Vec n a -> Signal dom addr -> Signal dom a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFilePow2</a> and
--   <a>romBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
romPow2 :: (KnownDomain dom, KnownNat n, NFDataX a) => Clock dom -> Enable dom -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom a

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlob :: Enum addr => MemBlob n m -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlobPow2 :: KnownNat n => MemBlob (2 ^ n) m -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlob :: forall dom addr m n. (KnownDomain dom, Enum addr) => Clock dom -> Enable dom -> MemBlob n m -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlobPow2 :: forall dom m n. (KnownDomain dom, KnownNat n) => Clock dom -> Enable dom -> MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, NFDataX addr, HasCallStack, KnownDomain wdom, KnownDomain rdom, NFDataX a) => Clock wdom -> Clock rdom -> Enable wdom -> SNat n -> Signal rdom addr -> Signal wdom (Maybe (addr, a)) -> Signal rdom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: forall wdom rdom n a. (KnownNat n, HasCallStack, KnownDomain wdom, KnownDomain rdom, NFDataX a) => Clock wdom -> Clock rdom -> Enable wdom -> Signal rdom (Unsigned n) -> Signal wdom (Maybe (Unsigned n, a)) -> Signal rdom a

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en (<a>blockRam</a>
--   clk inits) rd wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFile</a> and
--   <a>blockRamBlob</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram40
--     :: <a>Clock</a>  dom
--     -&gt; <a>Enable</a>  dom
--     -&gt; <a>Signal</a> dom (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram40 clk en = <a>blockRam</a> clk en (<a>replicate</a> d40 1)
--   </pre>
blockRam :: (KnownDomain dom, HasCallStack, NFDataX a, Enum addr, NFDataX addr) => Clock dom -> Enable dom -> Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamPow2</a> clk inits) rd wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFilePow2</a> and
--   <a>blockRamBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram32
--     :: <a>Clock</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram32 clk en = <a>blockRamPow2</a> clk en (<a>replicate</a> d32 1)
--   </pre>
blockRamPow2 :: (KnownDomain dom, HasCallStack, NFDataX a, KnownNat n) => Clock dom -> Enable dom -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamBlob</a> clk en content) rd wrM</tt>.</li>
--   </ul>
blockRamBlob :: forall dom addr m n. (KnownDomain dom, Enum addr, NFDataX addr) => Clock dom -> Enable dom -> MemBlob n m -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamBlobPow2</a> clk en content) rd wrM</tt>.</li>
--   </ul>
blockRamBlobPow2 :: forall dom m n. (KnownDomain dom, KnownNat n) => Clock dom -> Enable dom -> MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]

-- | Create a read-after-write block RAM from a read-before-write one
readNew :: (KnownDomain dom, NFDataX a, Eq addr) => Clock dom -> Reset dom -> Enable dom -> (Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Produces vendor-agnostic HDL that will be inferred as a true dual-port
--   block RAM
--   
--   Any value that is being written on a particular port is also the value
--   that will be read on that port, i.e. the same-port read/write behavior
--   is: WriteFirst. For mixed-port read/write, when port A writes to the
--   address port B reads from, the output of port B is undefined, and vice
--   versa.
trueDualPortBlockRam :: forall nAddrs domA domB a. (HasCallStack, KnownNat nAddrs, KnownDomain domA, KnownDomain domB, NFDataX a) => Clock domA -> Clock domB -> Signal domA (RamOp nAddrs a) -> Signal domB (RamOp nAddrs a) -> (Signal domA a, Signal domB a)

-- | Port operation
data RamOp n a

-- | Read from address
RamRead :: Index n -> RamOp n a

-- | Write data to address
RamWrite :: Index n -> a -> RamOp n a

-- | No operation
RamNoOp :: RamOp n a

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (KnownDomain dom, NFDataX a, Bounded a, Eq a) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom a -> Signal dom Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (KnownDomain dom, NFDataX a, Bounded a, Eq a) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom a -> Signal dom Bool

-- | Give a pulse every <tt>n</tt> clock cycles. This is a useful helper
--   function when combined with functions like <tt><a>regEn</a></tt> or
--   <tt><a>mux</a></tt>, in order to delay a register by a known amount.
riseEvery :: forall dom n. KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> SNat n -> Signal dom Bool

-- | Oscillate a <tt><a>Bool</a></tt> for a given number of cycles, given
--   the starting state.
oscillate :: forall dom n. KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> Bool -> SNat n -> Signal dom Bool

-- | Fixed size vectors.
--   
--   <ul>
--   <li>Lists with their length encoded in their type</li>
--   <li><a>Vec</a>tor elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.</li>
--   </ul>
data Vec :: Nat -> Type -> Type
[Nil] :: Vec 0 a
[Cons] :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the head of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; 3:&gt;4:&gt;5:&gt;Nil
--   3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = 3:&gt;4:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 3 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (x :&gt; y :&gt; _) = x + y
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   7
--   </pre>
--   
--   Also in conjunctions with (<a>:&lt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:>) :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the tail of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   3 :&gt; 4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 4 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (_ :&lt; y :&lt; x) = y + x
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   13
--   </pre>
--   
--   Also in conjunctions with (<a>:&gt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:<) :: Vec n a -> a -> Vec (n + 1) a
infixr 5 :>
infixl 5 :<
infixr 5 `Cons`

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from left to right:
--   
--   <pre>
--   foldl f z (x1 :&gt; x2 :&gt; ... :&gt; xn :&gt; Nil) == (...((z `f` x1) `f` x2) `f`...) `f` xn
--   foldl f z Nil                            == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldl :: (b -> a -> b) -> b -> Vec n a -> b

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z (x1 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn1 `f` (xn `f` z))...)
--   foldr r z Nil                             == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldr :: (a -> b -> b) -> b -> Vec n a -> b

-- | "<a>map</a> <tt>f xs</tt>" is the vector obtained by applying <i>f</i>
--   to each element of <i>xs</i>, i.e.,
--   
--   <pre>
--   map f (x1 :&gt; x2 :&gt;  ... :&gt; xn :&gt; Nil) == (f x1 :&gt; f x2 :&gt; ... :&gt; f xn :&gt; Nil)
--   </pre>
--   
--   and corresponds to the following circuit layout:
--   
map :: (a -> b) -> Vec n a -> Vec n b

-- | Convert a <a>BitVector</a> to a <a>Vec</a> of <a>Bit</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 6 :: BitVector 8
--   
--   &gt;&gt;&gt; x
--   0b0000_0110
--   
--   &gt;&gt;&gt; bv2v x
--   0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 1 :&gt; 0 :&gt; Nil
--   </pre>
bv2v :: KnownNat n => BitVector n -> Vec n Bit

-- | To be used as the motive <i>p</i> for <a>dfold</a>, when the <i>f</i>
--   in "<a>dfold</a> <tt>p f</tt>" is a variation on (<a>:&gt;</a>), e.g.:
--   
--   <pre>
--   map' :: forall n a b . KnownNat n =&gt; (a -&gt; b) -&gt; Vec n a -&gt; Vec n b
--   map' f = <a>dfold</a> (Proxy @(<a>VCons</a> b)) (_ x xs -&gt; f x :&gt; xs)
--   </pre>
data VCons (a :: Type) (f :: TyFun Nat Type) :: Type
traverse# :: forall a f b n. Applicative f => (a -> f b) -> Vec n a -> f (Vec n b)

-- | Create a vector of one element
--   
--   <pre>
--   &gt;&gt;&gt; singleton 5
--   5 :&gt; Nil
--   </pre>
singleton :: a -> Vec 1 a

-- | Extract the first element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; head (1:&gt;2:&gt;3:&gt;Nil)
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; head Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘head’, namely ‘Nil’
--         In the expression: head Nil
--         In an equation for ‘it’: it = head Nil
--   </pre>
head :: Vec (n + 1) a -> a

-- | Extract the elements after the head of a vector
--   
--   <pre>
--   &gt;&gt;&gt; tail (1:&gt;2:&gt;3:&gt;Nil)
--   2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; tail Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘tail’, namely ‘Nil’
--         In the expression: tail Nil
--         In an equation for ‘it’: it = tail Nil
--   </pre>
tail :: Vec (n + 1) a -> Vec n a

-- | Extract the last element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; last (1:&gt;2:&gt;3:&gt;Nil)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; last Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘last’, namely ‘Nil’
--         In the expression: last Nil
--         In an equation for ‘it’: it = last Nil
--   </pre>
last :: Vec (n + 1) a -> a

-- | Extract all the elements of a vector except the last element
--   
--   <pre>
--   &gt;&gt;&gt; init (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; init Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘init’, namely ‘Nil’
--         In the expression: init Nil
--         In an equation for ‘it’: it = init Nil
--   </pre>
init :: Vec (n + 1) a -> Vec n a

-- | Shift in elements to the head of a vector, bumping out elements at the
--   tail. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; Nil,3 :&gt; 4 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; Nil,0 :&gt; 1 :&gt; Nil)
--   </pre>
shiftInAt0 :: KnownNat n => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift in element to the tail of a vector, bumping out elements at the
--   head. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; Nil)
--   (3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; Nil) (2 :&gt; 3 :&gt; Nil)
--   (3 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftInAtN :: KnownNat m => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Add an element to the head of a vector, and extract all but the last
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; 1 +&gt;&gt; Nil
--   Nil
--   </pre>
(+>>) :: KnownNat n => a -> Vec n a -> Vec n a
infixr 4 +>>

-- | Add an element to the tail of a vector, and extract all but the first
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) &lt;&lt;+ 1
--   4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; Nil &lt;&lt;+ 1
--   Nil
--   </pre>
(<<+) :: Vec n a -> a -> Vec n a
infixl 4 <<+

-- | Shift <i>m</i> elements out from the head of a vector, filling up the
--   tail with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFrom0 d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (3 :&gt; 4 :&gt; 5 :&gt; 0 :&gt; 0 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftOutFrom0 :: (Default a, KnownNat m) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Shift <i>m</i> elements out from the tail of a vector, filling up the
--   head with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFromN d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (0 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil,4 :&gt; 5 :&gt; Nil)
--   </pre>
shiftOutFromN :: (Default a, KnownNat n) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Append two vectors.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;Nil) ++ (7:&gt;8:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 8 :&gt; Nil
--   </pre>
(++) :: Vec n a -> Vec m a -> Vec (n + m) a
infixr 5 ++

-- | Split a vector into two vectors at the given point.
--   
--   <pre>
--   &gt;&gt;&gt; splitAt (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   
--   &gt;&gt;&gt; splitAt d3 (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAt :: SNat m -> Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector into two vectors where the length of the two is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; splitAtI (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil) :: (Vec 2 Int, Vec 3 Int)
--   (1 :&gt; 2 :&gt; Nil,3 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAtI :: KnownNat m => Vec (m + n) a -> (Vec m a, Vec n a)

-- | Concatenate a vector of vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concat ((1:&gt;2:&gt;3:&gt;Nil) :&gt; (4:&gt;5:&gt;6:&gt;Nil) :&gt; (7:&gt;8:&gt;9:&gt;Nil) :&gt; (10:&gt;11:&gt;12:&gt;Nil) :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil
--   </pre>
concat :: Vec n (Vec m a) -> Vec (n * m) a

-- | Map a function over all the elements of a vector and concatentate the
--   resulting vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concatMap (replicate d3) (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 1 :&gt; 1 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; 3 :&gt; 3 :&gt; 3 :&gt; Nil
--   </pre>
concatMap :: (a -> Vec m b) -> Vec n a -> Vec (n * m) b

-- | Split a vector of (n * m) elements into a vector of "vectors of length
--   <i>m</i>", where the length <i>m</i> is given.
--   
--   <pre>
--   &gt;&gt;&gt; unconcat d4 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcat :: KnownNat n => SNat m -> Vec (n * m) a -> Vec n (Vec m a)

-- | Split a vector of <i>(n * m)</i> elements into a vector of "vectors of
--   length <i>m</i>", where the length <i>m</i> is determined by the
--   context.
--   
--   <pre>
--   &gt;&gt;&gt; unconcatI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil) :: Vec 2 (Vec 6 Int)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcatI :: (KnownNat n, KnownNat m) => Vec (n * m) a -> Vec n (Vec m a)

-- | Merge two vectors, alternating their elements, i.e.,
--   
--   <pre>
--   &gt;&gt;&gt; merge (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   1 :&gt; 5 :&gt; 2 :&gt; 6 :&gt; 3 :&gt; 7 :&gt; 4 :&gt; 8 :&gt; Nil
--   </pre>
merge :: KnownNat n => Vec n a -> Vec n a -> Vec (2 * n) a

-- | The elements in a vector in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; reverse (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
reverse :: Vec n a -> Vec n a

-- | Apply a function of every element of a vector and its index.
--   
--   <pre>
--   &gt;&gt;&gt; :t imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Index 4)
--   
--   &gt;&gt;&gt; imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   2 :&gt; 3 :&gt; *** Exception: X: Clash.Sized.Index: result 4 is out of bounds: [0..3]
--   ...
--   
--   &gt;&gt;&gt; imap (\i a -&gt; extend (bitCoerce i) + a) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Unsigned 8)
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
imap :: forall n a b. KnownNat n => (Index n -> a -> b) -> Vec n a -> Vec n b

-- | Zip two vectors with a functions that also takes the elements'
--   indices.
--   
--   <pre>
--   &gt;&gt;&gt; izipWith (\i a b -&gt; i + a + b) (2 :&gt; 2 :&gt; Nil)  (3 :&gt; 3:&gt; Nil)
--   *** Exception: X: Clash.Sized.Index: result 3 is out of bounds: [0..1]
--   ...
--   
--   &gt;&gt;&gt; izipWith (\i a b -&gt; extend (bitCoerce i) + a + b) (2 :&gt; 2 :&gt; Nil) (3 :&gt; 3 :&gt; Nil) :: Vec 2 (Unsigned 8)
--   5 :&gt; 6 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>izipWith</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third. This matters when <a>izipWith</a> is
--   used in a recursive setting. See <a>lazyV</a> for more information.
izipWith :: KnownNat n => (Index n -> a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | Right fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findLeftmost x xs = ifoldr (\i a b -&gt; if a == x then Just i else b) Nothing xs
--   
--   &gt;&gt;&gt; findLeftmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; findLeftmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldr :: KnownNat n => (Index n -> a -> b -> b) -> b -> Vec n a -> b

-- | Left fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findRightmost x xs = ifoldl (\a i b -&gt; if b == x then Just i else a) Nothing xs
--   
--   &gt;&gt;&gt; findRightmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 4
--   
--   &gt;&gt;&gt; findRightmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldl :: KnownNat n => (a -> Index n -> b -> a) -> a -> Vec n b -> a

-- | Generate a vector of indices.
--   
--   <pre>
--   &gt;&gt;&gt; indices d4
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indices :: KnownNat n => SNat n -> Vec n (Index n)

-- | Generate a vector of indices, where the length of the vector is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; indicesI :: Vec 4 (Index 4)
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indicesI :: KnownNat n => Vec n (Index n)

-- | "<a>findIndex</a> <tt>p xs</tt>" returns the index of the <i>first</i>
--   element of <i>xs</i> satisfying the predicate <i>p</i>, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 3) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 3
--   
--   &gt;&gt;&gt; findIndex (&gt; 8) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
findIndex :: KnownNat n => (a -> Bool) -> Vec n a -> Maybe (Index n)

-- | "<a>elemIndex</a> <tt>a xs</tt>" returns the index of the <i>first</i>
--   element which is equal (by <a>==</a>) to the query element <i>a</i>,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndex 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; elemIndex 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
elemIndex :: (KnownNat n, Eq a) => a -> Vec n a -> Maybe (Index n)

-- | <a>zipWith</a> generalizes <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "<a>zipWith</a> <tt>(+)</tt>" applied to two vectors produces
--   the vector of corresponding sums.
--   
--   <pre>
--   zipWith f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) == (f x1 y1 :&gt; f x2 y2 :&gt; ... :&gt; f xn yn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith</a> <tt>f xs ys</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>zipWith</a> is <i>strict</i> in its second argument, and
--   <i>lazy</i> in its third. This matters when <a>zipWith</a> is used in
--   a recursive setting. See <a>lazyV</a> for more information.
zipWith :: (a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>zipWith3</a> generalizes <a>zip3</a> by zipping with the function
--   given as the first argument, instead of a tupling function.
--   
--   <pre>
--   zipWith3 f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) (z1 :&gt; z2 :&gt; ... :&gt; zn :&gt; Nil) == (f x1 y1 z1 :&gt; f x2 y2 z2 :&gt; ... :&gt; f xn yn zn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith3</a> <tt>f xs ys zs</tt>" corresponds to the following
--   circuit layout:
--   
--   
--   <b>NB</b>: <a>zipWith3</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third and fourth. This matters when
--   <a>zipWith3</a> is used in a recursive setting. See <a>lazyV</a> for
--   more information.
zipWith3 :: (a -> b -> c -> d) -> Vec n a -> Vec n b -> Vec n c -> Vec n d
zipWith4 :: (a -> b -> c -> d -> e) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e
zipWith5 :: (a -> b -> c -> d -> e -> f) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f
zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g
zipWith7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n h

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldr1 f (x1 :&gt; ... :&gt; xn2 :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn2 `f` (xn1 `f` xn))...)
--   foldr1 f (x1 :&gt; Nil)                            == x1
--   foldr1 f Nil                                    == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (/) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldr1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldl1 f (x1 :&gt; x2 :&gt; x3 :&gt; ... :&gt; xn :&gt; Nil) == (...((x1 `f` x2) `f` x3) `f`...) `f` xn
--   foldl1 f (x1 :&gt; Nil)                          == x1
--   foldl1 f Nil                                  == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (/) (1 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldl1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>fold</a> is a variant of <a>foldr1</a> and <a>foldl1</a>, but
--   instead of reducing from right to left, or left to right, it reduces a
--   vector using a tree-like structure. The depth, or delay, of the
--   structure produced by "<tt><a>fold</a> f xs</tt>", is hence
--   <tt>O(log_2(<a>length</a> xs))</tt>, and not <tt>O(<a>length</a>
--   xs)</tt>.
--   
--   <b>NB</b>: The binary operator "<tt>f</tt>" in "<tt><a>fold</a> f
--   xs</tt>" must be associative.
--   
--   <pre>
--   fold f (x1 :&gt; x2 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == ((x1 `f` x2) `f` ...) `f` (... `f` (xn1 `f` xn))
--   fold f (x1 :&gt; Nil)                           == x1
--   fold f Nil                                   == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fold (+) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   15
--   </pre>
--   
--   "<a>fold</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
fold :: forall n a. (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a vector of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == z :&gt; (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   0 :&gt; 5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>scanl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>last (scanl f z xs) == foldl f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanl :: (b -> a -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>scanl</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanl1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   1 :&gt; -1 :&gt; -4 :&gt; -8 :&gt; Nil
--   </pre>
scanl1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>scanr</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanr1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   -2 :&gt; 3 :&gt; -1 :&gt; 4 :&gt; Nil
--   </pre>
scanr1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>postscanl</a> is a variant of <a>scanl</a> where the first result
--   is dropped:
--   
--   <pre>
--   postscanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>postscanl</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanl :: (b -> a -> b) -> b -> Vec n a -> Vec n b

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a vector of
--   successive reduced values from the right:
--   
--   <pre>
--   scanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; z :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; 0 :&gt; Nil
--   </pre>
--   
--   "<a>scanr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>head (scanr f z xs) == foldr f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanr :: (a -> b -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>postscanr</a> is a variant of <a>scanr</a> that where the last
--   result is dropped:
--   
--   <pre>
--   postscanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   "<a>postscanr</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanr :: (a -> b -> b) -> b -> Vec n a -> Vec n b

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumL (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,1 :&gt; 2 :&gt; 4 :&gt; 7 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumL</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumL :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumR (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,10 :&gt; 8 :&gt; 5 :&gt; 1 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumR</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumR :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | <a>zip</a> takes two vectors and returns a vector of corresponding
--   pairs.
--   
--   <pre>
--   &gt;&gt;&gt; zip (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil)
--   (1,4) :&gt; (2,3) :&gt; (3,2) :&gt; (4,1) :&gt; Nil
--   </pre>
zip :: Vec n a -> Vec n b -> Vec n (a, b)

-- | <a>zip3</a> takes three vectors and returns a vector of corresponding
--   triplets.
--   
--   <pre>
--   &gt;&gt;&gt; zip3 (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil) (5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   (1,4,5) :&gt; (2,3,6) :&gt; (3,2,7) :&gt; (4,1,8) :&gt; Nil
--   </pre>
zip3 :: Vec n a -> Vec n b -> Vec n c -> Vec n (a, b, c)

-- | <a>zip4</a> takes four vectors and returns a list of quadruples,
--   analogous to <a>zip</a>.
zip4 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n (a, b, c, d)

-- | <a>zip5</a> takes five vectors and returns a list of five-tuples,
--   analogous to <a>zip</a>.
zip5 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n (a, b, c, d, e)

-- | <a>zip6</a> takes six vectors and returns a list of six-tuples,
--   analogous to <a>zip</a>.
zip6 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n (a, b, c, d, e, f)

-- | <a>zip7</a> takes seven vectors and returns a list of seven-tuples,
--   analogous to <a>zip</a>.
zip7 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n (a, b, c, d, e, f, g)

-- | <a>unzip</a> transforms a vector of pairs into a vector of first
--   components and a vector of second components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip ((1,4):&gt;(2,3):&gt;(3,2):&gt;(4,1):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   </pre>
unzip :: Vec n (a, b) -> (Vec n a, Vec n b)

-- | <a>unzip3</a> transforms a vector of triplets into a vector of first
--   components, a vector of second components, and a vector of third
--   components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip3 ((1,4,5):&gt;(2,3,6):&gt;(3,2,7):&gt;(4,1,8):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil,5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
unzip3 :: Vec n (a, b, c) -> (Vec n a, Vec n b, Vec n c)

-- | <a>unzip4</a> takes a vector of quadruples and returns four vectors,
--   analogous to <a>unzip</a>.
unzip4 :: Vec n (a, b, c, d) -> (Vec n a, Vec n b, Vec n c, Vec n d)

-- | <a>unzip5</a> takes a vector of five-tuples and returns five vectors,
--   analogous to <a>unzip</a>.
unzip5 :: Vec n (a, b, c, d, e) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e)

-- | <a>unzip6</a> takes a vector of six-tuples and returns six vectors,
--   analogous to <a>unzip</a>.
unzip6 :: Vec n (a, b, c, d, e, f) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f)

-- | <a>unzip7</a> takes a vector of seven-tuples and returns seven
--   vectors, analogous to <a>unzip</a>.
unzip7 :: Vec n (a, b, c, d, e, f, g) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f, Vec n g)

-- | "<tt>xs</tt> <a>!!</a> <tt>n</tt>" returns the <i>n</i>'th element of
--   <i>xs</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 4
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! (length (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) - 1)
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 1
--   2
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 4
--   ...
--   </pre>
(!!) :: (KnownNat n, Enum i) => Vec n a -> i -> a

-- | The length of a <a>Vec</a>tor as an <a>Int</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; length (6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   3
--   </pre>
length :: KnownNat n => Vec n a -> Int

-- | "<a>replace</a> <tt>n a xs</tt>" returns the vector <i>xs</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; replace 3 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 0 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   7 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 9 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; *** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 4
--   ...
--   </pre>
replace :: (KnownNat n, Enum i) => i -> a -> Vec n a -> Vec n a

-- | "<a>take</a> <tt>n xs</tt>" returns the <i>n</i>-length prefix of
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; take (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d0               (1:&gt;2:&gt;Nil)
--   Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘4 + n0’ with ‘2’
--         Expected type: Vec (4 + n0) a
--           Actual type: Vec (1 + 1) a
--         The type variable ‘n0’ is ambiguous
--       • In the second argument of ‘take’, namely ‘(1 :&gt; 2 :&gt; Nil)’
--         In the expression: take d4 (1 :&gt; 2 :&gt; Nil)
--         In an equation for ‘it’: it = take d4 (1 :&gt; 2 :&gt; Nil)
--   </pre>
take :: SNat m -> Vec (m + n) a -> Vec m a

-- | "<a>takeI</a> <tt>xs</tt>" returns the prefix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; takeI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   1 :&gt; 2 :&gt; Nil
--   </pre>
takeI :: KnownNat m => Vec (m + n) a -> Vec m a

-- | "<a>drop</a> <tt>n xs</tt>" returns the suffix of <i>xs</i> after the
--   first <i>n</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; drop (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d0               (1:&gt;2:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; drop d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...: error:...
--       • Couldn't match...type ‘4 + n0...
--         The type variable ‘n0’ is ambiguous
--       • In the first argument of ‘print’, namely ‘it’
--         In a stmt of an interactive GHCi command: print it
--   </pre>
drop :: SNat m -> Vec (m + n) a -> Vec n a

-- | "<a>dropI</a> <tt>xs</tt>" returns the suffix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; dropI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   4 :&gt; 5 :&gt; Nil
--   </pre>
dropI :: KnownNat m => Vec (m + n) a -> Vec n a

-- | "<a>at</a> <tt>n xs</tt>" returns <i>n</i>'th element of <i>xs</i>
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; at (SNat :: SNat 1) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   
--   &gt;&gt;&gt; at d1               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   </pre>
at :: SNat m -> Vec (m + (n + 1)) a -> a

-- | "<a>select</a> <tt>f s n xs</tt>" selects <i>n</i> elements with
--   step-size <i>s</i> and offset <tt>f</tt> from <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; select (SNat :: SNat 1) (SNat :: SNat 2) (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; select d1 d2 d3 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   </pre>
select :: CmpNat (i + s) (s * n) ~ 'GT => SNat f -> SNat s -> SNat n -> Vec (f + i) a -> Vec n a

-- | "<a>selectI</a> <tt>f s xs</tt>" selects as many elements as demanded
--   by the context with step-size <i>s</i> and offset <i>f</i> from
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; selectI d1 d2 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil) :: Vec 2 Int
--   2 :&gt; 4 :&gt; Nil
--   </pre>
selectI :: (CmpNat (i + s) (s * n) ~ 'GT, KnownNat n) => SNat f -> SNat s -> Vec (f + i) a -> Vec n a

-- | "<a>replicate</a> <tt>n a</tt>" returns a vector that has <i>n</i>
--   copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; replicate (SNat :: SNat 3) 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; replicate d3 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
replicate :: SNat n -> a -> Vec n a

-- | "<a>repeat</a> <tt>a</tt>" creates a vector with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; repeat 6 :: Vec 5 Int
--   6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
repeat :: KnownNat n => a -> Vec n a

-- | "<a>iterate</a> <tt>n f x</tt>" returns a vector starting with
--   <i>x</i> followed by <i>n</i> repeated applications of <i>f</i> to
--   <i>x</i>.
--   
--   <pre>
--   iterate (SNat :: SNat 4) f x == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   iterate d4 f x               == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterate d4 (+1) 1
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>iterate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
iterate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>iterateI</a> <tt>f x</tt>" returns a vector starting with
--   <tt>x</tt> followed by <tt>n</tt> repeated applications of <tt>f</tt>
--   to <tt>x</tt>, where <tt>n</tt> is determined by the context.
--   
--   <pre>
--   iterateI f x :: Vec 3 a == (x :&gt; f x :&gt; f (f x) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterateI (+1) 1 :: Vec 3 Int
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   "<a>iterateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
iterateI :: forall n a. KnownNat n => (a -> a) -> a -> Vec n a

-- | "<a>unfoldr</a> <tt>n f s</tt>" builds a vector of length <tt>n</tt>
--   from a seed value <tt>s</tt>, where every element <tt>a</tt> is
--   created by successive calls of <tt>f</tt> on <tt>s</tt>. Unlike
--   <a>unfoldr</a> from <a>Data.List</a> the generating function
--   <tt>f</tt> cannot dictate the length of the resulting vector, it must
--   be statically known.
--   
--   a simple use of <a>unfoldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr d10 (\s -&gt; (s,s-1)) 10
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldr :: SNat n -> (s -> (a, s)) -> s -> Vec n a

-- | "<a>unfoldrI</a> <tt>f s</tt>" builds a vector from a seed value
--   <tt>s</tt>, where every element <tt>a</tt> is created by successive
--   calls of <tt>f</tt> on <tt>s</tt>; the length of the vector is
--   inferred from the context. Unlike <a>unfoldr</a> from <a>Data.List</a>
--   the generating function <tt>f</tt> cannot dictate the length of the
--   resulting vector, it must be statically known.
--   
--   a simple use of <a>unfoldrI</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldrI (\s -&gt; (s,s-1)) 10 :: Vec 10 Int
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldrI :: KnownNat n => (s -> (a, s)) -> s -> Vec n a

-- | "<a>generate</a> <tt>n f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>.
--   
--   <pre>
--   generate (SNat :: SNat 4) f x == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   generate d4 f x               == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generate d4 (+1) 1
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>generate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
generate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>generateI</a> <tt>f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>, where <tt>n</tt> is
--   determined by the context.
--   
--   <pre>
--   generateI f x :: Vec 3 a == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generateI (+1) 1 :: Vec 3 Int
--   2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>generateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
generateI :: KnownNat n => (a -> a) -> a -> Vec n a

-- | Transpose a matrix: go from row-major to column-major
--   
--   <pre>
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;Nil):&gt;(3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; transpose xss
--   (1 :&gt; 3 :&gt; 5 :&gt; Nil) :&gt; (2 :&gt; 4 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
transpose :: KnownNat n => Vec m (Vec n a) -> Vec n (Vec m a)

-- | 1-dimensional stencil computations
--   
--   "<a>stencil1d</a> <tt>stX f xs</tt>", where <i>xs</i> has <i>stX +
--   n</i> elements, applies the stencil computation <i>f</i> on: <i>n +
--   1</i> overlapping (1D) windows of length <i>stX</i>, drawn from
--   <i>xs</i>. The resulting vector has <i>n + 1</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t stencil1d d2 sum xs
--   stencil1d d2 sum xs :: Num b =&gt; Vec 5 b
--   
--   &gt;&gt;&gt; stencil1d d2 sum xs
--   3 :&gt; 5 :&gt; 7 :&gt; 9 :&gt; 11 :&gt; Nil
--   </pre>
stencil1d :: KnownNat n => SNat (stX + 1) -> (Vec (stX + 1) a -> b) -> Vec ((stX + n) + 1) a -> Vec (n + 1) b

-- | 2-dimensional stencil computations
--   
--   "<a>stencil2d</a> <tt>stY stX f xss</tt>", where <i>xss</i> is a
--   matrix of <i>stY + m</i> rows of <i>stX + n</i> elements, applies the
--   stencil computation <i>f</i> on: <i>(m + 1) * (n + 1)</i> overlapping
--   (2D) windows of <i>stY</i> rows of <i>stX</i> elements, drawn from
--   <i>xss</i>. The result matrix has <i>m + 1</i> rows of <i>n + 1</i>
--   elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t stencil2d d2 d2 (sum . map sum) xss
--   stencil2d d2 d2 (sum . map sum) xss :: Num b =&gt; Vec 3 (Vec 3 b)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stencil2d d2 d2 (sum . map sum) xss
--   (14 :&gt; 18 :&gt; 22 :&gt; Nil) :&gt; (30 :&gt; 34 :&gt; 38 :&gt; Nil) :&gt; (46 :&gt; 50 :&gt; 54 :&gt; Nil) :&gt; Nil
--   </pre>
stencil2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> (Vec (stY + 1) (Vec (stX + 1) a) -> b) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) b)

-- | "<a>windows1d</a> <tt>stX xs</tt>", where the vector <i>xs</i> has
--   <i>stX + n</i> elements, returns a vector of <i>n + 1</i> overlapping
--   (1D) windows of <i>xs</i> of length <i>stX</i>.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t windows1d d2 xs
--   windows1d d2 xs :: Num a =&gt; Vec 5 (Vec 2 a)
--   
--   &gt;&gt;&gt; windows1d d2 xs
--   (1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
windows1d :: KnownNat n => SNat (stX + 1) -> Vec ((stX + n) + 1) a -> Vec (n + 1) (Vec (stX + 1) a)

-- | "<a>windows2d</a> <tt>stY stX xss</tt>", where matrix <i>xss</i> has
--   <i>stY + m</i> rows of <i>stX + n</i>, returns a matrix of <i>m+1</i>
--   rows of <i>n+1</i> elements. The elements of this new matrix are the
--   overlapping (2D) windows of <i>xss</i>, where every window has
--   <i>stY</i> rows of <i>stX</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   
--   &gt;&gt;&gt; :t windows2d d2 d2 xss
--   windows2d d2 d2 xss :: Num a =&gt; Vec 3 (Vec 3 (Vec 2 (Vec 2 a)))
--   
--   &gt;&gt;&gt; windows2d d2 d2 xss
--   (((1 :&gt; 2 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil) :&gt; ((2 :&gt; 3 :&gt; Nil) :&gt; (6 :&gt; 7 :&gt; Nil) :&gt; Nil) :&gt; ((3 :&gt; 4 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((5 :&gt; 6 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; Nil) :&gt; Nil) :&gt; ((6 :&gt; 7 :&gt; Nil) :&gt; (10 :&gt; 11 :&gt; Nil) :&gt; Nil) :&gt; ((7 :&gt; 8 :&gt; Nil) :&gt; (11 :&gt; 12 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((9 :&gt; 10 :&gt; Nil) :&gt; (13 :&gt; 14 :&gt; Nil) :&gt; Nil) :&gt; ((10 :&gt; 11 :&gt; Nil) :&gt; (14 :&gt; 15 :&gt; Nil) :&gt; Nil) :&gt; ((11 :&gt; 12 :&gt; Nil) :&gt; (15 :&gt; 16 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; Nil
--   </pre>
windows2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) (Vec (stY + 1) (Vec (stX + 1) a)))

-- | Forward permutation specified by an index mapping, <i>ix</i>. The
--   result vector is initialized by the given defaults, <i>def</i>, and an
--   further values that are permuted into the result are added to the
--   current value using the given combination function, <i>f</i>.
--   
--   The combination function must be <i>associative</i> and
--   <i>commutative</i>.
permute :: (Enum i, KnownNat n, KnownNat m) => (a -> a -> a) -> Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>backpermute</a> <tt>xs is</tt>" is equivalent to "<a>map</a>
--   <tt>(xs <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; backpermute input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
backpermute :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | Copy elements from the source vector, <i>xs</i>, to the destination
--   vector according to an index mapping <i>is</i>. This is a forward
--   permute operation where a <i>to</i> vector encodes an input to output
--   index mapping. Output elements for indices that are not mapped assume
--   the value in the default vector <i>def</i>.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let defVec = 0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;Nil
--   
--   &gt;&gt;&gt; let to = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;8:&gt;Nil
--   
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; scatter defVec to input
--   0 :&gt; 1 :&gt; 4 :&gt; 9 :&gt; 0 :&gt; 4 :&gt; 0 :&gt; 6 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: If the same index appears in the index mapping more than
--   once, the latest mapping is chosen.
scatter :: (Enum i, KnownNat n, KnownNat m) => Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>gather</a> <tt>xs is</tt>" is equivalent to "<a>map</a> <tt>(xs
--   <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; gather input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
gather :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | "<a>interleave</a> <tt>d xs</tt>" creates a vector:
--   
--   <pre>
--   &lt;x_0,x_d,x_(2d),...,x_1,x_(d+1),x_(2d+1),...,x_(d-1),x_(2d-1),x_(3d-1)&gt;
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; Nil
--   
--   &gt;&gt;&gt; interleave d3 xs
--   1 :&gt; 4 :&gt; 7 :&gt; 2 :&gt; 5 :&gt; 8 :&gt; 3 :&gt; 6 :&gt; 9 :&gt; Nil
--   </pre>
interleave :: (KnownNat n, KnownNat d) => SNat d -> Vec (n * d) a -> Vec (d * n) a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs (-1)
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeftS</a> if you want to rotate left by a
--   <i>static</i> amount.
rotateLeft :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs (-1)
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRightS</a> if you want to rotate right by a
--   <i>static</i> amount.
rotateRight :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeftS xs d1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeft</a> if you want to rotate left by a
--   <i>dynamic</i> amount.
rotateLeftS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRightS xs d1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRight</a> if you want to rotate right by a
--   <i>dynamic</i> amount.
rotateRightS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | Convert a vector to a list.
--   
--   <pre>
--   &gt;&gt;&gt; toList (1:&gt;2:&gt;3:&gt;Nil)
--   [1,2,3]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
toList :: Vec n a -> [a]

-- | Create a vector literal from a list literal.
--   
--   <pre>
--   $(listToVecTH [1::Signed 8,2,3,4,5]) == (8:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 5 (Signed 8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1 :: Signed 8,2,3,4,5]
--   [1,2,3,4,5]
--   
--   &gt;&gt;&gt; $(listToVecTH [1::Signed 8,2,3,4,5])
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
listToVecTH :: Lift a => [a] -> ExpQ

-- | <a>Vec</a>tor as a <a>Proxy</a> for <a>Nat</a>
asNatProxy :: Vec n a -> Proxy n

-- | Length of a <a>Vec</a>tor as an <a>SNat</a> value
lengthS :: KnownNat n => Vec n a -> SNat n

-- | What you should use when your vector functions are too strict in their
--   arguments.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwapL a b = if a &lt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; :{
--   let sortVL :: (Ord a, KnownNat (n + 1)) =&gt; Vec ((n + 1) + 1) a -&gt; Vec ((n + 1) + 1) a
--       sortVL xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith compareSwapL (lazyV lefts) rights
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let sortV_flip xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith (flip compareSwapL) rights lefts
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   For example:
--   
--   <pre>
--   -- Bubble sort for 1 iteration
--   sortV xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL lefts rights
--   
--   -- Compare and swap
--   compareSwapL a b = if a &lt; b then (a,b)
--                               else (b,a)
--   </pre>
--   
--   Will not terminate because <a>zipWith</a> is too strict in its second
--   argument.
--   
--   In this case, adding <a>lazyV</a> on <a>zipWith</a>s second argument:
--   
--   <pre>
--   sortVL xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; map snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL (<a>lazyV</a> lefts) rights
--   </pre>
--   
--   Results in a successful computation:
--   
--   <pre>
--   &gt;&gt;&gt; sortVL (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: There is also a solution using <a>flip</a>, but it slightly
--   obfuscates the meaning of the code:
--   
--   <pre>
--   sortV_flip xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> (<a>flip</a> compareSwapL) rights lefts
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sortV_flip (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
lazyV :: KnownNat n => Vec n a -> Vec n a

-- | A <i>dependently</i> typed fold.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -fplugin GHC.TypeLits.Normalise
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data Append (m :: Nat) (a :: Type) (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply (Append m a) l = Vec (l + m) a
--   
--   &gt;&gt;&gt; let append' xs ys = dfold (Proxy :: Proxy (Append m a)) (const (:&gt;)) ys xs
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   Using lists, we can define <i>append</i> (a.k.a.
--   <tt>Data.List.</tt><a>++</a>) in terms of
--   <tt>Data.List.</tt><a>foldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List
--   
--   &gt;&gt;&gt; let append xs ys = Data.List.foldr (:) ys xs
--   
--   &gt;&gt;&gt; append [1,2] [3,4]
--   [1,2,3,4]
--   </pre>
--   
--   However, when we try to do the same for <a>Vec</a>, by defining
--   <i>append'</i> in terms of <tt>Clash.Sized.Vector.</tt><a>foldr</a>:
--   
--   <pre>
--   append' xs ys = <a>foldr</a> (:&gt;) ys xs
--   </pre>
--   
--   we get a type error:
--   
--   <pre>
--   <b>&gt;&gt;&gt; let append' xs ys = foldr (:&gt;) ys xs</b>
--   
--   &lt;interactive&gt;:...
--       • Occurs check: cannot construct the infinite type: ... ~ ... + 1
--         Expected type: a -&gt; Vec ... a -&gt; Vec ... a
--           Actual type: a -&gt; Vec ... a -&gt; Vec (... + 1) a
--       • In the first argument of ‘foldr’, namely ‘(:&gt;)’
--         In the expression: foldr (:&gt;) ys xs
--         In an equation for ‘append'’: append' xs ys = foldr (:&gt;) ys xs
--       • Relevant bindings include
--           ys :: Vec ... a (bound at ...)
--           append' :: Vec n a -&gt; Vec ... a -&gt; Vec ... a
--             (bound at ...)
--   </pre>
--   
--   The reason is that the type of <a>foldr</a> is:
--   
--   <pre>
--   &gt;&gt;&gt; :t foldr
--   foldr :: (a -&gt; b -&gt; b) -&gt; b -&gt; Vec n a -&gt; b
--   </pre>
--   
--   While the type of (<a>:&gt;</a>) is:
--   
--   <pre>
--   &gt;&gt;&gt; :t (:&gt;)
--   (:&gt;) :: a -&gt; Vec n a -&gt; Vec (n + 1) a
--   </pre>
--   
--   We thus need a <tt>fold</tt> function that can handle the growing
--   vector type: <a>dfold</a>. Compared to <a>foldr</a>, <a>dfold</a>
--   takes an extra parameter, called the <i>motive</i>, that allows the
--   folded function to have an argument and result type that
--   <i>depends</i> on the current length of the vector. Using
--   <a>dfold</a>, we can now correctly define <i>append'</i>:
--   
--   <pre>
--   import Data.Singletons
--   import Data.Proxy
--   
--   data Append (m :: Nat) (a :: Type) (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> (Append m a) l = <a>Vec</a> (l + m) a
--   
--   append' xs ys = <a>dfold</a> (Proxy :: Proxy (Append m a)) (const (<a>:&gt;</a>)) ys xs
--   </pre>
--   
--   We now see that <i>append'</i> has the appropriate type:
--   
--   <pre>
--   &gt;&gt;&gt; :t append'
--   append' :: KnownNat k =&gt; Vec k a -&gt; Vec m a -&gt; Vec (k + m) a
--   </pre>
--   
--   And that it works:
--   
--   <pre>
--   &gt;&gt;&gt; append' (1 :&gt; 2 :&gt; Nil) (3 :&gt; 4 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: "<tt><a>dfold</a> m f z xs</tt>" creates a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Look at <a>dtfold</a> for a <i>dependently</i> typed fold
--   that produces a structure with a depth of O(log_2(<tt><a>length</a>
--   xs</tt>)).
dfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (forall l. SNat l -> a -> (p @@ l) -> p @@ (l + 1)) -> (p @@ 0) -> Vec k a -> p @@ k

-- | A combination of <a>dfold</a> and <a>fold</a>: a <i>dependently</i>
--   typed fold that reduces a vector in a tree-like structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XUndecidableInstances
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data IIndex (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply IIndex l = Index ((2^l)+1)
--   
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat k, KnownNat (2^k)) =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--       populationCount' bv = dtfold (Proxy @IIndex)
--                                    fromIntegral
--                                    (\_ x y -&gt; add x y)
--                                    (bv2v bv)
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <a>BitVector</a>. Given a vector of <i>n</i> bits, we
--   only need we need a data type that can represent the number <i>n</i>:
--   <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a range of
--   <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits), hence we need
--   <a>Index</a> <tt>n+1</tt>. As an initial attempt we will use
--   <a>sum</a>, because it gives a nice (<tt>log2(n)</tt>) tree-structure
--   of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (n+1), KnownNat (n+2))
--                   =&gt; <a>BitVector</a> (n+1) -&gt; <a>Index</a> (n+2)
--   populationCount = sum . map fromIntegral . <a>bv2v</a>
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>add</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <a>fold</a> to create a tree-structure
--   of <a>add</a>es:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (n+1), KnownNat (n+2))
--                        =&gt; BitVector (n+1) -&gt; Index (n+2)
--       populationCount' = fold add . map fromIntegral . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘((n + 2) + (n + 2)) - 1’ with ‘n + 2’
--         Expected type: Index (n + 2) -&gt; Index (n + 2) -&gt; Index (n + 2)
--           Actual type: Index (n + 2)
--                        -&gt; Index (n + 2) -&gt; AResult (Index (n + 2)) (Index (n + 2))
--       • In the first argument of ‘fold’, namely ‘add’
--         In the first argument of ‘(.)’, namely ‘fold add’
--         In the expression: fold add . map fromIntegral . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (n + 1) -&gt; Index (n + 2)
--             (bound at ...)
--   </pre>
--   
--   because <a>fold</a> expects a function of type "<tt>a -&gt; a -&gt;
--   a</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>add</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons
--   import Data.Proxy
--   
--   data IIndex (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>dtfold</a> (Proxy @IIndex)
--                                fromIntegral
--                                (\_ x y -&gt; <a>add</a> x y)
--                                (<a>bv2v</a> bv)
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
--   
--   Some final remarks:
--   
--   <ul>
--   <li>By using <a>dtfold</a> instead of <a>fold</a>, we had to restrict
--   our <a>BitVector</a> argument to have bit-width that is a power of
--   2.</li>
--   <li>Even though our original <i>populationCount</i> function specified
--   a structure where all adders had the same width. Most
--   VHDL/(System)Verilog synthesis tools will create a more efficient
--   circuit, i.e. one where the adders have an increasing bit-width for
--   every layer, from the VHDL/(System)Verilog produced by the Clash
--   compiler.</li>
--   </ul>
--   
--   <b>NB</b>: The depth, or delay, of the structure produced by
--   "<tt><a>dtfold</a> m f g xs</tt>" is O(log_2(<tt><a>length</a>
--   xs</tt>)).
dtfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (a -> p @@ 0) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> p @@ (l + 1)) -> Vec (2 ^ k) a -> p @@ k

-- | Specialised version of <a>dfold</a> that builds a triangular
--   computational structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; let insert y xs = let (y',xs') = mapAccumL compareSwap y xs in xs' :&lt; y'
--   
--   &gt;&gt;&gt; let insertionSort = vfold (const insert)
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   <pre>
--   compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   insert y xs     = let (y',xs') = <a>mapAccumL</a> compareSwap y xs in xs' <a>:&lt;</a> y'
--   insertionSort   = <a>vfold</a> (const insert)
--   </pre>
--   
--   Builds a triangular structure of compare and swaps to sort a row.
--   
--   <pre>
--   &gt;&gt;&gt; insertionSort (7 :&gt; 3 :&gt; 9 :&gt; 1 :&gt; Nil)
--   1 :&gt; 3 :&gt; 7 :&gt; 9 :&gt; Nil
--   </pre>
--   
--   The circuit layout of <tt>insertionSort</tt>, build using
--   <a>vfold</a>, is:
--   
vfold :: forall k a b. KnownNat k => (forall l. SNat l -> a -> Vec l b -> Vec (l + 1) b) -> Vec k a -> Vec k b

-- | The largest element of a non-empty vector
maximum :: Ord a => Vec (n + 1) a -> a

-- | The least element of a non-empty vector
minimum :: Ord a => Vec (n + 1) a -> a

-- | Apply a function to every element of a vector and the element's
--   position (as an <a>SNat</a> value) in the vector.
--   
--   <pre>
--   &gt;&gt;&gt; let rotateMatrix = smap (flip rotateRightS)
--   
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; rotateMatrix xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; 1 :&gt; Nil) :&gt; Nil
--   </pre>
smap :: forall k a b. KnownNat k => (forall l. SNat l -> a -> b) -> Vec k a -> Vec k b
concatBitVector# :: forall n m. (KnownNat n, KnownNat m) => Vec n (BitVector m) -> BitVector (n * m)
unconcatBitVector# :: forall n m. (KnownNat n, KnownNat m) => BitVector (n * m) -> Vec n (BitVector m)

-- | Convert a <a>Vec</a> of <a>Bit</a>s to a <a>BitVector</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let x = (0:&gt;0:&gt;0:&gt;1:&gt;0:&gt;0:&gt;1:&gt;0:&gt;Nil) :: Vec 8 Bit
--   
--   &gt;&gt;&gt; x
--   0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; Nil
--   
--   &gt;&gt;&gt; v2bv x
--   0b0001_0010
--   </pre>
v2bv :: KnownNat n => Vec n Bit -> BitVector n

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument
seqV :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqV`

-- | Evaluate all elements of a vector to WHNF
forceV :: KnownNat n => Vec n a -> Vec n a

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument. Does not propagate <a>XException</a>s.
seqVX :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqVX`

-- | Evaluate all elements of a vector to WHNF. Does not propagate
--   <a>XException</a>s.
forceVX :: KnownNat n => Vec n a -> Vec n a

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <a>id</a>
--   <a>to</a> . <a>from</a> ≡ <a>id</a>
--   </pre>
class Generic a

-- | Representable types of kind <tt>* -&gt; *</tt> (or kind <tt>k -&gt;
--   *</tt>, when <tt>PolyKinds</tt> is enabled). This class is derivable
--   in GHC with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic1</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from1</a> . <a>to1</a> ≡ <a>id</a>
--   <a>to1</a> . <a>from1</a> ≡ <a>id</a>
--   </pre>
class Generic1 (f :: k -> Type)


-- | <b>This is the <a>Safe</a> API only of <a>Clash.Prelude</a></b>
--   
--   Clash is a functional hardware description language that borrows both
--   its syntax and semantics from the functional programming language
--   Haskell. The merits of using a functional language to describe
--   hardware comes from the fact that combinational circuits can be
--   directly modeled as mathematical functions and that functional
--   languages lend themselves very well at describing and (de-)composing
--   mathematical functions.
--   
--   This package provides:
--   
--   <ul>
--   <li>Prelude library containing datatypes and functions for circuit
--   design</li>
--   </ul>
--   
--   To use the library:
--   
--   <ul>
--   <li>Import <a>Clash.Prelude</a></li>
--   <li>Additionally import <a>Clash.Explicit.Prelude</a> if you want to
--   design explicitly clocked circuits in a multi-clock setting</li>
--   </ul>
--   
--   For now, <a>Clash.Prelude</a> is also the best starting point for
--   exploring the library. A preliminary version of a tutorial can be
--   found in <a>Clash.Tutorial</a>. Some circuit examples can be found in
--   <a>Clash.Examples</a>.
module Clash.Prelude.Safe

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac :: HiddenClockResetEnable dom  =&gt; <a>Signal</a> dom (Int, Int) -&gt; <a>Signal</a> dom Int
--   mac = <a>mealy</a> macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockResetEnable dom
--     =&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> macT 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> macT 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: (HiddenClockResetEnable dom, NFDataX s) => (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o

-- | Create a synchronous function from a combinational function describing
--   a mealy machine using the state monad. This can be particularly useful
--   when combined with lenses or optics to replicate imperative
--   algorithms.
--   
--   <pre>
--   data DelayState = DelayState
--     { _history    :: Vec 4 Int
--     , _untilValid :: Index 4
--     }
--     deriving (Generic, NFDataX)
--   makeLenses ''DelayState
--   
--   initialDelayState = DelayState (repeat 0) maxBound
--   
--   delayS :: Int -&gt; State DelayState (Maybe Int)
--   delayS n = do
--     history   %= (n +&gt;&gt;)
--     remaining &lt;- use untilValid
--     if remaining &gt; 0
--     then do
--        untilValid -= 1
--        return Nothing
--      else do
--        out &lt;- uses history last
--        return (Just out)
--   
--   delayTop :: HiddenClockResetEnable dom  =&gt; <a>Signal</a> dom Int -&gt; <a>Signal</a> dom (Maybe Int)
--   delayTop = <a>mealyS</a> delayS initialDelayState
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; L.take 7 $ simulate @System delayTop [1,2,3,4,5,6,7,8]
--   [Nothing,Nothing,Nothing,Just 1,Just 2,Just 3,Just 4]
--   ...
--   </pre>
mealyS :: (HiddenClockResetEnable dom, NFDataX s) => (i -> State s o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool, Int) -&gt; (Int, (Int, Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>mealy</a> f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>mealy</a> f 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> f 3 (c,i1)
--   </pre>
mealyB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | A version of <a>mealyS</a> that does automatic <a>Bundle</a>ing, see
--   <a>mealyB</a> for details.
mealySB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (i -> State s o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Infix version of <a>mealyB</a>
(<^>) :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; Int        -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: HiddenClockResetEnable dom
--     =&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac = <a>moore</a> mac id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14,30,...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockResetEnable dom
--     =&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> macT id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> macT id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: (HiddenClockResetEnable dom, NFDataX s) => (s -> i -> s) -> (s -> o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>moore</a> t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>moore</a> t o 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> t o 3 (c,i1)
--   </pre>
mooreB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> s) -> (s -> o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   '(Signal a, Signal b)')
--   
--   <pre>
--   rP :: HiddenClockResetEnable dom
--      =&gt; (Signal dom Int, Signal dom Int)
--      -&gt; (Signal dom Int, Signal dom Int)
--   rP = registerB (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System rP [(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: (HiddenClockResetEnable dom, NFDataX a, Bundle a) => a -> Unbundled dom a -> Unbundled dom a
infixr 3 `registerB`

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFile</a> and
--   <a>asyncRomBlob</a> for different approaches that scale well.</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr, NFDataX a) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFilePow2</a> and
--   <a>asyncRomBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
asyncRomPow2 :: (KnownNat n, NFDataX a) => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFile</a> and
--   <a>romBlob</a> for different approaches that scale well.</li>
--   </ul>
rom :: forall dom n m a. (NFDataX a, KnownNat n, KnownNat m, HiddenClock dom, HiddenEnable dom) => Vec n a -> Signal dom (Unsigned m) -> Signal dom a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFilePow2</a> and
--   <a>romBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
romPow2 :: forall dom n a. (KnownNat n, NFDataX a, HiddenClock dom, HiddenEnable dom) => Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom a

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlob :: Enum addr => MemBlob n m -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlobPow2 :: KnownNat n => MemBlob (2 ^ n) m -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlob :: forall dom addr m n. (HiddenClock dom, HiddenEnable dom, Enum addr) => MemBlob n m -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlobPow2 :: forall dom m n. (HiddenClock dom, HiddenEnable dom, KnownNat n) => MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, NFDataX addr, HiddenClock dom, HiddenEnable dom, HasCallStack, NFDataX a) => SNat n -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: (KnownNat n, HiddenClock dom, HiddenEnable dom, HasCallStack, NFDataX a) => Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRam</a> inits) rd
--   wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFile</a> and
--   <a>blockRamBlob</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram40
--     :: <a>HiddenClock</a> dom
--     =&gt; <a>Signal</a> dom (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram40 = <a>blockRam</a> (<a>replicate</a> d40 1)
--   </pre>
blockRam :: (HasCallStack, HiddenClock dom, HiddenEnable dom, NFDataX a, Enum addr, NFDataX addr) => Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamPow2</a> inits) rd
--   wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFilePow2</a> and
--   <a>blockRamBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram32
--     :: <a>HiddenClock</a> dom
--     =&gt; <a>Signal</a> dom (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram32 = <a>blockRamPow2</a> (<a>replicate</a> d32 1)
--   </pre>
blockRamPow2 :: (HasCallStack, HiddenClock dom, HiddenEnable dom, NFDataX a, KnownNat n) => Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamBlob</a> content)
--   rd wrM</tt>.</li>
--   </ul>
blockRamBlob :: forall dom addr m n. (HiddenClock dom, HiddenEnable dom, Enum addr, NFDataX addr) => MemBlob n m -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamBlobPow2</a>
--   content) rd wrM</tt>.</li>
--   </ul>
blockRamBlobPow2 :: forall dom m n. (HiddenClock dom, HiddenEnable dom, KnownNat n) => MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]

-- | Create a read-after-write block RAM from a read-before-write one
--   
--   <pre>
--   &gt;&gt;&gt; :t readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--   readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--     :: ...
--        ...
--        ...
--        ...
--        ... =&gt;
--        Signal dom addr -&gt; Signal dom (Maybe (addr, a)) -&gt; Signal dom a
--   </pre>
readNew :: (HiddenClockResetEnable dom, NFDataX a, Eq addr) => (Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Produces vendor-agnostic HDL that will be inferred as a true dual-port
--   block RAM
--   
--   Any value that is being written on a particular port is also the value
--   that will be read on that port, i.e. the same-port read/write behavior
--   is: WriteFirst. For mixed-port read/write, when port A writes to the
--   address port B reads from, the output of port B is undefined, and vice
--   versa.
trueDualPortBlockRam :: forall nAddrs dom a. (HasCallStack, KnownNat nAddrs, HiddenClock dom, NFDataX a) => Signal dom (RamOp nAddrs a) -> Signal dom (RamOp nAddrs a) -> (Signal dom a, Signal dom a)

-- | Port operation
data RamOp n a

-- | Read from address
RamRead :: Index n -> RamOp n a

-- | Write data to address
RamWrite :: Index n -> a -> RamOp n a

-- | No operation
RamNoOp :: RamOp n a

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (HiddenClockResetEnable dom, NFDataX a, Bounded a, Eq a) => a -> Signal dom a -> Signal dom Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (HiddenClockResetEnable dom, NFDataX a, Bounded a, Eq a) => a -> Signal dom a -> Signal dom Bool

-- | Give a pulse every <tt>n</tt> clock cycles. This is a useful helper
--   function when combined with functions like <tt><a>regEn</a></tt> or
--   <tt><a>mux</a></tt>, in order to delay a register by a known amount.
--   
--   To be precise: the given signal will be <tt><a>False</a></tt> for the
--   next <tt>n-1</tt> cycles, followed by a single <tt><a>True</a></tt>
--   value:
--   
--   <pre>
--   &gt;&gt;&gt; Prelude.last (sampleN @System 1025 (riseEvery d1024)) == True
--   True
--   
--   &gt;&gt;&gt; Prelude.or (sampleN @System 1024 (riseEvery d1024)) == False
--   True
--   </pre>
--   
--   For example, to update a counter once every 10 million cycles:
--   
--   <pre>
--   counter = <a>regEn</a> 0 (<a>riseEvery</a> (<a>SNat</a> :: <a>SNat</a> 10000000)) (counter + 1)
--   </pre>
riseEvery :: HiddenClockResetEnable dom => SNat n -> Signal dom Bool

-- | Oscillate a <tt><a>Bool</a></tt> for a given number of cycles. This is
--   a convenient function when combined with something like
--   <tt><a>regEn</a></tt>, as it allows you to easily hold a register
--   value for a given number of cycles. The input <tt><a>Bool</a></tt>
--   determines what the initial value is.
--   
--   To oscillate on an interval of 5 cycles:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 11 (oscillate False d5)
--   [False,False,False,False,False,False,True,True,True,True,True]
--   </pre>
--   
--   To oscillate between <tt><a>True</a></tt> and <tt><a>False</a></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 11 (oscillate False d1)
--   [False,False,True,False,True,False,True,False,True,False,True]
--   </pre>
--   
--   An alternative definition for the above could be:
--   
--   <pre>
--   &gt;&gt;&gt; let osc' = register False (not &lt;$&gt; osc')
--   
--   &gt;&gt;&gt; sampleN @System 200 (oscillate False d1) == sampleN @System 200 osc'
--   True
--   </pre>
oscillate :: HiddenClockResetEnable dom => Bool -> SNat n -> Signal dom Bool

-- | Fixed size vectors.
--   
--   <ul>
--   <li>Lists with their length encoded in their type</li>
--   <li><a>Vec</a>tor elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.</li>
--   </ul>
data Vec :: Nat -> Type -> Type
[Nil] :: Vec 0 a
[Cons] :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the head of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; 3:&gt;4:&gt;5:&gt;Nil
--   3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = 3:&gt;4:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 3 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (x :&gt; y :&gt; _) = x + y
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   7
--   </pre>
--   
--   Also in conjunctions with (<a>:&lt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:>) :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the tail of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   3 :&gt; 4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 4 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (_ :&lt; y :&lt; x) = y + x
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   13
--   </pre>
--   
--   Also in conjunctions with (<a>:&gt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:<) :: Vec n a -> a -> Vec (n + 1) a
infixr 5 :>
infixl 5 :<
infixr 5 `Cons`

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from left to right:
--   
--   <pre>
--   foldl f z (x1 :&gt; x2 :&gt; ... :&gt; xn :&gt; Nil) == (...((z `f` x1) `f` x2) `f`...) `f` xn
--   foldl f z Nil                            == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldl :: (b -> a -> b) -> b -> Vec n a -> b

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z (x1 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn1 `f` (xn `f` z))...)
--   foldr r z Nil                             == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldr :: (a -> b -> b) -> b -> Vec n a -> b

-- | "<a>map</a> <tt>f xs</tt>" is the vector obtained by applying <i>f</i>
--   to each element of <i>xs</i>, i.e.,
--   
--   <pre>
--   map f (x1 :&gt; x2 :&gt;  ... :&gt; xn :&gt; Nil) == (f x1 :&gt; f x2 :&gt; ... :&gt; f xn :&gt; Nil)
--   </pre>
--   
--   and corresponds to the following circuit layout:
--   
map :: (a -> b) -> Vec n a -> Vec n b

-- | Convert a <a>BitVector</a> to a <a>Vec</a> of <a>Bit</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 6 :: BitVector 8
--   
--   &gt;&gt;&gt; x
--   0b0000_0110
--   
--   &gt;&gt;&gt; bv2v x
--   0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 1 :&gt; 0 :&gt; Nil
--   </pre>
bv2v :: KnownNat n => BitVector n -> Vec n Bit

-- | To be used as the motive <i>p</i> for <a>dfold</a>, when the <i>f</i>
--   in "<a>dfold</a> <tt>p f</tt>" is a variation on (<a>:&gt;</a>), e.g.:
--   
--   <pre>
--   map' :: forall n a b . KnownNat n =&gt; (a -&gt; b) -&gt; Vec n a -&gt; Vec n b
--   map' f = <a>dfold</a> (Proxy @(<a>VCons</a> b)) (_ x xs -&gt; f x :&gt; xs)
--   </pre>
data VCons (a :: Type) (f :: TyFun Nat Type) :: Type
traverse# :: forall a f b n. Applicative f => (a -> f b) -> Vec n a -> f (Vec n b)

-- | Create a vector of one element
--   
--   <pre>
--   &gt;&gt;&gt; singleton 5
--   5 :&gt; Nil
--   </pre>
singleton :: a -> Vec 1 a

-- | Extract the first element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; head (1:&gt;2:&gt;3:&gt;Nil)
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; head Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘head’, namely ‘Nil’
--         In the expression: head Nil
--         In an equation for ‘it’: it = head Nil
--   </pre>
head :: Vec (n + 1) a -> a

-- | Extract the elements after the head of a vector
--   
--   <pre>
--   &gt;&gt;&gt; tail (1:&gt;2:&gt;3:&gt;Nil)
--   2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; tail Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘tail’, namely ‘Nil’
--         In the expression: tail Nil
--         In an equation for ‘it’: it = tail Nil
--   </pre>
tail :: Vec (n + 1) a -> Vec n a

-- | Extract the last element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; last (1:&gt;2:&gt;3:&gt;Nil)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; last Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘last’, namely ‘Nil’
--         In the expression: last Nil
--         In an equation for ‘it’: it = last Nil
--   </pre>
last :: Vec (n + 1) a -> a

-- | Extract all the elements of a vector except the last element
--   
--   <pre>
--   &gt;&gt;&gt; init (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; init Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘init’, namely ‘Nil’
--         In the expression: init Nil
--         In an equation for ‘it’: it = init Nil
--   </pre>
init :: Vec (n + 1) a -> Vec n a

-- | Shift in elements to the head of a vector, bumping out elements at the
--   tail. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; Nil,3 :&gt; 4 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; Nil,0 :&gt; 1 :&gt; Nil)
--   </pre>
shiftInAt0 :: KnownNat n => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift in element to the tail of a vector, bumping out elements at the
--   head. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; Nil)
--   (3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; Nil) (2 :&gt; 3 :&gt; Nil)
--   (3 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftInAtN :: KnownNat m => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Add an element to the head of a vector, and extract all but the last
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; 1 +&gt;&gt; Nil
--   Nil
--   </pre>
(+>>) :: KnownNat n => a -> Vec n a -> Vec n a
infixr 4 +>>

-- | Add an element to the tail of a vector, and extract all but the first
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) &lt;&lt;+ 1
--   4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; Nil &lt;&lt;+ 1
--   Nil
--   </pre>
(<<+) :: Vec n a -> a -> Vec n a
infixl 4 <<+

-- | Shift <i>m</i> elements out from the head of a vector, filling up the
--   tail with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFrom0 d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (3 :&gt; 4 :&gt; 5 :&gt; 0 :&gt; 0 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftOutFrom0 :: (Default a, KnownNat m) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Shift <i>m</i> elements out from the tail of a vector, filling up the
--   head with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFromN d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (0 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil,4 :&gt; 5 :&gt; Nil)
--   </pre>
shiftOutFromN :: (Default a, KnownNat n) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Append two vectors.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;Nil) ++ (7:&gt;8:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 8 :&gt; Nil
--   </pre>
(++) :: Vec n a -> Vec m a -> Vec (n + m) a
infixr 5 ++

-- | Split a vector into two vectors at the given point.
--   
--   <pre>
--   &gt;&gt;&gt; splitAt (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   
--   &gt;&gt;&gt; splitAt d3 (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAt :: SNat m -> Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector into two vectors where the length of the two is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; splitAtI (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil) :: (Vec 2 Int, Vec 3 Int)
--   (1 :&gt; 2 :&gt; Nil,3 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAtI :: KnownNat m => Vec (m + n) a -> (Vec m a, Vec n a)

-- | Concatenate a vector of vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concat ((1:&gt;2:&gt;3:&gt;Nil) :&gt; (4:&gt;5:&gt;6:&gt;Nil) :&gt; (7:&gt;8:&gt;9:&gt;Nil) :&gt; (10:&gt;11:&gt;12:&gt;Nil) :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil
--   </pre>
concat :: Vec n (Vec m a) -> Vec (n * m) a

-- | Map a function over all the elements of a vector and concatentate the
--   resulting vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concatMap (replicate d3) (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 1 :&gt; 1 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; 3 :&gt; 3 :&gt; 3 :&gt; Nil
--   </pre>
concatMap :: (a -> Vec m b) -> Vec n a -> Vec (n * m) b

-- | Split a vector of (n * m) elements into a vector of "vectors of length
--   <i>m</i>", where the length <i>m</i> is given.
--   
--   <pre>
--   &gt;&gt;&gt; unconcat d4 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcat :: KnownNat n => SNat m -> Vec (n * m) a -> Vec n (Vec m a)

-- | Split a vector of <i>(n * m)</i> elements into a vector of "vectors of
--   length <i>m</i>", where the length <i>m</i> is determined by the
--   context.
--   
--   <pre>
--   &gt;&gt;&gt; unconcatI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil) :: Vec 2 (Vec 6 Int)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcatI :: (KnownNat n, KnownNat m) => Vec (n * m) a -> Vec n (Vec m a)

-- | Merge two vectors, alternating their elements, i.e.,
--   
--   <pre>
--   &gt;&gt;&gt; merge (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   1 :&gt; 5 :&gt; 2 :&gt; 6 :&gt; 3 :&gt; 7 :&gt; 4 :&gt; 8 :&gt; Nil
--   </pre>
merge :: KnownNat n => Vec n a -> Vec n a -> Vec (2 * n) a

-- | The elements in a vector in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; reverse (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
reverse :: Vec n a -> Vec n a

-- | Apply a function of every element of a vector and its index.
--   
--   <pre>
--   &gt;&gt;&gt; :t imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Index 4)
--   
--   &gt;&gt;&gt; imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   2 :&gt; 3 :&gt; *** Exception: X: Clash.Sized.Index: result 4 is out of bounds: [0..3]
--   ...
--   
--   &gt;&gt;&gt; imap (\i a -&gt; extend (bitCoerce i) + a) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Unsigned 8)
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
imap :: forall n a b. KnownNat n => (Index n -> a -> b) -> Vec n a -> Vec n b

-- | Zip two vectors with a functions that also takes the elements'
--   indices.
--   
--   <pre>
--   &gt;&gt;&gt; izipWith (\i a b -&gt; i + a + b) (2 :&gt; 2 :&gt; Nil)  (3 :&gt; 3:&gt; Nil)
--   *** Exception: X: Clash.Sized.Index: result 3 is out of bounds: [0..1]
--   ...
--   
--   &gt;&gt;&gt; izipWith (\i a b -&gt; extend (bitCoerce i) + a + b) (2 :&gt; 2 :&gt; Nil) (3 :&gt; 3 :&gt; Nil) :: Vec 2 (Unsigned 8)
--   5 :&gt; 6 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>izipWith</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third. This matters when <a>izipWith</a> is
--   used in a recursive setting. See <a>lazyV</a> for more information.
izipWith :: KnownNat n => (Index n -> a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | Right fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findLeftmost x xs = ifoldr (\i a b -&gt; if a == x then Just i else b) Nothing xs
--   
--   &gt;&gt;&gt; findLeftmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; findLeftmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldr :: KnownNat n => (Index n -> a -> b -> b) -> b -> Vec n a -> b

-- | Left fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findRightmost x xs = ifoldl (\a i b -&gt; if b == x then Just i else a) Nothing xs
--   
--   &gt;&gt;&gt; findRightmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 4
--   
--   &gt;&gt;&gt; findRightmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldl :: KnownNat n => (a -> Index n -> b -> a) -> a -> Vec n b -> a

-- | Generate a vector of indices.
--   
--   <pre>
--   &gt;&gt;&gt; indices d4
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indices :: KnownNat n => SNat n -> Vec n (Index n)

-- | Generate a vector of indices, where the length of the vector is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; indicesI :: Vec 4 (Index 4)
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indicesI :: KnownNat n => Vec n (Index n)

-- | "<a>findIndex</a> <tt>p xs</tt>" returns the index of the <i>first</i>
--   element of <i>xs</i> satisfying the predicate <i>p</i>, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 3) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 3
--   
--   &gt;&gt;&gt; findIndex (&gt; 8) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
findIndex :: KnownNat n => (a -> Bool) -> Vec n a -> Maybe (Index n)

-- | "<a>elemIndex</a> <tt>a xs</tt>" returns the index of the <i>first</i>
--   element which is equal (by <a>==</a>) to the query element <i>a</i>,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndex 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; elemIndex 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
elemIndex :: (KnownNat n, Eq a) => a -> Vec n a -> Maybe (Index n)

-- | <a>zipWith</a> generalizes <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "<a>zipWith</a> <tt>(+)</tt>" applied to two vectors produces
--   the vector of corresponding sums.
--   
--   <pre>
--   zipWith f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) == (f x1 y1 :&gt; f x2 y2 :&gt; ... :&gt; f xn yn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith</a> <tt>f xs ys</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>zipWith</a> is <i>strict</i> in its second argument, and
--   <i>lazy</i> in its third. This matters when <a>zipWith</a> is used in
--   a recursive setting. See <a>lazyV</a> for more information.
zipWith :: (a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>zipWith3</a> generalizes <a>zip3</a> by zipping with the function
--   given as the first argument, instead of a tupling function.
--   
--   <pre>
--   zipWith3 f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) (z1 :&gt; z2 :&gt; ... :&gt; zn :&gt; Nil) == (f x1 y1 z1 :&gt; f x2 y2 z2 :&gt; ... :&gt; f xn yn zn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith3</a> <tt>f xs ys zs</tt>" corresponds to the following
--   circuit layout:
--   
--   
--   <b>NB</b>: <a>zipWith3</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third and fourth. This matters when
--   <a>zipWith3</a> is used in a recursive setting. See <a>lazyV</a> for
--   more information.
zipWith3 :: (a -> b -> c -> d) -> Vec n a -> Vec n b -> Vec n c -> Vec n d
zipWith4 :: (a -> b -> c -> d -> e) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e
zipWith5 :: (a -> b -> c -> d -> e -> f) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f
zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g
zipWith7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n h

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldr1 f (x1 :&gt; ... :&gt; xn2 :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn2 `f` (xn1 `f` xn))...)
--   foldr1 f (x1 :&gt; Nil)                            == x1
--   foldr1 f Nil                                    == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (/) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldr1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldl1 f (x1 :&gt; x2 :&gt; x3 :&gt; ... :&gt; xn :&gt; Nil) == (...((x1 `f` x2) `f` x3) `f`...) `f` xn
--   foldl1 f (x1 :&gt; Nil)                          == x1
--   foldl1 f Nil                                  == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (/) (1 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldl1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>fold</a> is a variant of <a>foldr1</a> and <a>foldl1</a>, but
--   instead of reducing from right to left, or left to right, it reduces a
--   vector using a tree-like structure. The depth, or delay, of the
--   structure produced by "<tt><a>fold</a> f xs</tt>", is hence
--   <tt>O(log_2(<a>length</a> xs))</tt>, and not <tt>O(<a>length</a>
--   xs)</tt>.
--   
--   <b>NB</b>: The binary operator "<tt>f</tt>" in "<tt><a>fold</a> f
--   xs</tt>" must be associative.
--   
--   <pre>
--   fold f (x1 :&gt; x2 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == ((x1 `f` x2) `f` ...) `f` (... `f` (xn1 `f` xn))
--   fold f (x1 :&gt; Nil)                           == x1
--   fold f Nil                                   == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fold (+) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   15
--   </pre>
--   
--   "<a>fold</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
fold :: forall n a. (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a vector of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == z :&gt; (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   0 :&gt; 5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>scanl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>last (scanl f z xs) == foldl f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanl :: (b -> a -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>scanl</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanl1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   1 :&gt; -1 :&gt; -4 :&gt; -8 :&gt; Nil
--   </pre>
scanl1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>scanr</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanr1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   -2 :&gt; 3 :&gt; -1 :&gt; 4 :&gt; Nil
--   </pre>
scanr1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>postscanl</a> is a variant of <a>scanl</a> where the first result
--   is dropped:
--   
--   <pre>
--   postscanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>postscanl</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanl :: (b -> a -> b) -> b -> Vec n a -> Vec n b

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a vector of
--   successive reduced values from the right:
--   
--   <pre>
--   scanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; z :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; 0 :&gt; Nil
--   </pre>
--   
--   "<a>scanr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>head (scanr f z xs) == foldr f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanr :: (a -> b -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>postscanr</a> is a variant of <a>scanr</a> that where the last
--   result is dropped:
--   
--   <pre>
--   postscanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   "<a>postscanr</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanr :: (a -> b -> b) -> b -> Vec n a -> Vec n b

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumL (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,1 :&gt; 2 :&gt; 4 :&gt; 7 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumL</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumL :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumR (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,10 :&gt; 8 :&gt; 5 :&gt; 1 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumR</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumR :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | <a>zip</a> takes two vectors and returns a vector of corresponding
--   pairs.
--   
--   <pre>
--   &gt;&gt;&gt; zip (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil)
--   (1,4) :&gt; (2,3) :&gt; (3,2) :&gt; (4,1) :&gt; Nil
--   </pre>
zip :: Vec n a -> Vec n b -> Vec n (a, b)

-- | <a>zip3</a> takes three vectors and returns a vector of corresponding
--   triplets.
--   
--   <pre>
--   &gt;&gt;&gt; zip3 (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil) (5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   (1,4,5) :&gt; (2,3,6) :&gt; (3,2,7) :&gt; (4,1,8) :&gt; Nil
--   </pre>
zip3 :: Vec n a -> Vec n b -> Vec n c -> Vec n (a, b, c)

-- | <a>zip4</a> takes four vectors and returns a list of quadruples,
--   analogous to <a>zip</a>.
zip4 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n (a, b, c, d)

-- | <a>zip5</a> takes five vectors and returns a list of five-tuples,
--   analogous to <a>zip</a>.
zip5 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n (a, b, c, d, e)

-- | <a>zip6</a> takes six vectors and returns a list of six-tuples,
--   analogous to <a>zip</a>.
zip6 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n (a, b, c, d, e, f)

-- | <a>zip7</a> takes seven vectors and returns a list of seven-tuples,
--   analogous to <a>zip</a>.
zip7 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n (a, b, c, d, e, f, g)

-- | <a>unzip</a> transforms a vector of pairs into a vector of first
--   components and a vector of second components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip ((1,4):&gt;(2,3):&gt;(3,2):&gt;(4,1):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   </pre>
unzip :: Vec n (a, b) -> (Vec n a, Vec n b)

-- | <a>unzip3</a> transforms a vector of triplets into a vector of first
--   components, a vector of second components, and a vector of third
--   components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip3 ((1,4,5):&gt;(2,3,6):&gt;(3,2,7):&gt;(4,1,8):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil,5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
unzip3 :: Vec n (a, b, c) -> (Vec n a, Vec n b, Vec n c)

-- | <a>unzip4</a> takes a vector of quadruples and returns four vectors,
--   analogous to <a>unzip</a>.
unzip4 :: Vec n (a, b, c, d) -> (Vec n a, Vec n b, Vec n c, Vec n d)

-- | <a>unzip5</a> takes a vector of five-tuples and returns five vectors,
--   analogous to <a>unzip</a>.
unzip5 :: Vec n (a, b, c, d, e) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e)

-- | <a>unzip6</a> takes a vector of six-tuples and returns six vectors,
--   analogous to <a>unzip</a>.
unzip6 :: Vec n (a, b, c, d, e, f) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f)

-- | <a>unzip7</a> takes a vector of seven-tuples and returns seven
--   vectors, analogous to <a>unzip</a>.
unzip7 :: Vec n (a, b, c, d, e, f, g) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f, Vec n g)

-- | "<tt>xs</tt> <a>!!</a> <tt>n</tt>" returns the <i>n</i>'th element of
--   <i>xs</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 4
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! (length (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) - 1)
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 1
--   2
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 4
--   ...
--   </pre>
(!!) :: (KnownNat n, Enum i) => Vec n a -> i -> a

-- | The length of a <a>Vec</a>tor as an <a>Int</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; length (6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   3
--   </pre>
length :: KnownNat n => Vec n a -> Int

-- | "<a>replace</a> <tt>n a xs</tt>" returns the vector <i>xs</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; replace 3 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 0 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   7 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 9 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; *** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 4
--   ...
--   </pre>
replace :: (KnownNat n, Enum i) => i -> a -> Vec n a -> Vec n a

-- | "<a>take</a> <tt>n xs</tt>" returns the <i>n</i>-length prefix of
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; take (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d0               (1:&gt;2:&gt;Nil)
--   Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘4 + n0’ with ‘2’
--         Expected type: Vec (4 + n0) a
--           Actual type: Vec (1 + 1) a
--         The type variable ‘n0’ is ambiguous
--       • In the second argument of ‘take’, namely ‘(1 :&gt; 2 :&gt; Nil)’
--         In the expression: take d4 (1 :&gt; 2 :&gt; Nil)
--         In an equation for ‘it’: it = take d4 (1 :&gt; 2 :&gt; Nil)
--   </pre>
take :: SNat m -> Vec (m + n) a -> Vec m a

-- | "<a>takeI</a> <tt>xs</tt>" returns the prefix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; takeI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   1 :&gt; 2 :&gt; Nil
--   </pre>
takeI :: KnownNat m => Vec (m + n) a -> Vec m a

-- | "<a>drop</a> <tt>n xs</tt>" returns the suffix of <i>xs</i> after the
--   first <i>n</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; drop (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d0               (1:&gt;2:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; drop d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...: error:...
--       • Couldn't match...type ‘4 + n0...
--         The type variable ‘n0’ is ambiguous
--       • In the first argument of ‘print’, namely ‘it’
--         In a stmt of an interactive GHCi command: print it
--   </pre>
drop :: SNat m -> Vec (m + n) a -> Vec n a

-- | "<a>dropI</a> <tt>xs</tt>" returns the suffix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; dropI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   4 :&gt; 5 :&gt; Nil
--   </pre>
dropI :: KnownNat m => Vec (m + n) a -> Vec n a

-- | "<a>at</a> <tt>n xs</tt>" returns <i>n</i>'th element of <i>xs</i>
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; at (SNat :: SNat 1) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   
--   &gt;&gt;&gt; at d1               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   </pre>
at :: SNat m -> Vec (m + (n + 1)) a -> a

-- | "<a>select</a> <tt>f s n xs</tt>" selects <i>n</i> elements with
--   step-size <i>s</i> and offset <tt>f</tt> from <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; select (SNat :: SNat 1) (SNat :: SNat 2) (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; select d1 d2 d3 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   </pre>
select :: CmpNat (i + s) (s * n) ~ 'GT => SNat f -> SNat s -> SNat n -> Vec (f + i) a -> Vec n a

-- | "<a>selectI</a> <tt>f s xs</tt>" selects as many elements as demanded
--   by the context with step-size <i>s</i> and offset <i>f</i> from
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; selectI d1 d2 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil) :: Vec 2 Int
--   2 :&gt; 4 :&gt; Nil
--   </pre>
selectI :: (CmpNat (i + s) (s * n) ~ 'GT, KnownNat n) => SNat f -> SNat s -> Vec (f + i) a -> Vec n a

-- | "<a>replicate</a> <tt>n a</tt>" returns a vector that has <i>n</i>
--   copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; replicate (SNat :: SNat 3) 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; replicate d3 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
replicate :: SNat n -> a -> Vec n a

-- | "<a>repeat</a> <tt>a</tt>" creates a vector with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; repeat 6 :: Vec 5 Int
--   6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
repeat :: KnownNat n => a -> Vec n a

-- | "<a>iterate</a> <tt>n f x</tt>" returns a vector starting with
--   <i>x</i> followed by <i>n</i> repeated applications of <i>f</i> to
--   <i>x</i>.
--   
--   <pre>
--   iterate (SNat :: SNat 4) f x == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   iterate d4 f x               == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterate d4 (+1) 1
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>iterate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
iterate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>iterateI</a> <tt>f x</tt>" returns a vector starting with
--   <tt>x</tt> followed by <tt>n</tt> repeated applications of <tt>f</tt>
--   to <tt>x</tt>, where <tt>n</tt> is determined by the context.
--   
--   <pre>
--   iterateI f x :: Vec 3 a == (x :&gt; f x :&gt; f (f x) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterateI (+1) 1 :: Vec 3 Int
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   "<a>iterateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
iterateI :: forall n a. KnownNat n => (a -> a) -> a -> Vec n a

-- | "<a>unfoldr</a> <tt>n f s</tt>" builds a vector of length <tt>n</tt>
--   from a seed value <tt>s</tt>, where every element <tt>a</tt> is
--   created by successive calls of <tt>f</tt> on <tt>s</tt>. Unlike
--   <a>unfoldr</a> from <a>Data.List</a> the generating function
--   <tt>f</tt> cannot dictate the length of the resulting vector, it must
--   be statically known.
--   
--   a simple use of <a>unfoldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr d10 (\s -&gt; (s,s-1)) 10
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldr :: SNat n -> (s -> (a, s)) -> s -> Vec n a

-- | "<a>unfoldrI</a> <tt>f s</tt>" builds a vector from a seed value
--   <tt>s</tt>, where every element <tt>a</tt> is created by successive
--   calls of <tt>f</tt> on <tt>s</tt>; the length of the vector is
--   inferred from the context. Unlike <a>unfoldr</a> from <a>Data.List</a>
--   the generating function <tt>f</tt> cannot dictate the length of the
--   resulting vector, it must be statically known.
--   
--   a simple use of <a>unfoldrI</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldrI (\s -&gt; (s,s-1)) 10 :: Vec 10 Int
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldrI :: KnownNat n => (s -> (a, s)) -> s -> Vec n a

-- | "<a>generate</a> <tt>n f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>.
--   
--   <pre>
--   generate (SNat :: SNat 4) f x == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   generate d4 f x               == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generate d4 (+1) 1
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>generate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
generate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>generateI</a> <tt>f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>, where <tt>n</tt> is
--   determined by the context.
--   
--   <pre>
--   generateI f x :: Vec 3 a == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generateI (+1) 1 :: Vec 3 Int
--   2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>generateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
generateI :: KnownNat n => (a -> a) -> a -> Vec n a

-- | Transpose a matrix: go from row-major to column-major
--   
--   <pre>
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;Nil):&gt;(3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; transpose xss
--   (1 :&gt; 3 :&gt; 5 :&gt; Nil) :&gt; (2 :&gt; 4 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
transpose :: KnownNat n => Vec m (Vec n a) -> Vec n (Vec m a)

-- | 1-dimensional stencil computations
--   
--   "<a>stencil1d</a> <tt>stX f xs</tt>", where <i>xs</i> has <i>stX +
--   n</i> elements, applies the stencil computation <i>f</i> on: <i>n +
--   1</i> overlapping (1D) windows of length <i>stX</i>, drawn from
--   <i>xs</i>. The resulting vector has <i>n + 1</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t stencil1d d2 sum xs
--   stencil1d d2 sum xs :: Num b =&gt; Vec 5 b
--   
--   &gt;&gt;&gt; stencil1d d2 sum xs
--   3 :&gt; 5 :&gt; 7 :&gt; 9 :&gt; 11 :&gt; Nil
--   </pre>
stencil1d :: KnownNat n => SNat (stX + 1) -> (Vec (stX + 1) a -> b) -> Vec ((stX + n) + 1) a -> Vec (n + 1) b

-- | 2-dimensional stencil computations
--   
--   "<a>stencil2d</a> <tt>stY stX f xss</tt>", where <i>xss</i> is a
--   matrix of <i>stY + m</i> rows of <i>stX + n</i> elements, applies the
--   stencil computation <i>f</i> on: <i>(m + 1) * (n + 1)</i> overlapping
--   (2D) windows of <i>stY</i> rows of <i>stX</i> elements, drawn from
--   <i>xss</i>. The result matrix has <i>m + 1</i> rows of <i>n + 1</i>
--   elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t stencil2d d2 d2 (sum . map sum) xss
--   stencil2d d2 d2 (sum . map sum) xss :: Num b =&gt; Vec 3 (Vec 3 b)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stencil2d d2 d2 (sum . map sum) xss
--   (14 :&gt; 18 :&gt; 22 :&gt; Nil) :&gt; (30 :&gt; 34 :&gt; 38 :&gt; Nil) :&gt; (46 :&gt; 50 :&gt; 54 :&gt; Nil) :&gt; Nil
--   </pre>
stencil2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> (Vec (stY + 1) (Vec (stX + 1) a) -> b) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) b)

-- | "<a>windows1d</a> <tt>stX xs</tt>", where the vector <i>xs</i> has
--   <i>stX + n</i> elements, returns a vector of <i>n + 1</i> overlapping
--   (1D) windows of <i>xs</i> of length <i>stX</i>.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t windows1d d2 xs
--   windows1d d2 xs :: Num a =&gt; Vec 5 (Vec 2 a)
--   
--   &gt;&gt;&gt; windows1d d2 xs
--   (1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
windows1d :: KnownNat n => SNat (stX + 1) -> Vec ((stX + n) + 1) a -> Vec (n + 1) (Vec (stX + 1) a)

-- | "<a>windows2d</a> <tt>stY stX xss</tt>", where matrix <i>xss</i> has
--   <i>stY + m</i> rows of <i>stX + n</i>, returns a matrix of <i>m+1</i>
--   rows of <i>n+1</i> elements. The elements of this new matrix are the
--   overlapping (2D) windows of <i>xss</i>, where every window has
--   <i>stY</i> rows of <i>stX</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   
--   &gt;&gt;&gt; :t windows2d d2 d2 xss
--   windows2d d2 d2 xss :: Num a =&gt; Vec 3 (Vec 3 (Vec 2 (Vec 2 a)))
--   
--   &gt;&gt;&gt; windows2d d2 d2 xss
--   (((1 :&gt; 2 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil) :&gt; ((2 :&gt; 3 :&gt; Nil) :&gt; (6 :&gt; 7 :&gt; Nil) :&gt; Nil) :&gt; ((3 :&gt; 4 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((5 :&gt; 6 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; Nil) :&gt; Nil) :&gt; ((6 :&gt; 7 :&gt; Nil) :&gt; (10 :&gt; 11 :&gt; Nil) :&gt; Nil) :&gt; ((7 :&gt; 8 :&gt; Nil) :&gt; (11 :&gt; 12 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((9 :&gt; 10 :&gt; Nil) :&gt; (13 :&gt; 14 :&gt; Nil) :&gt; Nil) :&gt; ((10 :&gt; 11 :&gt; Nil) :&gt; (14 :&gt; 15 :&gt; Nil) :&gt; Nil) :&gt; ((11 :&gt; 12 :&gt; Nil) :&gt; (15 :&gt; 16 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; Nil
--   </pre>
windows2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) (Vec (stY + 1) (Vec (stX + 1) a)))

-- | Forward permutation specified by an index mapping, <i>ix</i>. The
--   result vector is initialized by the given defaults, <i>def</i>, and an
--   further values that are permuted into the result are added to the
--   current value using the given combination function, <i>f</i>.
--   
--   The combination function must be <i>associative</i> and
--   <i>commutative</i>.
permute :: (Enum i, KnownNat n, KnownNat m) => (a -> a -> a) -> Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>backpermute</a> <tt>xs is</tt>" is equivalent to "<a>map</a>
--   <tt>(xs <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; backpermute input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
backpermute :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | Copy elements from the source vector, <i>xs</i>, to the destination
--   vector according to an index mapping <i>is</i>. This is a forward
--   permute operation where a <i>to</i> vector encodes an input to output
--   index mapping. Output elements for indices that are not mapped assume
--   the value in the default vector <i>def</i>.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let defVec = 0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;Nil
--   
--   &gt;&gt;&gt; let to = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;8:&gt;Nil
--   
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; scatter defVec to input
--   0 :&gt; 1 :&gt; 4 :&gt; 9 :&gt; 0 :&gt; 4 :&gt; 0 :&gt; 6 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: If the same index appears in the index mapping more than
--   once, the latest mapping is chosen.
scatter :: (Enum i, KnownNat n, KnownNat m) => Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>gather</a> <tt>xs is</tt>" is equivalent to "<a>map</a> <tt>(xs
--   <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; gather input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
gather :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | "<a>interleave</a> <tt>d xs</tt>" creates a vector:
--   
--   <pre>
--   &lt;x_0,x_d,x_(2d),...,x_1,x_(d+1),x_(2d+1),...,x_(d-1),x_(2d-1),x_(3d-1)&gt;
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; Nil
--   
--   &gt;&gt;&gt; interleave d3 xs
--   1 :&gt; 4 :&gt; 7 :&gt; 2 :&gt; 5 :&gt; 8 :&gt; 3 :&gt; 6 :&gt; 9 :&gt; Nil
--   </pre>
interleave :: (KnownNat n, KnownNat d) => SNat d -> Vec (n * d) a -> Vec (d * n) a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs (-1)
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeftS</a> if you want to rotate left by a
--   <i>static</i> amount.
rotateLeft :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs (-1)
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRightS</a> if you want to rotate right by a
--   <i>static</i> amount.
rotateRight :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeftS xs d1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeft</a> if you want to rotate left by a
--   <i>dynamic</i> amount.
rotateLeftS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRightS xs d1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRight</a> if you want to rotate right by a
--   <i>dynamic</i> amount.
rotateRightS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | Convert a vector to a list.
--   
--   <pre>
--   &gt;&gt;&gt; toList (1:&gt;2:&gt;3:&gt;Nil)
--   [1,2,3]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
toList :: Vec n a -> [a]

-- | Create a vector literal from a list literal.
--   
--   <pre>
--   $(listToVecTH [1::Signed 8,2,3,4,5]) == (8:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 5 (Signed 8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1 :: Signed 8,2,3,4,5]
--   [1,2,3,4,5]
--   
--   &gt;&gt;&gt; $(listToVecTH [1::Signed 8,2,3,4,5])
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
listToVecTH :: Lift a => [a] -> ExpQ

-- | <a>Vec</a>tor as a <a>Proxy</a> for <a>Nat</a>
asNatProxy :: Vec n a -> Proxy n

-- | Length of a <a>Vec</a>tor as an <a>SNat</a> value
lengthS :: KnownNat n => Vec n a -> SNat n

-- | What you should use when your vector functions are too strict in their
--   arguments.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwapL a b = if a &lt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; :{
--   let sortVL :: (Ord a, KnownNat (n + 1)) =&gt; Vec ((n + 1) + 1) a -&gt; Vec ((n + 1) + 1) a
--       sortVL xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith compareSwapL (lazyV lefts) rights
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let sortV_flip xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith (flip compareSwapL) rights lefts
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   For example:
--   
--   <pre>
--   -- Bubble sort for 1 iteration
--   sortV xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL lefts rights
--   
--   -- Compare and swap
--   compareSwapL a b = if a &lt; b then (a,b)
--                               else (b,a)
--   </pre>
--   
--   Will not terminate because <a>zipWith</a> is too strict in its second
--   argument.
--   
--   In this case, adding <a>lazyV</a> on <a>zipWith</a>s second argument:
--   
--   <pre>
--   sortVL xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; map snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL (<a>lazyV</a> lefts) rights
--   </pre>
--   
--   Results in a successful computation:
--   
--   <pre>
--   &gt;&gt;&gt; sortVL (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: There is also a solution using <a>flip</a>, but it slightly
--   obfuscates the meaning of the code:
--   
--   <pre>
--   sortV_flip xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> (<a>flip</a> compareSwapL) rights lefts
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sortV_flip (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
lazyV :: KnownNat n => Vec n a -> Vec n a

-- | A <i>dependently</i> typed fold.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -fplugin GHC.TypeLits.Normalise
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data Append (m :: Nat) (a :: Type) (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply (Append m a) l = Vec (l + m) a
--   
--   &gt;&gt;&gt; let append' xs ys = dfold (Proxy :: Proxy (Append m a)) (const (:&gt;)) ys xs
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   Using lists, we can define <i>append</i> (a.k.a.
--   <tt>Data.List.</tt><a>++</a>) in terms of
--   <tt>Data.List.</tt><a>foldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List
--   
--   &gt;&gt;&gt; let append xs ys = Data.List.foldr (:) ys xs
--   
--   &gt;&gt;&gt; append [1,2] [3,4]
--   [1,2,3,4]
--   </pre>
--   
--   However, when we try to do the same for <a>Vec</a>, by defining
--   <i>append'</i> in terms of <tt>Clash.Sized.Vector.</tt><a>foldr</a>:
--   
--   <pre>
--   append' xs ys = <a>foldr</a> (:&gt;) ys xs
--   </pre>
--   
--   we get a type error:
--   
--   <pre>
--   <b>&gt;&gt;&gt; let append' xs ys = foldr (:&gt;) ys xs</b>
--   
--   &lt;interactive&gt;:...
--       • Occurs check: cannot construct the infinite type: ... ~ ... + 1
--         Expected type: a -&gt; Vec ... a -&gt; Vec ... a
--           Actual type: a -&gt; Vec ... a -&gt; Vec (... + 1) a
--       • In the first argument of ‘foldr’, namely ‘(:&gt;)’
--         In the expression: foldr (:&gt;) ys xs
--         In an equation for ‘append'’: append' xs ys = foldr (:&gt;) ys xs
--       • Relevant bindings include
--           ys :: Vec ... a (bound at ...)
--           append' :: Vec n a -&gt; Vec ... a -&gt; Vec ... a
--             (bound at ...)
--   </pre>
--   
--   The reason is that the type of <a>foldr</a> is:
--   
--   <pre>
--   &gt;&gt;&gt; :t foldr
--   foldr :: (a -&gt; b -&gt; b) -&gt; b -&gt; Vec n a -&gt; b
--   </pre>
--   
--   While the type of (<a>:&gt;</a>) is:
--   
--   <pre>
--   &gt;&gt;&gt; :t (:&gt;)
--   (:&gt;) :: a -&gt; Vec n a -&gt; Vec (n + 1) a
--   </pre>
--   
--   We thus need a <tt>fold</tt> function that can handle the growing
--   vector type: <a>dfold</a>. Compared to <a>foldr</a>, <a>dfold</a>
--   takes an extra parameter, called the <i>motive</i>, that allows the
--   folded function to have an argument and result type that
--   <i>depends</i> on the current length of the vector. Using
--   <a>dfold</a>, we can now correctly define <i>append'</i>:
--   
--   <pre>
--   import Data.Singletons
--   import Data.Proxy
--   
--   data Append (m :: Nat) (a :: Type) (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> (Append m a) l = <a>Vec</a> (l + m) a
--   
--   append' xs ys = <a>dfold</a> (Proxy :: Proxy (Append m a)) (const (<a>:&gt;</a>)) ys xs
--   </pre>
--   
--   We now see that <i>append'</i> has the appropriate type:
--   
--   <pre>
--   &gt;&gt;&gt; :t append'
--   append' :: KnownNat k =&gt; Vec k a -&gt; Vec m a -&gt; Vec (k + m) a
--   </pre>
--   
--   And that it works:
--   
--   <pre>
--   &gt;&gt;&gt; append' (1 :&gt; 2 :&gt; Nil) (3 :&gt; 4 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: "<tt><a>dfold</a> m f z xs</tt>" creates a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Look at <a>dtfold</a> for a <i>dependently</i> typed fold
--   that produces a structure with a depth of O(log_2(<tt><a>length</a>
--   xs</tt>)).
dfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (forall l. SNat l -> a -> (p @@ l) -> p @@ (l + 1)) -> (p @@ 0) -> Vec k a -> p @@ k

-- | A combination of <a>dfold</a> and <a>fold</a>: a <i>dependently</i>
--   typed fold that reduces a vector in a tree-like structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XUndecidableInstances
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data IIndex (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply IIndex l = Index ((2^l)+1)
--   
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat k, KnownNat (2^k)) =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--       populationCount' bv = dtfold (Proxy @IIndex)
--                                    fromIntegral
--                                    (\_ x y -&gt; add x y)
--                                    (bv2v bv)
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <a>BitVector</a>. Given a vector of <i>n</i> bits, we
--   only need we need a data type that can represent the number <i>n</i>:
--   <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a range of
--   <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits), hence we need
--   <a>Index</a> <tt>n+1</tt>. As an initial attempt we will use
--   <a>sum</a>, because it gives a nice (<tt>log2(n)</tt>) tree-structure
--   of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (n+1), KnownNat (n+2))
--                   =&gt; <a>BitVector</a> (n+1) -&gt; <a>Index</a> (n+2)
--   populationCount = sum . map fromIntegral . <a>bv2v</a>
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>add</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <a>fold</a> to create a tree-structure
--   of <a>add</a>es:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (n+1), KnownNat (n+2))
--                        =&gt; BitVector (n+1) -&gt; Index (n+2)
--       populationCount' = fold add . map fromIntegral . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘((n + 2) + (n + 2)) - 1’ with ‘n + 2’
--         Expected type: Index (n + 2) -&gt; Index (n + 2) -&gt; Index (n + 2)
--           Actual type: Index (n + 2)
--                        -&gt; Index (n + 2) -&gt; AResult (Index (n + 2)) (Index (n + 2))
--       • In the first argument of ‘fold’, namely ‘add’
--         In the first argument of ‘(.)’, namely ‘fold add’
--         In the expression: fold add . map fromIntegral . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (n + 1) -&gt; Index (n + 2)
--             (bound at ...)
--   </pre>
--   
--   because <a>fold</a> expects a function of type "<tt>a -&gt; a -&gt;
--   a</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>add</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons
--   import Data.Proxy
--   
--   data IIndex (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>dtfold</a> (Proxy @IIndex)
--                                fromIntegral
--                                (\_ x y -&gt; <a>add</a> x y)
--                                (<a>bv2v</a> bv)
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
--   
--   Some final remarks:
--   
--   <ul>
--   <li>By using <a>dtfold</a> instead of <a>fold</a>, we had to restrict
--   our <a>BitVector</a> argument to have bit-width that is a power of
--   2.</li>
--   <li>Even though our original <i>populationCount</i> function specified
--   a structure where all adders had the same width. Most
--   VHDL/(System)Verilog synthesis tools will create a more efficient
--   circuit, i.e. one where the adders have an increasing bit-width for
--   every layer, from the VHDL/(System)Verilog produced by the Clash
--   compiler.</li>
--   </ul>
--   
--   <b>NB</b>: The depth, or delay, of the structure produced by
--   "<tt><a>dtfold</a> m f g xs</tt>" is O(log_2(<tt><a>length</a>
--   xs</tt>)).
dtfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (a -> p @@ 0) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> p @@ (l + 1)) -> Vec (2 ^ k) a -> p @@ k

-- | Specialised version of <a>dfold</a> that builds a triangular
--   computational structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; let insert y xs = let (y',xs') = mapAccumL compareSwap y xs in xs' :&lt; y'
--   
--   &gt;&gt;&gt; let insertionSort = vfold (const insert)
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   <pre>
--   compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   insert y xs     = let (y',xs') = <a>mapAccumL</a> compareSwap y xs in xs' <a>:&lt;</a> y'
--   insertionSort   = <a>vfold</a> (const insert)
--   </pre>
--   
--   Builds a triangular structure of compare and swaps to sort a row.
--   
--   <pre>
--   &gt;&gt;&gt; insertionSort (7 :&gt; 3 :&gt; 9 :&gt; 1 :&gt; Nil)
--   1 :&gt; 3 :&gt; 7 :&gt; 9 :&gt; Nil
--   </pre>
--   
--   The circuit layout of <tt>insertionSort</tt>, build using
--   <a>vfold</a>, is:
--   
vfold :: forall k a b. KnownNat k => (forall l. SNat l -> a -> Vec l b -> Vec (l + 1) b) -> Vec k a -> Vec k b

-- | The largest element of a non-empty vector
maximum :: Ord a => Vec (n + 1) a -> a

-- | The least element of a non-empty vector
minimum :: Ord a => Vec (n + 1) a -> a

-- | Apply a function to every element of a vector and the element's
--   position (as an <a>SNat</a> value) in the vector.
--   
--   <pre>
--   &gt;&gt;&gt; let rotateMatrix = smap (flip rotateRightS)
--   
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; rotateMatrix xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; 1 :&gt; Nil) :&gt; Nil
--   </pre>
smap :: forall k a b. KnownNat k => (forall l. SNat l -> a -> b) -> Vec k a -> Vec k b
concatBitVector# :: forall n m. (KnownNat n, KnownNat m) => Vec n (BitVector m) -> BitVector (n * m)
unconcatBitVector# :: forall n m. (KnownNat n, KnownNat m) => BitVector (n * m) -> Vec n (BitVector m)

-- | Convert a <a>Vec</a> of <a>Bit</a>s to a <a>BitVector</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let x = (0:&gt;0:&gt;0:&gt;1:&gt;0:&gt;0:&gt;1:&gt;0:&gt;Nil) :: Vec 8 Bit
--   
--   &gt;&gt;&gt; x
--   0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; Nil
--   
--   &gt;&gt;&gt; v2bv x
--   0b0001_0010
--   </pre>
v2bv :: KnownNat n => Vec n Bit -> BitVector n

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument
seqV :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqV`

-- | Evaluate all elements of a vector to WHNF
forceV :: KnownNat n => Vec n a -> Vec n a

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument. Does not propagate <a>XException</a>s.
seqVX :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqVX`

-- | Evaluate all elements of a vector to WHNF. Does not propagate
--   <a>XException</a>s.
forceVX :: KnownNat n => Vec n a -> Vec n a

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <a>id</a>
--   <a>to</a> . <a>from</a> ≡ <a>id</a>
--   </pre>
class Generic a

-- | Representable types of kind <tt>* -&gt; *</tt> (or kind <tt>k -&gt;
--   *</tt>, when <tt>PolyKinds</tt> is enabled). This class is derivable
--   in GHC with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic1</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from1</a> . <a>to1</a> ≡ <a>id</a>
--   <a>to1</a> . <a>from1</a> ≡ <a>id</a>
--   </pre>
class Generic1 (f :: k -> Type)


-- | This module can automatically generate TopEntity definitions from
--   <a>Clash.NamedTypes</a> annotations. Annotations involving data/type
--   families must be inspected for correctness. Not all cases can be
--   handled with automatic generation due to the difficulty of type
--   manipulation in template Haskell. In particular annotations
--   <b>inside</b> the following is unlikely to work:
--   
--   <ul>
--   <li>Data/type family referencing other data/type families.</li>
--   <li>Annotations inside recursive data types</li>
--   <li>Clock constraints other than a single HiddenClockResetEnable. (You
--   can still use arbitrary explicit clock/reset/enables!)</li>
--   </ul>
--   
--   See <a>Clash.Tests.TopEntityGeneration</a> for more examples.
--   
--   <pre>
--   import Clash.Annotations.TH
--   
--   data Named
--     = Named
--     { name1 :: "named1" ::: BitVector 3
--     , name2 :: "named2" ::: BitVector 5
--     }
--   
--   topEntity :: "tup1" ::: Signal System (Int, Bool)
--             -&gt; "tup2" ::: (Signal System Int, Signal System Bool)
--             -&gt; "tup3" ::: Signal System ("int":::Int, "bool":::Bool)
--             -&gt; "tup4" ::: ("int":::Signal System Int, "bool":::Signal System Bool)
--             -&gt; "custom" ::: Signal System Named
--             -&gt; "outTup" ::: Signal System ("outint":::Int, "outbool":::Bool)
--   topEntity = undefined
--   makeTopEntity 'topEntity
--   -- ===&gt;
--   --  
--   </pre>
module Clash.Annotations.TH

-- | Automatically create a <tt><a>TopEntity</a></tt> for a given
--   <tt><a>Name</a></tt>. The name of the generated RTL entity will be the
--   name of the function that has been specified; e.g.
--   <tt><a>makeTopEntity</a> 'foobar</tt> will generate a <tt>foobar</tt>
--   module.
--   
--   The function arguments and return values of the function specified by
--   the given <tt><a>Name</a></tt> must be annotated with
--   <tt><a>(:::)</a></tt>. This annotation provides the given name of the
--   port.
makeTopEntity :: Name -> DecsQ

-- | Automatically create a <tt><a>TopEntity</a></tt> for a given
--   <tt><a>Name</a></tt>, using the given <tt><a>String</a></tt> to
--   specify the name of the generated RTL entity.
--   
--   The function arguments and return values of the function specified by
--   the given <tt><a>Name</a></tt> must be annotated with
--   <tt><a>(:::)</a></tt>. This annotation provides the given name of the
--   port.
makeTopEntityWithName :: Name -> String -> DecsQ

-- | Wrap a <a>TopEntity</a> expression in an annotation pragma
makeTopEntityWithName' :: Name -> Maybe String -> DecQ

-- | Return a typed expression for a <a>TopEntity</a> of a given
--   <tt>(<a>Name</a>, <a>Type</a>)</tt>.
buildTopEntity :: Maybe String -> (Name, Type) -> TExpQ TopEntity

-- | Return a typed 'Maybe TopEntity' expression given a <a>Name</a>. This
--   will return an <a>TExp</a> of <a>Nothing</a> if <a>TopEntity</a>
--   generation failed.
maybeBuildTopEntity :: Maybe String -> Name -> Q (TExp (Maybe TopEntity))

-- | Turn the <a>Name</a> of a value to a <tt>(<a>Name</a>,
--   <a>Type</a>)</tt>
getNameBinding :: Name -> Q (Name, Type)
instance Data.Traversable.Traversable Clash.Annotations.TH.TypeF
instance Data.Foldable.Foldable Clash.Annotations.TH.TypeF
instance GHC.Base.Functor Clash.Annotations.TH.TypeF
instance GHC.Base.Functor Clash.Annotations.TH.Naming
instance GHC.Classes.Eq Clash.Annotations.TH.ClockType
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Clash.Annotations.TH.Naming a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Clash.Annotations.TH.Naming a)
instance Data.Functor.Foldable.Recursive Language.Haskell.TH.Syntax.Type
instance Data.Functor.Foldable.Corecursive Language.Haskell.TH.Syntax.Type


-- | This module contains:
--   
--   <ul>
--   <li>Template Haskell functions for deriving <a>BitPack</a> instances
--   given a custom bit representation as those defined in
--   <a>Clash.Annotations.BitRepresentation</a>.</li>
--   <li>Template Haskell functions for deriving custom bit
--   representations, e.g. one-hot, for a data type.</li>
--   </ul>
module Clash.Annotations.BitRepresentation.Deriving
deriveAnnotation :: Derivator -> Q Type -> Q [Dec]

-- | Derives BitPack instances for given type. Will account for custom bit
--   representation annotations in the module where the splice is ran. Note
--   that the generated instance might conflict with existing
--   implementations (for example, an instance for <i>Maybe a</i> exists,
--   yielding conflicts for any alternative implementations).
--   
--   Usage:
--   
--   <pre>
--   data Color = R | G | B
--   {-# ANN module (DataReprAnn
--                     $(liftQ [t|Color|])
--                     2
--                     [ ConstrRepr 'R 0b11 0b00 []
--                     , ConstrRepr 'G 0b11 0b01 []
--                     , ConstrRepr 'B 0b11 0b10 []
--                     ]) #-}
--   deriveBitPack [t| Color |]
--   
--   data MaybeColor = JustColor Color
--                   | NothingColor deriving (Generic,BitPack)
--   </pre>
--   
--   <b>NB</b>: Because of the way template haskell works the order here
--   matters, if you try to derive MaybeColor before deriveBitPack Color it
--   will complain about missing an instance BitSize Color.
deriveBitPack :: Q Type -> Q [Dec]

-- | Derives bit representation corresponding to the default manner in
--   which Clash stores types.
deriveDefaultAnnotation :: Q Type -> Q [Dec]
derivePackedAnnotation :: Q Type -> Q [Dec]

-- | Derive a compactly represented version of <tt>Maybe a</tt>.
derivePackedMaybeAnnotation :: DataReprAnn -> Q [Dec]

-- | Derives bit representation corresponding to the default manner in
--   which BlueSpec stores types.
deriveBlueSpecAnnotation :: Q Type -> Q [Dec]

-- | Derives bit representation corresponding to the default manner in
--   which Clash stores types.
defaultDerivator :: Derivator

-- | Derives bit representation corresponding to the default manner in
--   which BlueSpec stores types.
blueSpecDerivator :: Derivator

-- | This derivator tries to distribute its constructor bits over space
--   left by the difference in constructor sizes. Example:
--   
--   <pre>
--   type SmallInt = Unsigned 2
--   
--   data Train
--      = Passenger SmallInt
--      | Freight SmallInt SmallInt
--      | Maintenance
--      | Toy
--   </pre>
--   
--   The packed representation of this data type needs only a single
--   constructor bit. The first bit discriminates between <tt>Freight</tt>
--   and non-<tt>Freight</tt> constructors. All other constructors do not
--   use their last two bits; the packed representation will store the rest
--   of the constructor bits there.
packedDerivator :: Derivator
packedMaybeDerivator :: DataReprAnn -> Derivator

-- | Simple derivators change the (default) way Clash stores data types. It
--   assumes no overlap between constructors and fields.
simpleDerivator :: ConstructorType -> FieldsType -> Derivator

-- | In Haskell apply the first argument to the second argument, in HDL
--   just return the second argument.
--   
--   This is used in the generated pack/unpack to not do anything in HDL.
dontApplyInHDL :: (a -> b) -> a -> b

-- | Indicates how to pack constructor for simpleDerivator
data ConstructorType

-- | First constructor will be encoded as 0b0, the second as 0b1, the third
--   as 0b10, etc.
Binary :: ConstructorType

-- | Reserve a single bit for each constructor marker.
OneHot :: ConstructorType

-- | Indicates how to pack (constructor) fields for simpleDerivator
data FieldsType

-- | Store fields of different constructors at (possibly) overlapping bit
--   positions. That is, a data type with two constructors with each two
--   fields of each one bit will take <i>two</i> bits for its whole
--   representation (plus constructor bits). Overlap is left-biased, i.e.
--   don't care bits are padded to the right.
--   
--   This is the default behavior of Clash.
OverlapL :: FieldsType

-- | Store fields of different constructors at (possibly) overlapping bit
--   positions. That is, a data type with two constructors with each two
--   fields of each one bit will take <i>two</i> bits for its whole
--   representation (plus constructor bits). Overlap is right biased, i.e.
--   don't care bits are padded between between the constructor bits and
--   the field bits.
OverlapR :: FieldsType

-- | Store fields of different constructs at non-overlapping positions.
--   That is, a data type with two constructors with each two fields of
--   each one bit will take <i>four</i> bits for its whole representation
--   (plus constructor bits).
Wide :: FieldsType

-- | A derivator derives a bit representation given a type
type Derivator = Type -> Q DataReprAnnExp

-- | DataReprAnn as template haskell expression
type DataReprAnnExp = Exp
instance Language.Haskell.TH.Syntax.Lift Clash.Annotations.BitRepresentation.Deriving.BitMaskOrigin
instance Data.Data.Data Clash.Annotations.BitRepresentation.Deriving.BitMaskOrigin
instance GHC.Show.Show Clash.Annotations.BitRepresentation.Deriving.BitMaskOrigin
instance Control.DeepSeq.NFData Clash.Annotations.BitRepresentation.Deriving.Bit'
instance GHC.Generics.Generic Clash.Annotations.BitRepresentation.Deriving.Bit'
instance GHC.Classes.Eq Clash.Annotations.BitRepresentation.Deriving.Bit'
instance GHC.Show.Show Clash.Annotations.BitRepresentation.Deriving.Bit'


-- | Utilities for tracing signals and dumping them in various ways.
--   Example usage:
--   
--   <pre>
--   import Clash.Prelude hiding (writeFile)
--   import Data.Text.IO  (writeFile)
--   
--   -- | Count and wrap around
--   subCounter :: SystemClockResetEnable =&gt; Signal System (Index 3)
--   subCounter = traceSignal1 "sub" counter
--     where
--       counter =
--         register 0 (fmap succ' counter)
--   
--       succ' c
--         | c == maxBound = 0
--         | otherwise     = c + 1
--   
--   -- | Count, but only when my subcounter is wrapping around
--   mainCounter :: SystemClockResetEnable =&gt; Signal System (Signed 64)
--   mainCounter = traceSignal1 "main" counter
--     where
--       counter =
--         register 0 (fmap succ' $ bundle (subCounter,counter))
--   
--       succ' (sc, c)
--         | sc == maxBound = c + 1
--         | otherwise      = c
--   
--   -- | Collect traces, and dump them to a VCD file.
--   main :: IO ()
--   main = do
--     let cntrOut = exposeClockResetEnable mainCounter systemClockGen systemResetGen enableGen
--     vcd &lt;- dumpVCD (0, 100) cntrOut ["main", "sub"]
--     case vcd of
--       Left msg -&gt;
--         error msg
--       Right contents -&gt;
--         writeFile "mainCounter.vcd" contents
--   </pre>
module Clash.Signal.Trace

-- | Trace a single signal. Will emit an error if a signal with the same
--   name was previously registered.
--   
--   <b>NB</b>: Associates the traced signal with a clock period of
--   <i>1</i>, which results in incorrect VCD files when working with
--   circuits that have multiple clocks. Use <a>traceSignal</a> when
--   working with circuits that have multiple clocks.
traceSignal1 :: (BitPack a, NFDataX a, Typeable a) => String -> Signal dom a -> Signal dom a

-- | Trace a single vector signal: each element in the vector will show up
--   as a different trace. If the trace name already exists, this function
--   will emit an error.
--   
--   <b>NB</b>: Associates the traced signal with a clock period of
--   <i>1</i>, which results in incorrect VCD files when working with
--   circuits that have multiple clocks. Use <a>traceSignal</a> when
--   working with circuits that have multiple clocks.
traceVecSignal1 :: (KnownNat n, BitPack a, NFDataX a, Typeable a) => String -> Signal dom (Vec (n + 1) a) -> Signal dom (Vec (n + 1) a)

-- | Trace a single signal. Will emit an error if a signal with the same
--   name was previously registered.
--   
--   <b>NB</b>: Works correctly when creating VCD files from traced signal
--   in multi-clock circuits. However <a>traceSignal1</a> might be more
--   convenient to use when the domain of your circuit is polymorphic.
traceSignal :: forall dom a. (KnownDomain dom, BitPack a, NFDataX a, Typeable a) => String -> Signal dom a -> Signal dom a

-- | Trace a single vector signal: each element in the vector will show up
--   as a different trace. If the trace name already exists, this function
--   will emit an error.
--   
--   <b>NB</b>: Works correctly when creating VCD files from traced signal
--   in multi-clock circuits. However <a>traceSignal1</a> might be more
--   convenient to use when the domain of your circuit is polymorphic.
traceVecSignal :: forall dom a n. (KnownDomain dom, KnownNat n, BitPack a, NFDataX a, Typeable a) => String -> Signal dom (Vec (n + 1) a) -> Signal dom (Vec (n + 1) a)

-- | Produce a four-state VCD (Value Change Dump) according to IEEE
--   1364-{1995,2001}. This function fails if a trace name contains either
--   non-printable or non-VCD characters.
--   
--   Due to lazy evaluation, the created VCD files might not contain all
--   the traces you were expecting. You therefore have to provide a list of
--   names you definately want to be dumped in the VCD file.
--   
--   For example:
--   
--   <pre>
--   vcd &lt;- dumpVCD (0, 100) cntrOut ["main", "sub"]
--   </pre>
--   
--   Evaluates <i>cntrOut</i> long enough in order for to guarantee that
--   the <tt>main</tt>, and <tt>sub</tt> traces end up in the generated VCD
--   file.
dumpVCD :: NFDataX a => (Int, Int) -> Signal dom a -> [String] -> IO (Either String Text)

-- | Dump a number of samples to a replayable bytestring.
dumpReplayable :: forall a dom. NFDataX a => Int -> Signal dom a -> String -> IO ByteString

-- | Take a serialized signal (dumped with <tt>dumpReplayable</tt>) and
--   convert it back into a signal. Will error if dumped type does not
--   match requested type. The first value in the signal that fails to
--   decode will stop the decoding process and yield an error. Not that
--   this always happens if you evaluate more values than were originally
--   dumped.
replay :: forall a dom n. (Typeable a, NFDataX a, BitPack a, KnownNat n, n ~ BitSize a) => ByteString -> Either String (Signal dom a)
type Period = Int
type Changed = Bool
type Value = (Natural, Natural)
type Width = Int
type TraceMap = Map String (TypeRepBS, Period, Width, [Value])

-- | Serialized TypeRep we need to store for dumpReplayable / replay
type TypeRepBS = ByteString

-- | Trace a single signal. Will emit an error if a signal with the same
--   name was previously registered.
traceSignal# :: forall dom a. (BitPack a, NFDataX a, Typeable a) => IORef TraceMap -> Int -> String -> Signal dom a -> IO (Signal dom a)

-- | Trace a single vector signal: each element in the vector will show up
--   as a different trace. If the trace name already exists, this function
--   will emit an error.
traceVecSignal# :: forall dom n a. (KnownNat n, BitPack a, NFDataX a, Typeable a) => IORef TraceMap -> Int -> String -> Signal dom (Vec (n + 1) a) -> IO (Signal dom (Vec (n + 1) a))

-- | Same as <tt>dumpVCD</tt>, but supplied with a custom tracemap
dumpVCD# :: NFDataX a => IORef TraceMap -> (Int, Int) -> Signal dom a -> [String] -> IO (Either String Text)

-- | Same as <tt>dumpVCD</tt>, but supplied with a custom tracemap and a
--   custom timestamp
dumpVCD## :: (Int, Int) -> TraceMap -> UTCTime -> Either String Text

-- | Keep evaluating given signal until all trace names are present.
waitForTraces# :: NFDataX a => IORef TraceMap -> Signal dom a -> [String] -> IO ()

-- | Map of traces used by the non-internal trace and dumpvcd functions.
traceMap# :: IORef TraceMap


-- | This module defines the explicitly clocked counterparts of the
--   functions defined in <a>Clash.Prelude</a>.
module Clash.Explicit.Prelude

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   import qualified Data.List as L
--   
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac clk rst en = <a>mealy</a> clk rst en macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen enableGen) [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac clk rst en (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> clk rst en macT 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> clk rst en macT 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o

-- | Create a synchronous function from a combinational function describing
--   a mealy machine using the state monad. This can be particularly useful
--   when combined with lenses or optics to replicate imperative
--   algorithms.
--   
--   <pre>
--   data DelayState = DelayState
--     { _history    :: Vec 4 Int
--     , _untilValid :: Index 4
--     }
--     deriving (Generic, NFDataX)
--   makeLenses ''DelayState
--   
--   initialDelayState = DelayState (repeat 0) maxBound
--   
--   delayS :: Int -&gt; State DelayState (Maybe Int)
--   delayS n = do
--     history   %= (n +&gt;&gt;)
--     remaining &lt;- use untilValid
--     if remaining &gt; 0
--     then do
--        untilValid -= 1
--        return Nothing
--      else do
--        out &lt;- uses history last
--        return (Just out)
--   
--   delayTop ::<a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int -&gt; <a>Signal</a> dom (Maybe Int))
--   delayTop clk rst en = <a>mealyS</a> clk rst en delayS initialDelayState
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; L.take 7 $ simulate (delayTop systemClockGen systemResetGen enableGen) [-100,1,2,3,4,5,6,7,8]
--   [Nothing,Nothing,Nothing,Nothing,Just 1,Just 2,Just 3]
--   </pre>
mealyS :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (i -> State s o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool,Int) -&gt; (Int,(Int,Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (mealy clk rst en f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (mealy clk rst en f 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> clk rst en f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> clk rst en f 3 (c,i1)
--   </pre>
mealyB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | A version of <a>mealyS</a> that does automatic <a>Bundle</a>ing, see
--   <a>mealyB</a> for details.
mealySB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (i -> State s o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac clk rst en = <a>moore</a> clk rst en macT id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen enableGen) [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>KnownDomain</a> dom
--     =&gt; <a>Clock</a> dom
--     -&gt; <a>Reset</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac clk rst en (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> clk rst en macT id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> clk rst en macT id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: (KnownDomain dom, NFDataX s) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> (s -> o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (moore clk rst en t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (moore clk rst en t o 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g clk rst en a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> clk rst en t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> clk rst en t o 3 (c,i1)
--   </pre>
mooreB :: (KnownDomain dom, NFDataX s, Bundle i, Bundle o) => Clock dom -> Reset dom -> Enable dom -> (s -> i -> s) -> (s -> o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   <tt>(<a>Signal</a> a, <a>Signal</a> b)</tt>)
--   
--   <pre>
--   rP :: Clock dom -&gt; Reset dom -&gt; Enable dom
--      -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--      -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--   rP clk rst en = <a>registerB</a> clk rst en (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (rP systemClockGen systemResetGen enableGen) [(1,1),(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: (KnownDomain dom, NFDataX a, Bundle a) => Clock dom -> Reset dom -> Enable dom -> a -> Unbundled dom a -> Unbundled dom a

-- | Synchronizer based on two sequentially connected flip-flops.
--   
--   <ul>
--   <li><b>NB</b>: This synchronizer can be used for
--   <b>bit</b>-synchronization.</li>
--   <li><b>NB</b>: Although this synchronizer does reduce metastability,
--   it does not guarantee the proper synchronization of a whole
--   <b>word</b>. For example, given that the output is sampled twice as
--   fast as the input is running, and we have two samples in the input
--   stream that look like:<pre>[0111,1000]</pre>But the circuit driving
--   the input stream has a longer propagation delay on <b>msb</b> compared
--   to the <b>lsb</b>s. What can happen is an output stream that looks
--   like this:<pre>[0111,0111,0000,1000]</pre>Where the level-change of
--   the <b>msb</b> was not captured, but the level change of the
--   <b>lsb</b>s were.If you want to have <i>safe</i>
--   <b>word</b>-synchronization use <a>asyncFIFOSynchronizer</a>.</li>
--   </ul>
dualFlipFlopSynchronizer :: (NFDataX a, KnownDomain dom1, KnownDomain dom2) => Clock dom1 -> Clock dom2 -> Reset dom2 -> Enable dom2 -> a -> Signal dom1 a -> Signal dom2 a

-- | Synchronizer implemented as a FIFO around a synchronous RAM. Based on
--   the design described in <a>Clash.Tutorial#multiclock</a>, which is
--   itself based on the design described in
--   <a>http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf</a>.
--   However, this FIFO uses a synchronous dual-ported RAM which, unlike
--   those designs using RAM with an asynchronous read port, is nearly
--   guaranteed to actually synthesize into one of the dual-ported RAMs
--   found on most FPGAs.
--   
--   <b>NB</b>: This synchronizer can be used for
--   <b>word</b>-synchronization. <b>NB</b>: This synchronizer will only
--   work safely when you set up the proper bus skew and maximum delay
--   constraints inside your synthesis tool for the clock domain crossings
--   of the gray pointers.
asyncFIFOSynchronizer :: (KnownDomain wdom, KnownDomain rdom, 2 <= addrSize, NFDataX a) => SNat addrSize -> Clock wdom -> Clock rdom -> Reset wdom -> Reset rdom -> Enable wdom -> Enable rdom -> Signal rdom Bool -> Signal wdom (Maybe a) -> (Signal rdom a, Signal rdom Bool, Signal wdom Bool)

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFile</a> and
--   <a>asyncRomBlob</a> for different approaches that scale well.</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr, NFDataX a) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFilePow2</a> and
--   <a>asyncRomBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
asyncRomPow2 :: (KnownNat n, NFDataX a) => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFile</a> and
--   <a>romBlob</a> for different approaches that scale well.</li>
--   </ul>
rom :: (KnownDomain dom, KnownNat n, NFDataX a, Enum addr) => Clock dom -> Enable dom -> Vec n a -> Signal dom addr -> Signal dom a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFilePow2</a> and
--   <a>romBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
romPow2 :: (KnownDomain dom, KnownNat n, NFDataX a) => Clock dom -> Enable dom -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom a

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlob :: Enum addr => MemBlob n m -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlobPow2 :: KnownNat n => MemBlob (2 ^ n) m -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlob :: forall dom addr m n. (KnownDomain dom, Enum addr) => Clock dom -> Enable dom -> MemBlob n m -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlobPow2 :: forall dom m n. (KnownDomain dom, KnownNat n) => Clock dom -> Enable dom -> MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFile</a> is significantly slowing
--   down your simulation, give it a <i>monomorphic</i> type signature. So
--   instead of leaving the type to be inferred:<pre>myRomData =
--   asyncRomFile d512 "memory.bin" </pre>or giving it a <i>polymorphic</i>
--   type signature:<pre>myRomData :: Enum addr =&gt; addr -&gt; BitVector
--   16 myRomData = asyncRomFile d512 "memory.bin" </pre>you <b>should</b>
--   give it a <i>monomorphic</i> type signature:<pre>myRomData :: Unsigned
--   9 -&gt; BitVector 16 myRomData = asyncRomFile d512 "memory.bin"
--   </pre></li>
--   </ul>
asyncRomFile :: (KnownNat m, Enum addr) => SNat n -> FilePath -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFilePow2</a> is significantly
--   slowing down your simulation, give it a <i>monomorphic</i> type
--   signature. So instead of leaving the type to be
--   inferred:<pre>myRomData = asyncRomFilePow2 "memory.bin" </pre>you
--   <b>should</b> give it a <i>monomorphic</i> type
--   signature:<pre>myRomData :: Unsigned 9 -&gt; BitVector 16 myRomData =
--   asyncRomFilePow2 "memory.bin" </pre></li>
--   </ul>
asyncRomFilePow2 :: forall n m. (KnownNat m, KnownNat n) => FilePath -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, Enum addr, KnownDomain dom) => Clock dom -> Enable dom -> SNat n -> FilePath -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
romFilePow2 :: forall dom n m. (KnownNat m, KnownNat n, KnownDomain dom) => Clock dom -> Enable dom -> FilePath -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, NFDataX addr, HasCallStack, KnownDomain wdom, KnownDomain rdom, NFDataX a) => Clock wdom -> Clock rdom -> Enable wdom -> SNat n -> Signal rdom addr -> Signal wdom (Maybe (addr, a)) -> Signal rdom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: forall wdom rdom n a. (KnownNat n, HasCallStack, KnownDomain wdom, KnownDomain rdom, NFDataX a) => Clock wdom -> Clock rdom -> Enable wdom -> Signal rdom (Unsigned n) -> Signal wdom (Maybe (Unsigned n, a)) -> Signal rdom a

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en (<a>blockRam</a>
--   clk inits) rd wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFile</a> and
--   <a>blockRamBlob</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram40
--     :: <a>Clock</a>  dom
--     -&gt; <a>Enable</a>  dom
--     -&gt; <a>Signal</a> dom (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram40 clk en = <a>blockRam</a> clk en (<a>replicate</a> d40 1)
--   </pre>
blockRam :: (KnownDomain dom, HasCallStack, NFDataX a, Enum addr, NFDataX addr) => Clock dom -> Enable dom -> Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamPow2</a> clk inits) rd wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFilePow2</a> and
--   <a>blockRamBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram32
--     :: <a>Clock</a> dom
--     -&gt; <a>Enable</a> dom
--     -&gt; <a>Signal</a> dom (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram32 clk en = <a>blockRamPow2</a> clk en (<a>replicate</a> d32 1)
--   </pre>
blockRamPow2 :: (KnownDomain dom, HasCallStack, NFDataX a, KnownNat n) => Clock dom -> Enable dom -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that has no default values set. May be
--   cleared to an arbitrary state using a reset function.
blockRamU :: forall n dom a r addr. (KnownDomain dom, HasCallStack, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => Clock dom -> Reset dom -> Enable dom -> ResetStrategy r -> SNat n -> (Index n -> a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that is initialized with the same value
--   on all memory positions
blockRam1 :: forall n dom a r addr. (KnownDomain dom, HasCallStack, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => Clock dom -> Reset dom -> Enable dom -> ResetStrategy r -> SNat n -> a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a
data ResetStrategy (r :: Bool)
[ClearOnReset] :: ResetStrategy 'True
[NoClearOnReset] :: ResetStrategy 'False

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamBlob</a> clk en content) rd wrM</tt>.</li>
--   </ul>
blockRamBlob :: forall dom addr m n. (KnownDomain dom, Enum addr, NFDataX addr) => Clock dom -> Enable dom -> MemBlob n m -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamBlobPow2</a> clk en content) rd wrM</tt>.</li>
--   </ul>
blockRamBlobPow2 :: forall dom m n. (KnownDomain dom, KnownNat n) => Clock dom -> Enable dom -> MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en
--   (<a>blockRamFile</a> clk en size file) rd wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for more ideas on
--   how to create your own data files.</li>
--   </ul>
blockRamFile :: (KnownDomain dom, KnownNat m, Enum addr, NFDataX addr, HasCallStack) => Clock dom -> Enable dom -> SNat n -> FilePath -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst en (blockRamFilePow2'
--   clk en file) rd wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>memFile</a> for creating a data file with Clash.</li>
--   <li>See <a>Clash.Explicit.Fixed#creatingdatafiles</a> for more ideas
--   on how to create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall dom n m. (KnownDomain dom, KnownNat m, KnownNat n, HasCallStack) => Clock dom -> Enable dom -> FilePath -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Create a read-after-write block RAM from a read-before-write one
readNew :: (KnownDomain dom, NFDataX a, Eq addr) => Clock dom -> Reset dom -> Enable dom -> (Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Produces vendor-agnostic HDL that will be inferred as a true dual-port
--   block RAM
--   
--   Any value that is being written on a particular port is also the value
--   that will be read on that port, i.e. the same-port read/write behavior
--   is: WriteFirst. For mixed-port read/write, when port A writes to the
--   address port B reads from, the output of port B is undefined, and vice
--   versa.
trueDualPortBlockRam :: forall nAddrs domA domB a. (HasCallStack, KnownNat nAddrs, KnownDomain domA, KnownDomain domB, NFDataX a) => Clock domA -> Clock domB -> Signal domA (RamOp nAddrs a) -> Signal domB (RamOp nAddrs a) -> (Signal domA a, Signal domB a)

-- | Port operation
data RamOp n a

-- | Read from address
RamRead :: Index n -> RamOp n a

-- | Write data to address
RamWrite :: Index n -> a -> RamOp n a

-- | No operation
RamNoOp :: RamOp n a

-- | Give a window over a <a>Signal</a>
--   
--   @ window4
window :: (KnownNat n, KnownDomain dom, NFDataX a, Default a) => Clock dom -> Reset dom -> Enable dom -> Signal dom a -> Vec (n + 1) (Signal dom a)

-- | Give a delayed window over a <a>Signal</a>
--   
--   <pre>
--   windowD3
--     :: KnownDomain dom
--     -&gt; Clock dom
--     -&gt; Enable dom
--     -&gt; Reset dom
--     -&gt; <a>Signal</a> dom Int
--     -&gt; <a>Vec</a> 3 (<a>Signal</a> dom Int)
--   windowD3 = <a>windowD</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (windowD3 systemClockGen resetGen enableGen) [1::Int,1,2,3,4] :: [Vec 3 Int]
--   [0 :&gt; 0 :&gt; 0 :&gt; Nil,0 :&gt; 0 :&gt; 0 :&gt; Nil,1 :&gt; 0 :&gt; 0 :&gt; Nil,2 :&gt; 1 :&gt; 0 :&gt; Nil,3 :&gt; 2 :&gt; 1 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; Nil,...
--   ...
--   </pre>
windowD :: (KnownNat n, NFDataX a, Default a, KnownDomain dom) => Clock dom -> Reset dom -> Enable dom -> Signal dom a -> Vec (n + 1) (Signal dom a)

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (KnownDomain dom, NFDataX a, Bounded a, Eq a) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom a -> Signal dom Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (KnownDomain dom, NFDataX a, Bounded a, Eq a) => Clock dom -> Reset dom -> Enable dom -> a -> Signal dom a -> Signal dom Bool

-- | Give a pulse every <tt>n</tt> clock cycles. This is a useful helper
--   function when combined with functions like <tt><a>regEn</a></tt> or
--   <tt><a>mux</a></tt>, in order to delay a register by a known amount.
riseEvery :: forall dom n. KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> SNat n -> Signal dom Bool

-- | Oscillate a <tt><a>Bool</a></tt> for a given number of cycles, given
--   the starting state.
oscillate :: forall dom n. KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> Bool -> SNat n -> Signal dom Bool

-- | Compares the first two <a>Signal</a>s for equality and logs a warning
--   when they are not equal. The second <a>Signal</a> is considered the
--   expected value. This function simply returns the third <a>Signal</a>
--   unaltered as its result. This function is used by
--   <a>outputVerifier</a>.
--   
--   <h3>Usage in <tt>clashi</tt> </h3>
--   
--   <b>NB</b>: When simulating a component that uses <a>assert</a> in
--   <tt>clashi</tt>, usually, the warnings are only logged the first time
--   the component is simulated. Issuing <tt>:reload</tt> in
--   <tt>clashi</tt> will discard the cached result of the computation, and
--   warnings will once again be emitted.
--   
--   <b>NB</b>: This function <i>can</i> be used in synthesizable designs.
assert :: (KnownDomain dom, Eq a, ShowX a) => Clock dom -> Reset dom -> String -> Signal dom a -> Signal dom a -> Signal dom b -> Signal dom b

-- | Example:
--   
--   <pre>
--   testInput
--     :: KnownDomain dom
--     =&gt; Clock dom
--     -&gt; Reset dom
--     -&gt; <a>Signal</a> dom Int
--   testInput clk rst = <a>stimuliGenerator</a> clk rst $(<a>listToVecTH</a> [(1::Int),3..21])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 14 (testInput systemClockGen resetGen)
--   [1,1,3,5,7,9,11,13,15,17,19,21,21,21]
--   </pre>
stimuliGenerator :: forall l dom a. (KnownNat l, KnownDomain dom) => Clock dom -> Reset dom -> Vec l a -> Signal dom a

-- | Same as <a>outputVerifier</a> but used in cases where the test bench
--   domain and the domain of the circuit under test are the same.
outputVerifier' :: forall l a dom. (KnownNat l, KnownDomain dom, Eq a, ShowX a, 1 <= l) => Clock dom -> Reset dom -> Vec l a -> Signal dom a -> Signal dom Bool

-- | Trace a single signal. Will emit an error if a signal with the same
--   name was previously registered.
--   
--   <b>NB</b>: Associates the traced signal with a clock period of
--   <i>1</i>, which results in incorrect VCD files when working with
--   circuits that have multiple clocks. Use <a>traceSignal</a> when
--   working with circuits that have multiple clocks.
traceSignal1 :: (BitPack a, NFDataX a, Typeable a) => String -> Signal dom a -> Signal dom a

-- | Trace a single vector signal: each element in the vector will show up
--   as a different trace. If the trace name already exists, this function
--   will emit an error.
--   
--   <b>NB</b>: Associates the traced signal with a clock period of
--   <i>1</i>, which results in incorrect VCD files when working with
--   circuits that have multiple clocks. Use <a>traceSignal</a> when
--   working with circuits that have multiple clocks.
traceVecSignal1 :: (KnownNat n, BitPack a, NFDataX a, Typeable a) => String -> Signal dom (Vec (n + 1) a) -> Signal dom (Vec (n + 1) a)

-- | Trace a single signal. Will emit an error if a signal with the same
--   name was previously registered.
--   
--   <b>NB</b>: Works correctly when creating VCD files from traced signal
--   in multi-clock circuits. However <a>traceSignal1</a> might be more
--   convenient to use when the domain of your circuit is polymorphic.
traceSignal :: forall dom a. (KnownDomain dom, BitPack a, NFDataX a, Typeable a) => String -> Signal dom a -> Signal dom a

-- | Trace a single vector signal: each element in the vector will show up
--   as a different trace. If the trace name already exists, this function
--   will emit an error.
--   
--   <b>NB</b>: Works correctly when creating VCD files from traced signal
--   in multi-clock circuits. However <a>traceSignal1</a> might be more
--   convenient to use when the domain of your circuit is polymorphic.
traceVecSignal :: forall dom a n. (KnownDomain dom, KnownNat n, BitPack a, NFDataX a, Typeable a) => String -> Signal dom (Vec (n + 1) a) -> Signal dom (Vec (n + 1) a)

-- | Produce a four-state VCD (Value Change Dump) according to IEEE
--   1364-{1995,2001}. This function fails if a trace name contains either
--   non-printable or non-VCD characters.
--   
--   Due to lazy evaluation, the created VCD files might not contain all
--   the traces you were expecting. You therefore have to provide a list of
--   names you definately want to be dumped in the VCD file.
--   
--   For example:
--   
--   <pre>
--   vcd &lt;- dumpVCD (0, 100) cntrOut ["main", "sub"]
--   </pre>
--   
--   Evaluates <i>cntrOut</i> long enough in order for to guarantee that
--   the <tt>main</tt>, and <tt>sub</tt> traces end up in the generated VCD
--   file.
dumpVCD :: NFDataX a => (Int, Int) -> Signal dom a -> [String] -> IO (Either String Text)

-- | Fixed size vectors.
--   
--   <ul>
--   <li>Lists with their length encoded in their type</li>
--   <li><a>Vec</a>tor elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.</li>
--   </ul>
data Vec :: Nat -> Type -> Type
[Nil] :: Vec 0 a
[Cons] :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the head of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; 3:&gt;4:&gt;5:&gt;Nil
--   3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = 3:&gt;4:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 3 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (x :&gt; y :&gt; _) = x + y
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   7
--   </pre>
--   
--   Also in conjunctions with (<a>:&lt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:>) :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the tail of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   3 :&gt; 4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 4 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (_ :&lt; y :&lt; x) = y + x
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   13
--   </pre>
--   
--   Also in conjunctions with (<a>:&gt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:<) :: Vec n a -> a -> Vec (n + 1) a
infixr 5 :>
infixl 5 :<
infixr 5 `Cons`

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from left to right:
--   
--   <pre>
--   foldl f z (x1 :&gt; x2 :&gt; ... :&gt; xn :&gt; Nil) == (...((z `f` x1) `f` x2) `f`...) `f` xn
--   foldl f z Nil                            == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldl :: (b -> a -> b) -> b -> Vec n a -> b

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z (x1 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn1 `f` (xn `f` z))...)
--   foldr r z Nil                             == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldr :: (a -> b -> b) -> b -> Vec n a -> b

-- | "<a>map</a> <tt>f xs</tt>" is the vector obtained by applying <i>f</i>
--   to each element of <i>xs</i>, i.e.,
--   
--   <pre>
--   map f (x1 :&gt; x2 :&gt;  ... :&gt; xn :&gt; Nil) == (f x1 :&gt; f x2 :&gt; ... :&gt; f xn :&gt; Nil)
--   </pre>
--   
--   and corresponds to the following circuit layout:
--   
map :: (a -> b) -> Vec n a -> Vec n b

-- | Convert a <a>BitVector</a> to a <a>Vec</a> of <a>Bit</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 6 :: BitVector 8
--   
--   &gt;&gt;&gt; x
--   0b0000_0110
--   
--   &gt;&gt;&gt; bv2v x
--   0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 1 :&gt; 0 :&gt; Nil
--   </pre>
bv2v :: KnownNat n => BitVector n -> Vec n Bit

-- | To be used as the motive <i>p</i> for <a>dfold</a>, when the <i>f</i>
--   in "<a>dfold</a> <tt>p f</tt>" is a variation on (<a>:&gt;</a>), e.g.:
--   
--   <pre>
--   map' :: forall n a b . KnownNat n =&gt; (a -&gt; b) -&gt; Vec n a -&gt; Vec n b
--   map' f = <a>dfold</a> (Proxy @(<a>VCons</a> b)) (_ x xs -&gt; f x :&gt; xs)
--   </pre>
data VCons (a :: Type) (f :: TyFun Nat Type) :: Type
traverse# :: forall a f b n. Applicative f => (a -> f b) -> Vec n a -> f (Vec n b)

-- | Create a vector of one element
--   
--   <pre>
--   &gt;&gt;&gt; singleton 5
--   5 :&gt; Nil
--   </pre>
singleton :: a -> Vec 1 a

-- | Extract the first element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; head (1:&gt;2:&gt;3:&gt;Nil)
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; head Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘head’, namely ‘Nil’
--         In the expression: head Nil
--         In an equation for ‘it’: it = head Nil
--   </pre>
head :: Vec (n + 1) a -> a

-- | Extract the elements after the head of a vector
--   
--   <pre>
--   &gt;&gt;&gt; tail (1:&gt;2:&gt;3:&gt;Nil)
--   2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; tail Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘tail’, namely ‘Nil’
--         In the expression: tail Nil
--         In an equation for ‘it’: it = tail Nil
--   </pre>
tail :: Vec (n + 1) a -> Vec n a

-- | Extract the last element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; last (1:&gt;2:&gt;3:&gt;Nil)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; last Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘last’, namely ‘Nil’
--         In the expression: last Nil
--         In an equation for ‘it’: it = last Nil
--   </pre>
last :: Vec (n + 1) a -> a

-- | Extract all the elements of a vector except the last element
--   
--   <pre>
--   &gt;&gt;&gt; init (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; init Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘init’, namely ‘Nil’
--         In the expression: init Nil
--         In an equation for ‘it’: it = init Nil
--   </pre>
init :: Vec (n + 1) a -> Vec n a

-- | Shift in elements to the head of a vector, bumping out elements at the
--   tail. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; Nil,3 :&gt; 4 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; Nil,0 :&gt; 1 :&gt; Nil)
--   </pre>
shiftInAt0 :: KnownNat n => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift in element to the tail of a vector, bumping out elements at the
--   head. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; Nil)
--   (3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; Nil) (2 :&gt; 3 :&gt; Nil)
--   (3 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftInAtN :: KnownNat m => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Add an element to the head of a vector, and extract all but the last
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; 1 +&gt;&gt; Nil
--   Nil
--   </pre>
(+>>) :: KnownNat n => a -> Vec n a -> Vec n a
infixr 4 +>>

-- | Add an element to the tail of a vector, and extract all but the first
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) &lt;&lt;+ 1
--   4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; Nil &lt;&lt;+ 1
--   Nil
--   </pre>
(<<+) :: Vec n a -> a -> Vec n a
infixl 4 <<+

-- | Shift <i>m</i> elements out from the head of a vector, filling up the
--   tail with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFrom0 d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (3 :&gt; 4 :&gt; 5 :&gt; 0 :&gt; 0 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftOutFrom0 :: (Default a, KnownNat m) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Shift <i>m</i> elements out from the tail of a vector, filling up the
--   head with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFromN d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (0 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil,4 :&gt; 5 :&gt; Nil)
--   </pre>
shiftOutFromN :: (Default a, KnownNat n) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Append two vectors.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;Nil) ++ (7:&gt;8:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 8 :&gt; Nil
--   </pre>
(++) :: Vec n a -> Vec m a -> Vec (n + m) a
infixr 5 ++

-- | Split a vector into two vectors at the given point.
--   
--   <pre>
--   &gt;&gt;&gt; splitAt (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   
--   &gt;&gt;&gt; splitAt d3 (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAt :: SNat m -> Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector into two vectors where the length of the two is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; splitAtI (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil) :: (Vec 2 Int, Vec 3 Int)
--   (1 :&gt; 2 :&gt; Nil,3 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAtI :: KnownNat m => Vec (m + n) a -> (Vec m a, Vec n a)

-- | Concatenate a vector of vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concat ((1:&gt;2:&gt;3:&gt;Nil) :&gt; (4:&gt;5:&gt;6:&gt;Nil) :&gt; (7:&gt;8:&gt;9:&gt;Nil) :&gt; (10:&gt;11:&gt;12:&gt;Nil) :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil
--   </pre>
concat :: Vec n (Vec m a) -> Vec (n * m) a

-- | Map a function over all the elements of a vector and concatentate the
--   resulting vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concatMap (replicate d3) (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 1 :&gt; 1 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; 3 :&gt; 3 :&gt; 3 :&gt; Nil
--   </pre>
concatMap :: (a -> Vec m b) -> Vec n a -> Vec (n * m) b

-- | Split a vector of (n * m) elements into a vector of "vectors of length
--   <i>m</i>", where the length <i>m</i> is given.
--   
--   <pre>
--   &gt;&gt;&gt; unconcat d4 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcat :: KnownNat n => SNat m -> Vec (n * m) a -> Vec n (Vec m a)

-- | Split a vector of <i>(n * m)</i> elements into a vector of "vectors of
--   length <i>m</i>", where the length <i>m</i> is determined by the
--   context.
--   
--   <pre>
--   &gt;&gt;&gt; unconcatI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil) :: Vec 2 (Vec 6 Int)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcatI :: (KnownNat n, KnownNat m) => Vec (n * m) a -> Vec n (Vec m a)

-- | Merge two vectors, alternating their elements, i.e.,
--   
--   <pre>
--   &gt;&gt;&gt; merge (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   1 :&gt; 5 :&gt; 2 :&gt; 6 :&gt; 3 :&gt; 7 :&gt; 4 :&gt; 8 :&gt; Nil
--   </pre>
merge :: KnownNat n => Vec n a -> Vec n a -> Vec (2 * n) a

-- | The elements in a vector in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; reverse (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
reverse :: Vec n a -> Vec n a

-- | Apply a function of every element of a vector and its index.
--   
--   <pre>
--   &gt;&gt;&gt; :t imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Index 4)
--   
--   &gt;&gt;&gt; imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   2 :&gt; 3 :&gt; *** Exception: X: Clash.Sized.Index: result 4 is out of bounds: [0..3]
--   ...
--   
--   &gt;&gt;&gt; imap (\i a -&gt; extend (bitCoerce i) + a) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Unsigned 8)
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
imap :: forall n a b. KnownNat n => (Index n -> a -> b) -> Vec n a -> Vec n b

-- | Zip two vectors with a functions that also takes the elements'
--   indices.
--   
--   <pre>
--   &gt;&gt;&gt; izipWith (\i a b -&gt; i + a + b) (2 :&gt; 2 :&gt; Nil)  (3 :&gt; 3:&gt; Nil)
--   *** Exception: X: Clash.Sized.Index: result 3 is out of bounds: [0..1]
--   ...
--   
--   &gt;&gt;&gt; izipWith (\i a b -&gt; extend (bitCoerce i) + a + b) (2 :&gt; 2 :&gt; Nil) (3 :&gt; 3 :&gt; Nil) :: Vec 2 (Unsigned 8)
--   5 :&gt; 6 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>izipWith</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third. This matters when <a>izipWith</a> is
--   used in a recursive setting. See <a>lazyV</a> for more information.
izipWith :: KnownNat n => (Index n -> a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | Right fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findLeftmost x xs = ifoldr (\i a b -&gt; if a == x then Just i else b) Nothing xs
--   
--   &gt;&gt;&gt; findLeftmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; findLeftmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldr :: KnownNat n => (Index n -> a -> b -> b) -> b -> Vec n a -> b

-- | Left fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findRightmost x xs = ifoldl (\a i b -&gt; if b == x then Just i else a) Nothing xs
--   
--   &gt;&gt;&gt; findRightmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 4
--   
--   &gt;&gt;&gt; findRightmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldl :: KnownNat n => (a -> Index n -> b -> a) -> a -> Vec n b -> a

-- | Generate a vector of indices.
--   
--   <pre>
--   &gt;&gt;&gt; indices d4
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indices :: KnownNat n => SNat n -> Vec n (Index n)

-- | Generate a vector of indices, where the length of the vector is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; indicesI :: Vec 4 (Index 4)
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indicesI :: KnownNat n => Vec n (Index n)

-- | "<a>findIndex</a> <tt>p xs</tt>" returns the index of the <i>first</i>
--   element of <i>xs</i> satisfying the predicate <i>p</i>, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 3) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 3
--   
--   &gt;&gt;&gt; findIndex (&gt; 8) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
findIndex :: KnownNat n => (a -> Bool) -> Vec n a -> Maybe (Index n)

-- | "<a>elemIndex</a> <tt>a xs</tt>" returns the index of the <i>first</i>
--   element which is equal (by <a>==</a>) to the query element <i>a</i>,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndex 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; elemIndex 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
elemIndex :: (KnownNat n, Eq a) => a -> Vec n a -> Maybe (Index n)

-- | <a>zipWith</a> generalizes <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "<a>zipWith</a> <tt>(+)</tt>" applied to two vectors produces
--   the vector of corresponding sums.
--   
--   <pre>
--   zipWith f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) == (f x1 y1 :&gt; f x2 y2 :&gt; ... :&gt; f xn yn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith</a> <tt>f xs ys</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>zipWith</a> is <i>strict</i> in its second argument, and
--   <i>lazy</i> in its third. This matters when <a>zipWith</a> is used in
--   a recursive setting. See <a>lazyV</a> for more information.
zipWith :: (a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>zipWith3</a> generalizes <a>zip3</a> by zipping with the function
--   given as the first argument, instead of a tupling function.
--   
--   <pre>
--   zipWith3 f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) (z1 :&gt; z2 :&gt; ... :&gt; zn :&gt; Nil) == (f x1 y1 z1 :&gt; f x2 y2 z2 :&gt; ... :&gt; f xn yn zn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith3</a> <tt>f xs ys zs</tt>" corresponds to the following
--   circuit layout:
--   
--   
--   <b>NB</b>: <a>zipWith3</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third and fourth. This matters when
--   <a>zipWith3</a> is used in a recursive setting. See <a>lazyV</a> for
--   more information.
zipWith3 :: (a -> b -> c -> d) -> Vec n a -> Vec n b -> Vec n c -> Vec n d
zipWith4 :: (a -> b -> c -> d -> e) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e
zipWith5 :: (a -> b -> c -> d -> e -> f) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f
zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g
zipWith7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n h

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldr1 f (x1 :&gt; ... :&gt; xn2 :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn2 `f` (xn1 `f` xn))...)
--   foldr1 f (x1 :&gt; Nil)                            == x1
--   foldr1 f Nil                                    == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (/) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldr1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldl1 f (x1 :&gt; x2 :&gt; x3 :&gt; ... :&gt; xn :&gt; Nil) == (...((x1 `f` x2) `f` x3) `f`...) `f` xn
--   foldl1 f (x1 :&gt; Nil)                          == x1
--   foldl1 f Nil                                  == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (/) (1 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldl1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>fold</a> is a variant of <a>foldr1</a> and <a>foldl1</a>, but
--   instead of reducing from right to left, or left to right, it reduces a
--   vector using a tree-like structure. The depth, or delay, of the
--   structure produced by "<tt><a>fold</a> f xs</tt>", is hence
--   <tt>O(log_2(<a>length</a> xs))</tt>, and not <tt>O(<a>length</a>
--   xs)</tt>.
--   
--   <b>NB</b>: The binary operator "<tt>f</tt>" in "<tt><a>fold</a> f
--   xs</tt>" must be associative.
--   
--   <pre>
--   fold f (x1 :&gt; x2 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == ((x1 `f` x2) `f` ...) `f` (... `f` (xn1 `f` xn))
--   fold f (x1 :&gt; Nil)                           == x1
--   fold f Nil                                   == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fold (+) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   15
--   </pre>
--   
--   "<a>fold</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
fold :: forall n a. (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a vector of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == z :&gt; (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   0 :&gt; 5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>scanl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>last (scanl f z xs) == foldl f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanl :: (b -> a -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>scanl</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanl1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   1 :&gt; -1 :&gt; -4 :&gt; -8 :&gt; Nil
--   </pre>
scanl1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>scanr</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanr1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   -2 :&gt; 3 :&gt; -1 :&gt; 4 :&gt; Nil
--   </pre>
scanr1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>postscanl</a> is a variant of <a>scanl</a> where the first result
--   is dropped:
--   
--   <pre>
--   postscanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>postscanl</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanl :: (b -> a -> b) -> b -> Vec n a -> Vec n b

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a vector of
--   successive reduced values from the right:
--   
--   <pre>
--   scanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; z :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; 0 :&gt; Nil
--   </pre>
--   
--   "<a>scanr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>head (scanr f z xs) == foldr f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanr :: (a -> b -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>postscanr</a> is a variant of <a>scanr</a> that where the last
--   result is dropped:
--   
--   <pre>
--   postscanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   "<a>postscanr</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanr :: (a -> b -> b) -> b -> Vec n a -> Vec n b

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumL (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,1 :&gt; 2 :&gt; 4 :&gt; 7 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumL</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumL :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumR (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,10 :&gt; 8 :&gt; 5 :&gt; 1 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumR</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumR :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | <a>zip</a> takes two vectors and returns a vector of corresponding
--   pairs.
--   
--   <pre>
--   &gt;&gt;&gt; zip (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil)
--   (1,4) :&gt; (2,3) :&gt; (3,2) :&gt; (4,1) :&gt; Nil
--   </pre>
zip :: Vec n a -> Vec n b -> Vec n (a, b)

-- | <a>zip3</a> takes three vectors and returns a vector of corresponding
--   triplets.
--   
--   <pre>
--   &gt;&gt;&gt; zip3 (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil) (5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   (1,4,5) :&gt; (2,3,6) :&gt; (3,2,7) :&gt; (4,1,8) :&gt; Nil
--   </pre>
zip3 :: Vec n a -> Vec n b -> Vec n c -> Vec n (a, b, c)

-- | <a>zip4</a> takes four vectors and returns a list of quadruples,
--   analogous to <a>zip</a>.
zip4 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n (a, b, c, d)

-- | <a>zip5</a> takes five vectors and returns a list of five-tuples,
--   analogous to <a>zip</a>.
zip5 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n (a, b, c, d, e)

-- | <a>zip6</a> takes six vectors and returns a list of six-tuples,
--   analogous to <a>zip</a>.
zip6 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n (a, b, c, d, e, f)

-- | <a>zip7</a> takes seven vectors and returns a list of seven-tuples,
--   analogous to <a>zip</a>.
zip7 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n (a, b, c, d, e, f, g)

-- | <a>unzip</a> transforms a vector of pairs into a vector of first
--   components and a vector of second components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip ((1,4):&gt;(2,3):&gt;(3,2):&gt;(4,1):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   </pre>
unzip :: Vec n (a, b) -> (Vec n a, Vec n b)

-- | <a>unzip3</a> transforms a vector of triplets into a vector of first
--   components, a vector of second components, and a vector of third
--   components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip3 ((1,4,5):&gt;(2,3,6):&gt;(3,2,7):&gt;(4,1,8):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil,5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
unzip3 :: Vec n (a, b, c) -> (Vec n a, Vec n b, Vec n c)

-- | <a>unzip4</a> takes a vector of quadruples and returns four vectors,
--   analogous to <a>unzip</a>.
unzip4 :: Vec n (a, b, c, d) -> (Vec n a, Vec n b, Vec n c, Vec n d)

-- | <a>unzip5</a> takes a vector of five-tuples and returns five vectors,
--   analogous to <a>unzip</a>.
unzip5 :: Vec n (a, b, c, d, e) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e)

-- | <a>unzip6</a> takes a vector of six-tuples and returns six vectors,
--   analogous to <a>unzip</a>.
unzip6 :: Vec n (a, b, c, d, e, f) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f)

-- | <a>unzip7</a> takes a vector of seven-tuples and returns seven
--   vectors, analogous to <a>unzip</a>.
unzip7 :: Vec n (a, b, c, d, e, f, g) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f, Vec n g)

-- | "<tt>xs</tt> <a>!!</a> <tt>n</tt>" returns the <i>n</i>'th element of
--   <i>xs</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 4
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! (length (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) - 1)
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 1
--   2
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 4
--   ...
--   </pre>
(!!) :: (KnownNat n, Enum i) => Vec n a -> i -> a

-- | The length of a <a>Vec</a>tor as an <a>Int</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; length (6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   3
--   </pre>
length :: KnownNat n => Vec n a -> Int

-- | "<a>replace</a> <tt>n a xs</tt>" returns the vector <i>xs</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; replace 3 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 0 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   7 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 9 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; *** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 4
--   ...
--   </pre>
replace :: (KnownNat n, Enum i) => i -> a -> Vec n a -> Vec n a

-- | "<a>take</a> <tt>n xs</tt>" returns the <i>n</i>-length prefix of
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; take (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d0               (1:&gt;2:&gt;Nil)
--   Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘4 + n0’ with ‘2’
--         Expected type: Vec (4 + n0) a
--           Actual type: Vec (1 + 1) a
--         The type variable ‘n0’ is ambiguous
--       • In the second argument of ‘take’, namely ‘(1 :&gt; 2 :&gt; Nil)’
--         In the expression: take d4 (1 :&gt; 2 :&gt; Nil)
--         In an equation for ‘it’: it = take d4 (1 :&gt; 2 :&gt; Nil)
--   </pre>
take :: SNat m -> Vec (m + n) a -> Vec m a

-- | "<a>takeI</a> <tt>xs</tt>" returns the prefix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; takeI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   1 :&gt; 2 :&gt; Nil
--   </pre>
takeI :: KnownNat m => Vec (m + n) a -> Vec m a

-- | "<a>drop</a> <tt>n xs</tt>" returns the suffix of <i>xs</i> after the
--   first <i>n</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; drop (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d0               (1:&gt;2:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; drop d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...: error:...
--       • Couldn't match...type ‘4 + n0...
--         The type variable ‘n0’ is ambiguous
--       • In the first argument of ‘print’, namely ‘it’
--         In a stmt of an interactive GHCi command: print it
--   </pre>
drop :: SNat m -> Vec (m + n) a -> Vec n a

-- | "<a>dropI</a> <tt>xs</tt>" returns the suffix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; dropI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   4 :&gt; 5 :&gt; Nil
--   </pre>
dropI :: KnownNat m => Vec (m + n) a -> Vec n a

-- | "<a>at</a> <tt>n xs</tt>" returns <i>n</i>'th element of <i>xs</i>
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; at (SNat :: SNat 1) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   
--   &gt;&gt;&gt; at d1               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   </pre>
at :: SNat m -> Vec (m + (n + 1)) a -> a

-- | "<a>select</a> <tt>f s n xs</tt>" selects <i>n</i> elements with
--   step-size <i>s</i> and offset <tt>f</tt> from <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; select (SNat :: SNat 1) (SNat :: SNat 2) (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; select d1 d2 d3 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   </pre>
select :: CmpNat (i + s) (s * n) ~ 'GT => SNat f -> SNat s -> SNat n -> Vec (f + i) a -> Vec n a

-- | "<a>selectI</a> <tt>f s xs</tt>" selects as many elements as demanded
--   by the context with step-size <i>s</i> and offset <i>f</i> from
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; selectI d1 d2 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil) :: Vec 2 Int
--   2 :&gt; 4 :&gt; Nil
--   </pre>
selectI :: (CmpNat (i + s) (s * n) ~ 'GT, KnownNat n) => SNat f -> SNat s -> Vec (f + i) a -> Vec n a

-- | "<a>replicate</a> <tt>n a</tt>" returns a vector that has <i>n</i>
--   copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; replicate (SNat :: SNat 3) 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; replicate d3 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
replicate :: SNat n -> a -> Vec n a

-- | "<a>repeat</a> <tt>a</tt>" creates a vector with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; repeat 6 :: Vec 5 Int
--   6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
repeat :: KnownNat n => a -> Vec n a

-- | "<a>iterate</a> <tt>n f x</tt>" returns a vector starting with
--   <i>x</i> followed by <i>n</i> repeated applications of <i>f</i> to
--   <i>x</i>.
--   
--   <pre>
--   iterate (SNat :: SNat 4) f x == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   iterate d4 f x               == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterate d4 (+1) 1
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>iterate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
iterate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>iterateI</a> <tt>f x</tt>" returns a vector starting with
--   <tt>x</tt> followed by <tt>n</tt> repeated applications of <tt>f</tt>
--   to <tt>x</tt>, where <tt>n</tt> is determined by the context.
--   
--   <pre>
--   iterateI f x :: Vec 3 a == (x :&gt; f x :&gt; f (f x) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterateI (+1) 1 :: Vec 3 Int
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   "<a>iterateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
iterateI :: forall n a. KnownNat n => (a -> a) -> a -> Vec n a

-- | "<a>unfoldr</a> <tt>n f s</tt>" builds a vector of length <tt>n</tt>
--   from a seed value <tt>s</tt>, where every element <tt>a</tt> is
--   created by successive calls of <tt>f</tt> on <tt>s</tt>. Unlike
--   <a>unfoldr</a> from <a>Data.List</a> the generating function
--   <tt>f</tt> cannot dictate the length of the resulting vector, it must
--   be statically known.
--   
--   a simple use of <a>unfoldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr d10 (\s -&gt; (s,s-1)) 10
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldr :: SNat n -> (s -> (a, s)) -> s -> Vec n a

-- | "<a>unfoldrI</a> <tt>f s</tt>" builds a vector from a seed value
--   <tt>s</tt>, where every element <tt>a</tt> is created by successive
--   calls of <tt>f</tt> on <tt>s</tt>; the length of the vector is
--   inferred from the context. Unlike <a>unfoldr</a> from <a>Data.List</a>
--   the generating function <tt>f</tt> cannot dictate the length of the
--   resulting vector, it must be statically known.
--   
--   a simple use of <a>unfoldrI</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldrI (\s -&gt; (s,s-1)) 10 :: Vec 10 Int
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldrI :: KnownNat n => (s -> (a, s)) -> s -> Vec n a

-- | "<a>generate</a> <tt>n f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>.
--   
--   <pre>
--   generate (SNat :: SNat 4) f x == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   generate d4 f x               == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generate d4 (+1) 1
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>generate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
generate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>generateI</a> <tt>f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>, where <tt>n</tt> is
--   determined by the context.
--   
--   <pre>
--   generateI f x :: Vec 3 a == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generateI (+1) 1 :: Vec 3 Int
--   2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>generateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
generateI :: KnownNat n => (a -> a) -> a -> Vec n a

-- | Transpose a matrix: go from row-major to column-major
--   
--   <pre>
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;Nil):&gt;(3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; transpose xss
--   (1 :&gt; 3 :&gt; 5 :&gt; Nil) :&gt; (2 :&gt; 4 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
transpose :: KnownNat n => Vec m (Vec n a) -> Vec n (Vec m a)

-- | 1-dimensional stencil computations
--   
--   "<a>stencil1d</a> <tt>stX f xs</tt>", where <i>xs</i> has <i>stX +
--   n</i> elements, applies the stencil computation <i>f</i> on: <i>n +
--   1</i> overlapping (1D) windows of length <i>stX</i>, drawn from
--   <i>xs</i>. The resulting vector has <i>n + 1</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t stencil1d d2 sum xs
--   stencil1d d2 sum xs :: Num b =&gt; Vec 5 b
--   
--   &gt;&gt;&gt; stencil1d d2 sum xs
--   3 :&gt; 5 :&gt; 7 :&gt; 9 :&gt; 11 :&gt; Nil
--   </pre>
stencil1d :: KnownNat n => SNat (stX + 1) -> (Vec (stX + 1) a -> b) -> Vec ((stX + n) + 1) a -> Vec (n + 1) b

-- | 2-dimensional stencil computations
--   
--   "<a>stencil2d</a> <tt>stY stX f xss</tt>", where <i>xss</i> is a
--   matrix of <i>stY + m</i> rows of <i>stX + n</i> elements, applies the
--   stencil computation <i>f</i> on: <i>(m + 1) * (n + 1)</i> overlapping
--   (2D) windows of <i>stY</i> rows of <i>stX</i> elements, drawn from
--   <i>xss</i>. The result matrix has <i>m + 1</i> rows of <i>n + 1</i>
--   elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t stencil2d d2 d2 (sum . map sum) xss
--   stencil2d d2 d2 (sum . map sum) xss :: Num b =&gt; Vec 3 (Vec 3 b)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stencil2d d2 d2 (sum . map sum) xss
--   (14 :&gt; 18 :&gt; 22 :&gt; Nil) :&gt; (30 :&gt; 34 :&gt; 38 :&gt; Nil) :&gt; (46 :&gt; 50 :&gt; 54 :&gt; Nil) :&gt; Nil
--   </pre>
stencil2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> (Vec (stY + 1) (Vec (stX + 1) a) -> b) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) b)

-- | "<a>windows1d</a> <tt>stX xs</tt>", where the vector <i>xs</i> has
--   <i>stX + n</i> elements, returns a vector of <i>n + 1</i> overlapping
--   (1D) windows of <i>xs</i> of length <i>stX</i>.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t windows1d d2 xs
--   windows1d d2 xs :: Num a =&gt; Vec 5 (Vec 2 a)
--   
--   &gt;&gt;&gt; windows1d d2 xs
--   (1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
windows1d :: KnownNat n => SNat (stX + 1) -> Vec ((stX + n) + 1) a -> Vec (n + 1) (Vec (stX + 1) a)

-- | "<a>windows2d</a> <tt>stY stX xss</tt>", where matrix <i>xss</i> has
--   <i>stY + m</i> rows of <i>stX + n</i>, returns a matrix of <i>m+1</i>
--   rows of <i>n+1</i> elements. The elements of this new matrix are the
--   overlapping (2D) windows of <i>xss</i>, where every window has
--   <i>stY</i> rows of <i>stX</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   
--   &gt;&gt;&gt; :t windows2d d2 d2 xss
--   windows2d d2 d2 xss :: Num a =&gt; Vec 3 (Vec 3 (Vec 2 (Vec 2 a)))
--   
--   &gt;&gt;&gt; windows2d d2 d2 xss
--   (((1 :&gt; 2 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil) :&gt; ((2 :&gt; 3 :&gt; Nil) :&gt; (6 :&gt; 7 :&gt; Nil) :&gt; Nil) :&gt; ((3 :&gt; 4 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((5 :&gt; 6 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; Nil) :&gt; Nil) :&gt; ((6 :&gt; 7 :&gt; Nil) :&gt; (10 :&gt; 11 :&gt; Nil) :&gt; Nil) :&gt; ((7 :&gt; 8 :&gt; Nil) :&gt; (11 :&gt; 12 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((9 :&gt; 10 :&gt; Nil) :&gt; (13 :&gt; 14 :&gt; Nil) :&gt; Nil) :&gt; ((10 :&gt; 11 :&gt; Nil) :&gt; (14 :&gt; 15 :&gt; Nil) :&gt; Nil) :&gt; ((11 :&gt; 12 :&gt; Nil) :&gt; (15 :&gt; 16 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; Nil
--   </pre>
windows2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) (Vec (stY + 1) (Vec (stX + 1) a)))

-- | Forward permutation specified by an index mapping, <i>ix</i>. The
--   result vector is initialized by the given defaults, <i>def</i>, and an
--   further values that are permuted into the result are added to the
--   current value using the given combination function, <i>f</i>.
--   
--   The combination function must be <i>associative</i> and
--   <i>commutative</i>.
permute :: (Enum i, KnownNat n, KnownNat m) => (a -> a -> a) -> Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>backpermute</a> <tt>xs is</tt>" is equivalent to "<a>map</a>
--   <tt>(xs <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; backpermute input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
backpermute :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | Copy elements from the source vector, <i>xs</i>, to the destination
--   vector according to an index mapping <i>is</i>. This is a forward
--   permute operation where a <i>to</i> vector encodes an input to output
--   index mapping. Output elements for indices that are not mapped assume
--   the value in the default vector <i>def</i>.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let defVec = 0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;Nil
--   
--   &gt;&gt;&gt; let to = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;8:&gt;Nil
--   
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; scatter defVec to input
--   0 :&gt; 1 :&gt; 4 :&gt; 9 :&gt; 0 :&gt; 4 :&gt; 0 :&gt; 6 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: If the same index appears in the index mapping more than
--   once, the latest mapping is chosen.
scatter :: (Enum i, KnownNat n, KnownNat m) => Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>gather</a> <tt>xs is</tt>" is equivalent to "<a>map</a> <tt>(xs
--   <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; gather input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
gather :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | "<a>interleave</a> <tt>d xs</tt>" creates a vector:
--   
--   <pre>
--   &lt;x_0,x_d,x_(2d),...,x_1,x_(d+1),x_(2d+1),...,x_(d-1),x_(2d-1),x_(3d-1)&gt;
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; Nil
--   
--   &gt;&gt;&gt; interleave d3 xs
--   1 :&gt; 4 :&gt; 7 :&gt; 2 :&gt; 5 :&gt; 8 :&gt; 3 :&gt; 6 :&gt; 9 :&gt; Nil
--   </pre>
interleave :: (KnownNat n, KnownNat d) => SNat d -> Vec (n * d) a -> Vec (d * n) a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs (-1)
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeftS</a> if you want to rotate left by a
--   <i>static</i> amount.
rotateLeft :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs (-1)
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRightS</a> if you want to rotate right by a
--   <i>static</i> amount.
rotateRight :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeftS xs d1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeft</a> if you want to rotate left by a
--   <i>dynamic</i> amount.
rotateLeftS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRightS xs d1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRight</a> if you want to rotate right by a
--   <i>dynamic</i> amount.
rotateRightS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | Convert a vector to a list.
--   
--   <pre>
--   &gt;&gt;&gt; toList (1:&gt;2:&gt;3:&gt;Nil)
--   [1,2,3]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
toList :: Vec n a -> [a]

-- | Create a vector literal from a list literal.
--   
--   <pre>
--   $(listToVecTH [1::Signed 8,2,3,4,5]) == (8:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 5 (Signed 8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1 :: Signed 8,2,3,4,5]
--   [1,2,3,4,5]
--   
--   &gt;&gt;&gt; $(listToVecTH [1::Signed 8,2,3,4,5])
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
listToVecTH :: Lift a => [a] -> ExpQ

-- | <a>Vec</a>tor as a <a>Proxy</a> for <a>Nat</a>
asNatProxy :: Vec n a -> Proxy n

-- | Length of a <a>Vec</a>tor as an <a>SNat</a> value
lengthS :: KnownNat n => Vec n a -> SNat n

-- | What you should use when your vector functions are too strict in their
--   arguments.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwapL a b = if a &lt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; :{
--   let sortVL :: (Ord a, KnownNat (n + 1)) =&gt; Vec ((n + 1) + 1) a -&gt; Vec ((n + 1) + 1) a
--       sortVL xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith compareSwapL (lazyV lefts) rights
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let sortV_flip xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith (flip compareSwapL) rights lefts
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   For example:
--   
--   <pre>
--   -- Bubble sort for 1 iteration
--   sortV xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL lefts rights
--   
--   -- Compare and swap
--   compareSwapL a b = if a &lt; b then (a,b)
--                               else (b,a)
--   </pre>
--   
--   Will not terminate because <a>zipWith</a> is too strict in its second
--   argument.
--   
--   In this case, adding <a>lazyV</a> on <a>zipWith</a>s second argument:
--   
--   <pre>
--   sortVL xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; map snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL (<a>lazyV</a> lefts) rights
--   </pre>
--   
--   Results in a successful computation:
--   
--   <pre>
--   &gt;&gt;&gt; sortVL (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: There is also a solution using <a>flip</a>, but it slightly
--   obfuscates the meaning of the code:
--   
--   <pre>
--   sortV_flip xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> (<a>flip</a> compareSwapL) rights lefts
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sortV_flip (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
lazyV :: KnownNat n => Vec n a -> Vec n a

-- | A <i>dependently</i> typed fold.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -fplugin GHC.TypeLits.Normalise
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data Append (m :: Nat) (a :: Type) (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply (Append m a) l = Vec (l + m) a
--   
--   &gt;&gt;&gt; let append' xs ys = dfold (Proxy :: Proxy (Append m a)) (const (:&gt;)) ys xs
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   Using lists, we can define <i>append</i> (a.k.a.
--   <tt>Data.List.</tt><a>++</a>) in terms of
--   <tt>Data.List.</tt><a>foldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List
--   
--   &gt;&gt;&gt; let append xs ys = Data.List.foldr (:) ys xs
--   
--   &gt;&gt;&gt; append [1,2] [3,4]
--   [1,2,3,4]
--   </pre>
--   
--   However, when we try to do the same for <a>Vec</a>, by defining
--   <i>append'</i> in terms of <tt>Clash.Sized.Vector.</tt><a>foldr</a>:
--   
--   <pre>
--   append' xs ys = <a>foldr</a> (:&gt;) ys xs
--   </pre>
--   
--   we get a type error:
--   
--   <pre>
--   <b>&gt;&gt;&gt; let append' xs ys = foldr (:&gt;) ys xs</b>
--   
--   &lt;interactive&gt;:...
--       • Occurs check: cannot construct the infinite type: ... ~ ... + 1
--         Expected type: a -&gt; Vec ... a -&gt; Vec ... a
--           Actual type: a -&gt; Vec ... a -&gt; Vec (... + 1) a
--       • In the first argument of ‘foldr’, namely ‘(:&gt;)’
--         In the expression: foldr (:&gt;) ys xs
--         In an equation for ‘append'’: append' xs ys = foldr (:&gt;) ys xs
--       • Relevant bindings include
--           ys :: Vec ... a (bound at ...)
--           append' :: Vec n a -&gt; Vec ... a -&gt; Vec ... a
--             (bound at ...)
--   </pre>
--   
--   The reason is that the type of <a>foldr</a> is:
--   
--   <pre>
--   &gt;&gt;&gt; :t foldr
--   foldr :: (a -&gt; b -&gt; b) -&gt; b -&gt; Vec n a -&gt; b
--   </pre>
--   
--   While the type of (<a>:&gt;</a>) is:
--   
--   <pre>
--   &gt;&gt;&gt; :t (:&gt;)
--   (:&gt;) :: a -&gt; Vec n a -&gt; Vec (n + 1) a
--   </pre>
--   
--   We thus need a <tt>fold</tt> function that can handle the growing
--   vector type: <a>dfold</a>. Compared to <a>foldr</a>, <a>dfold</a>
--   takes an extra parameter, called the <i>motive</i>, that allows the
--   folded function to have an argument and result type that
--   <i>depends</i> on the current length of the vector. Using
--   <a>dfold</a>, we can now correctly define <i>append'</i>:
--   
--   <pre>
--   import Data.Singletons
--   import Data.Proxy
--   
--   data Append (m :: Nat) (a :: Type) (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> (Append m a) l = <a>Vec</a> (l + m) a
--   
--   append' xs ys = <a>dfold</a> (Proxy :: Proxy (Append m a)) (const (<a>:&gt;</a>)) ys xs
--   </pre>
--   
--   We now see that <i>append'</i> has the appropriate type:
--   
--   <pre>
--   &gt;&gt;&gt; :t append'
--   append' :: KnownNat k =&gt; Vec k a -&gt; Vec m a -&gt; Vec (k + m) a
--   </pre>
--   
--   And that it works:
--   
--   <pre>
--   &gt;&gt;&gt; append' (1 :&gt; 2 :&gt; Nil) (3 :&gt; 4 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: "<tt><a>dfold</a> m f z xs</tt>" creates a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Look at <a>dtfold</a> for a <i>dependently</i> typed fold
--   that produces a structure with a depth of O(log_2(<tt><a>length</a>
--   xs</tt>)).
dfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (forall l. SNat l -> a -> (p @@ l) -> p @@ (l + 1)) -> (p @@ 0) -> Vec k a -> p @@ k

-- | A combination of <a>dfold</a> and <a>fold</a>: a <i>dependently</i>
--   typed fold that reduces a vector in a tree-like structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XUndecidableInstances
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data IIndex (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply IIndex l = Index ((2^l)+1)
--   
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat k, KnownNat (2^k)) =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--       populationCount' bv = dtfold (Proxy @IIndex)
--                                    fromIntegral
--                                    (\_ x y -&gt; add x y)
--                                    (bv2v bv)
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <a>BitVector</a>. Given a vector of <i>n</i> bits, we
--   only need we need a data type that can represent the number <i>n</i>:
--   <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a range of
--   <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits), hence we need
--   <a>Index</a> <tt>n+1</tt>. As an initial attempt we will use
--   <a>sum</a>, because it gives a nice (<tt>log2(n)</tt>) tree-structure
--   of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (n+1), KnownNat (n+2))
--                   =&gt; <a>BitVector</a> (n+1) -&gt; <a>Index</a> (n+2)
--   populationCount = sum . map fromIntegral . <a>bv2v</a>
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>add</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <a>fold</a> to create a tree-structure
--   of <a>add</a>es:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (n+1), KnownNat (n+2))
--                        =&gt; BitVector (n+1) -&gt; Index (n+2)
--       populationCount' = fold add . map fromIntegral . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘((n + 2) + (n + 2)) - 1’ with ‘n + 2’
--         Expected type: Index (n + 2) -&gt; Index (n + 2) -&gt; Index (n + 2)
--           Actual type: Index (n + 2)
--                        -&gt; Index (n + 2) -&gt; AResult (Index (n + 2)) (Index (n + 2))
--       • In the first argument of ‘fold’, namely ‘add’
--         In the first argument of ‘(.)’, namely ‘fold add’
--         In the expression: fold add . map fromIntegral . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (n + 1) -&gt; Index (n + 2)
--             (bound at ...)
--   </pre>
--   
--   because <a>fold</a> expects a function of type "<tt>a -&gt; a -&gt;
--   a</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>add</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons
--   import Data.Proxy
--   
--   data IIndex (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>dtfold</a> (Proxy @IIndex)
--                                fromIntegral
--                                (\_ x y -&gt; <a>add</a> x y)
--                                (<a>bv2v</a> bv)
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
--   
--   Some final remarks:
--   
--   <ul>
--   <li>By using <a>dtfold</a> instead of <a>fold</a>, we had to restrict
--   our <a>BitVector</a> argument to have bit-width that is a power of
--   2.</li>
--   <li>Even though our original <i>populationCount</i> function specified
--   a structure where all adders had the same width. Most
--   VHDL/(System)Verilog synthesis tools will create a more efficient
--   circuit, i.e. one where the adders have an increasing bit-width for
--   every layer, from the VHDL/(System)Verilog produced by the Clash
--   compiler.</li>
--   </ul>
--   
--   <b>NB</b>: The depth, or delay, of the structure produced by
--   "<tt><a>dtfold</a> m f g xs</tt>" is O(log_2(<tt><a>length</a>
--   xs</tt>)).
dtfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (a -> p @@ 0) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> p @@ (l + 1)) -> Vec (2 ^ k) a -> p @@ k

-- | Specialised version of <a>dfold</a> that builds a triangular
--   computational structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; let insert y xs = let (y',xs') = mapAccumL compareSwap y xs in xs' :&lt; y'
--   
--   &gt;&gt;&gt; let insertionSort = vfold (const insert)
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   <pre>
--   compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   insert y xs     = let (y',xs') = <a>mapAccumL</a> compareSwap y xs in xs' <a>:&lt;</a> y'
--   insertionSort   = <a>vfold</a> (const insert)
--   </pre>
--   
--   Builds a triangular structure of compare and swaps to sort a row.
--   
--   <pre>
--   &gt;&gt;&gt; insertionSort (7 :&gt; 3 :&gt; 9 :&gt; 1 :&gt; Nil)
--   1 :&gt; 3 :&gt; 7 :&gt; 9 :&gt; Nil
--   </pre>
--   
--   The circuit layout of <tt>insertionSort</tt>, build using
--   <a>vfold</a>, is:
--   
vfold :: forall k a b. KnownNat k => (forall l. SNat l -> a -> Vec l b -> Vec (l + 1) b) -> Vec k a -> Vec k b

-- | The largest element of a non-empty vector
maximum :: Ord a => Vec (n + 1) a -> a

-- | The least element of a non-empty vector
minimum :: Ord a => Vec (n + 1) a -> a

-- | Apply a function to every element of a vector and the element's
--   position (as an <a>SNat</a> value) in the vector.
--   
--   <pre>
--   &gt;&gt;&gt; let rotateMatrix = smap (flip rotateRightS)
--   
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; rotateMatrix xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; 1 :&gt; Nil) :&gt; Nil
--   </pre>
smap :: forall k a b. KnownNat k => (forall l. SNat l -> a -> b) -> Vec k a -> Vec k b
concatBitVector# :: forall n m. (KnownNat n, KnownNat m) => Vec n (BitVector m) -> BitVector (n * m)
unconcatBitVector# :: forall n m. (KnownNat n, KnownNat m) => BitVector (n * m) -> Vec n (BitVector m)

-- | Convert a <a>Vec</a> of <a>Bit</a>s to a <a>BitVector</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let x = (0:&gt;0:&gt;0:&gt;1:&gt;0:&gt;0:&gt;1:&gt;0:&gt;Nil) :: Vec 8 Bit
--   
--   &gt;&gt;&gt; x
--   0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; Nil
--   
--   &gt;&gt;&gt; v2bv x
--   0b0001_0010
--   </pre>
v2bv :: KnownNat n => Vec n Bit -> BitVector n

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument
seqV :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqV`

-- | Evaluate all elements of a vector to WHNF
forceV :: KnownNat n => Vec n a -> Vec n a

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument. Does not propagate <a>XException</a>s.
seqVX :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqVX`

-- | Evaluate all elements of a vector to WHNF. Does not propagate
--   <a>XException</a>s.
forceVX :: KnownNat n => Vec n a -> Vec n a

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <a>id</a>
--   <a>to</a> . <a>from</a> ≡ <a>id</a>
--   </pre>
class Generic a

-- | Representable types of kind <tt>* -&gt; *</tt> (or kind <tt>k -&gt;
--   *</tt>, when <tt>PolyKinds</tt> is enabled). This class is derivable
--   in GHC with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic1</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from1</a> . <a>to1</a> ≡ <a>id</a>
--   <a>to1</a> . <a>from1</a> ≡ <a>id</a>
--   </pre>
class Generic1 (f :: k -> Type)

-- | A <a>Lift</a> instance can have any of its values turned into a
--   Template Haskell expression. This is needed when a value used within a
--   Template Haskell quotation is bound outside the Oxford brackets
--   (<tt>[| ... |]</tt> or <tt>[|| ... ||]</tt>) but not at the top level.
--   As an example:
--   
--   <pre>
--   add1 :: Int -&gt; Q (TExp Int)
--   add1 x = [|| x + 1 ||]
--   </pre>
--   
--   Template Haskell has no way of knowing what value <tt>x</tt> will take
--   on at splice-time, so it requires the type of <tt>x</tt> to be an
--   instance of <a>Lift</a>.
--   
--   A <a>Lift</a> instance must satisfy <tt>$(lift x) ≡ x</tt> and
--   <tt>$$(liftTyped x) ≡ x</tt> for all <tt>x</tt>, where <tt>$(...)</tt>
--   and <tt>$$(...)</tt> are Template Haskell splices. It is additionally
--   expected that <tt><a>lift</a> x ≡ <a>unTypeQ</a> (<a>liftTyped</a>
--   x)</tt>.
--   
--   <a>Lift</a> instances can be derived automatically by use of the
--   <tt>-XDeriveLift</tt> GHC language extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveLift #-}
--   module Foo where
--   
--   import Language.Haskell.TH.Syntax
--   
--   data Bar a = Bar1 a (Bar a) | Bar2 String
--     deriving Lift
--   </pre>
--   
--   Levity-polymorphic since <i>template-haskell-2.16.0.0</i>.
class Lift (t :: TYPE r)

-- | Turn a value into a Template Haskell expression, suitable for use in a
--   splice.
lift :: Lift t => t -> Q Exp

-- | Turn a value into a Template Haskell typed expression, suitable for
--   use in a typed splice.
liftTyped :: Lift t => t -> Q (TExp t)


-- | Clash is a functional hardware description language that borrows both
--   its syntax and semantics from the functional programming language
--   Haskell. The merits of using a functional language to describe
--   hardware comes from the fact that combinational circuits can be
--   directly modeled as mathematical functions and that functional
--   languages lend themselves very well at describing and (de-)composing
--   mathematical functions.
--   
--   This package provides:
--   
--   <ul>
--   <li>Prelude library containing datatypes and functions for circuit
--   design</li>
--   </ul>
--   
--   To use the library:
--   
--   <ul>
--   <li>Import <a>Clash.Prelude</a>; by default clock and reset lines are
--   implicitly routed for all the components found in
--   <a>Clash.Prelude</a>. You can read more about implicit clock and reset
--   lines in <a>Clash.Signal#implicitclockandreset</a></li>
--   <li>Alternatively, if you want to explicitly route clock and reset
--   ports, for more straightforward multi-clock designs, you can import
--   the <a>Clash.Explicit.Prelude</a> module. Note that you should not
--   import <a>Clash.Prelude</a> and <a>Clash.Explicit.Prelude</a> at the
--   same time as they have overlapping definitions.</li>
--   </ul>
--   
--   For now, <a>Clash.Prelude</a> is also the best starting point for
--   exploring the library. A preliminary version of a tutorial can be
--   found in <a>Clash.Tutorial</a>. Some circuit examples can be found in
--   <a>Clash.Examples</a>.
module Clash.Prelude

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac :: HiddenClockResetEnable dom  =&gt; <a>Signal</a> dom (Int, Int) -&gt; <a>Signal</a> dom Int
--   mac = <a>mealy</a> macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockResetEnable dom
--     =&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> macT 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> macT 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: (HiddenClockResetEnable dom, NFDataX s) => (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o

-- | Create a synchronous function from a combinational function describing
--   a mealy machine using the state monad. This can be particularly useful
--   when combined with lenses or optics to replicate imperative
--   algorithms.
--   
--   <pre>
--   data DelayState = DelayState
--     { _history    :: Vec 4 Int
--     , _untilValid :: Index 4
--     }
--     deriving (Generic, NFDataX)
--   makeLenses ''DelayState
--   
--   initialDelayState = DelayState (repeat 0) maxBound
--   
--   delayS :: Int -&gt; State DelayState (Maybe Int)
--   delayS n = do
--     history   %= (n +&gt;&gt;)
--     remaining &lt;- use untilValid
--     if remaining &gt; 0
--     then do
--        untilValid -= 1
--        return Nothing
--      else do
--        out &lt;- uses history last
--        return (Just out)
--   
--   delayTop :: HiddenClockResetEnable dom  =&gt; <a>Signal</a> dom Int -&gt; <a>Signal</a> dom (Maybe Int)
--   delayTop = <a>mealyS</a> delayS initialDelayState
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; L.take 7 $ simulate @System delayTop [1,2,3,4,5,6,7,8]
--   [Nothing,Nothing,Nothing,Just 1,Just 2,Just 3,Just 4]
--   ...
--   </pre>
mealyS :: (HiddenClockResetEnable dom, NFDataX s) => (i -> State s o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool, Int) -&gt; (Int, (Int, Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>mealy</a> f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>mealy</a> f 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> f 3 (c,i1)
--   </pre>
mealyB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | A version of <a>mealyS</a> that does automatic <a>Bundle</a>ing, see
--   <a>mealyB</a> for details.
mealySB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (i -> State s o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Infix version of <a>mealyB</a>
(<^>) :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; Int        -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: HiddenClockResetEnable dom
--     =&gt; <a>Signal</a> dom (Int, Int)
--     -&gt; <a>Signal</a> dom Int
--   mac = <a>moore</a> mac id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
--   [0,0,1,5,14,30,...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockResetEnable dom
--     =&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; (<a>Signal</a> dom Int, <a>Signal</a> dom Int)
--     -&gt; <a>Signal</a> dom Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> macT id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> macT id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: (HiddenClockResetEnable dom, NFDataX s) => (s -> i -> s) -> (s -> o) -> s -> Signal dom i -> Signal dom o

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>moore</a> t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>moore</a> t o 3 (<a>bundle</a> (c,i1)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> t o 3 (c,i1)
--   </pre>
mooreB :: (HiddenClockResetEnable dom, NFDataX s, Bundle i, Bundle o) => (s -> i -> s) -> (s -> o) -> s -> Unbundled dom i -> Unbundled dom o

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   '(Signal a, Signal b)')
--   
--   <pre>
--   rP :: HiddenClockResetEnable dom
--      =&gt; (Signal dom Int, Signal dom Int)
--      -&gt; (Signal dom Int, Signal dom Int)
--   rP = registerB (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System rP [(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: (HiddenClockResetEnable dom, NFDataX a, Bundle a) => a -> Unbundled dom a -> Unbundled dom a
infixr 3 `registerB`

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFile</a> and
--   <a>asyncRomBlob</a> for different approaches that scale well.</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr, NFDataX a) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>asyncRomFilePow2</a> and
--   <a>asyncRomBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
asyncRomPow2 :: (KnownNat n, NFDataX a) => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFile</a> and
--   <a>romBlob</a> for different approaches that scale well.</li>
--   </ul>
rom :: forall dom n m a. (NFDataX a, KnownNat n, KnownNat m, HiddenClock dom, HiddenEnable dom) => Vec n a -> Signal dom (Unsigned m) -> Signal dom a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   <li>A large <a>Vec</a> for the content may be too inefficient,
--   depending on how it is constructed. See <a>romFilePow2</a> and
--   <a>romBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
romPow2 :: forall dom n a. (KnownNat n, NFDataX a, HiddenClock dom, HiddenEnable dom) => Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom a

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlob :: Enum addr => MemBlob n m -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
asyncRomBlobPow2 :: KnownNat n => MemBlob (2 ^ n) m -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlob :: forall dom addr m n. (HiddenClock dom, HiddenEnable dom, Enum addr) => MemBlob n m -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs.</li>
--   </ul>
romBlobPow2 :: forall dom m n. (HiddenClock dom, HiddenEnable dom, KnownNat n) => MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFile</a> is significantly slowing
--   down your simulation, give it a <i>monomorphic</i> type signature. So
--   instead of leaving the type to be inferred:<pre>myRomData =
--   asyncRomFile d512 "memory.bin" </pre>or giving it a <i>polymorphic</i>
--   type signature:<pre>myRomData :: Enum addr =&gt; addr -&gt; BitVector
--   16 myRomData = asyncRomFile d512 "memory.bin" </pre>you <b>should</b>
--   give it a <i>monomorphic</i> type signature:<pre>myRomData :: Unsigned
--   9 -&gt; BitVector 16 myRomData = asyncRomFile d512 "memory.bin"
--   </pre></li>
--   </ul>
asyncRomFile :: (KnownNat m, Enum addr) => SNat n -> FilePath -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFilePow2</a> is significantly
--   slowing down your simulation, give it a <i>monomorphic</i> type
--   signature. So instead of leaving the type to be
--   inferred:<pre>myRomData = asyncRomFilePow2 "memory.bin" </pre>you
--   <b>should</b> give it a <i>monomorphic</i> type
--   signature:<pre>myRomData :: Unsigned 9 -&gt; BitVector 16 myRomData =
--   asyncRomFilePow2 "memory.bin" </pre></li>
--   </ul>
asyncRomFilePow2 :: forall n m. (KnownNat m, KnownNat n) => FilePath -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, KnownNat n, HiddenClock dom, HiddenEnable dom, Enum addr) => SNat n -> FilePath -> Signal dom addr -> Signal dom (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFilePow2 :: forall n m dom. (KnownNat m, KnownNat n, HiddenClock dom, HiddenEnable dom) => FilePath -> Signal dom (Unsigned n) -> Signal dom (BitVector m)

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, NFDataX addr, HiddenClock dom, HiddenEnable dom, HasCallStack, NFDataX a) => SNat n -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <i>undefined</i>, reading
--   it will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: (KnownNat n, HiddenClock dom, HiddenEnable dom, HasCallStack, NFDataX a) => Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRam</a> inits) rd
--   wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFile</a> and
--   <a>blockRamBlob</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram40
--     :: <a>HiddenClock</a> dom
--     =&gt; <a>Signal</a> dom (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram40 = <a>blockRam</a> (<a>replicate</a> d40 1)
--   </pre>
blockRam :: (HasCallStack, HiddenClock dom, HiddenEnable dom, NFDataX a, Enum addr, NFDataX addr) => Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamPow2</a> inits) rd
--   wrM</tt>.</li>
--   <li>A large <a>Vec</a> for the initial content may be too inefficient,
--   depending on how it is constructed. See <a>blockRamFilePow2</a> and
--   <a>blockRamBlobPow2</a> for different approaches that scale well.</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   bram32
--     :: <a>HiddenClock</a> dom
--     =&gt; <a>Signal</a> dom (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> dom (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> dom <a>Bit</a>
--   bram32 = <a>blockRamPow2</a> (<a>replicate</a> d32 1)
--   </pre>
blockRamPow2 :: (HasCallStack, HiddenClock dom, HiddenEnable dom, NFDataX a, KnownNat n) => Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that has no default values set. May be
--   cleared to an arbitrary state using a reset function.
blockRamU :: forall n dom a r addr. (HasCallStack, HiddenClockResetEnable dom, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => ResetStrategy r -> SNat n -> (Index n -> a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | A version of <a>blockRam</a> that is initialized with the same value
--   on all memory positions
blockRam1 :: forall n dom a r addr. (HasCallStack, HiddenClockResetEnable dom, NFDataX a, Enum addr, NFDataX addr, 1 <= n) => ResetStrategy r -> SNat n -> a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a
data ResetStrategy (r :: Bool)
[ClearOnReset] :: ResetStrategy 'True
[NoClearOnReset] :: ResetStrategy 'False

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamBlob</a> content)
--   rd wrM</tt>.</li>
--   </ul>
blockRamBlob :: forall dom addr m n. (HiddenClock dom, HiddenEnable dom, Enum addr, NFDataX addr) => MemBlob n m -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   </ul>
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamBlobPow2</a>
--   content) rd wrM</tt>.</li>
--   </ul>
blockRamBlobPow2 :: forall dom m n. (HiddenClock dom, HiddenEnable dom, KnownNat n) => MemBlob (2 ^ n) m -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Efficient storage of memory content
--   
--   It holds <tt>n</tt> words of <tt><a>BitVector</a> m</tt>.
data MemBlob (n :: Nat) (m :: Nat)

-- | Create a <a>MemBlob</a> binding from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>createMemBlob</a> can refer to something defined in the same
--   module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   <a>createMemBlob</a> "content" <a>Nothing</a> [15 :: Unsigned 8 .. 17]
--   
--   ram clk en = <a>blockRamBlob</a> clk en content
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; :{
--   createMemBlob "content0" (Just 0) es
--   createMemBlob "content1" (Just 1) es
--   x = 1
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   createMemBlob "contentN" Nothing es
--   x = 1
--   :}
--   
--   &lt;interactive&gt;:...: error:...
--       packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--   </pre>
--   
--   Note how we hinted to <tt>clashi</tt> that our multi-line command was
--   a list of declarations by including a dummy declaration <tt>x =
--   1</tt>. Without this trick, <tt>clashi</tt> would expect an expression
--   and the Template Haskell would not work.
createMemBlob :: forall a f. (Foldable f, BitPack a) => String -> Maybe Bit -> f a -> DecsQ

-- | Create a <a>MemBlob</a> from a list of values
--   
--   Since this uses Template Haskell, nothing in the arguments given to
--   <a>memBlobTH</a> can refer to something defined in the same module.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   ram clk en = <a>blockRamBlob</a> clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])
--   </pre>
--   
--   The <a>Maybe</a> datatype has don't care bits, where the actual value
--   does not matter. But the bits need a defined value in the memory.
--   Either 0 or 1 can be used, and both are valid representations of the
--   data.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Prelude as P
--   
--   &gt;&gt;&gt; let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
--   
--   &gt;&gt;&gt; content0 = $(memBlobTH (Just 0) es)
--   
--   &gt;&gt;&gt; content1 = $(memBlobTH (Just 1) es)
--   
--   &gt;&gt;&gt; let pr = mapM_ (putStrLn . show)
--   
--   &gt;&gt;&gt; pr $ P.map pack es
--   0b0_...._....
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content0
--   0b0_0000_0000
--   0b1_0000_0111
--   0b1_0000_1000
--   
--   &gt;&gt;&gt; pr $ unpackMemBlob content1
--   0b0_1111_1111
--   0b1_0000_0111
--   0b1_0000_1000
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(memBlobTH Nothing es)
--   
--   &lt;interactive&gt;:...: error:...
--       • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
--       • In the untyped splice: $(memBlobTH Nothing es)
--   </pre>
memBlobTH :: forall a f. (Foldable f, BitPack a) => Maybe Bit -> f a -> ExpQ

-- | Convert a <a>MemBlob</a> back to a list
--   
--   <b>NB</b>: Not synthesizable
unpackMemBlob :: forall n m. MemBlob n m -> [BitVector m]

-- | Create a block RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamFile</a> size
--   file) rd wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFile :: (KnownNat m, Enum addr, NFDataX addr, HiddenClock dom, HiddenEnable dom, HasCallStack) => SNat n -> FilePath -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a block RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <i>undefined</i>, reading it
--   will throw an <a>XException</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:</li>
--   </ul>
--   
--   TODO: table
--   
--   <h3>See also:</h3>
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> (<a>blockRamFilePow2</a> file)
--   rd wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall dom n m. (KnownNat m, KnownNat n, HiddenClock dom, HiddenEnable dom, HasCallStack) => FilePath -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Create a read-after-write block RAM from a read-before-write one
--   
--   <pre>
--   &gt;&gt;&gt; :t readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--   readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--     :: ...
--        ...
--        ...
--        ...
--        ... =&gt;
--        Signal dom addr -&gt; Signal dom (Maybe (addr, a)) -&gt; Signal dom a
--   </pre>
readNew :: (HiddenClockResetEnable dom, NFDataX a, Eq addr) => (Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a) -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Produces vendor-agnostic HDL that will be inferred as a true dual-port
--   block RAM
--   
--   Any value that is being written on a particular port is also the value
--   that will be read on that port, i.e. the same-port read/write behavior
--   is: WriteFirst. For mixed-port read/write, when port A writes to the
--   address port B reads from, the output of port B is undefined, and vice
--   versa.
trueDualPortBlockRam :: forall nAddrs dom a. (HasCallStack, KnownNat nAddrs, HiddenClock dom, NFDataX a) => Signal dom (RamOp nAddrs a) -> Signal dom (RamOp nAddrs a) -> (Signal dom a, Signal dom a)

-- | Port operation
data RamOp n a

-- | Read from address
RamRead :: Index n -> RamOp n a

-- | Write data to address
RamWrite :: Index n -> a -> RamOp n a

-- | No operation
RamNoOp :: RamOp n a

-- | Give a window over a <a>Signal</a>
--   
--   <pre>
--   window4 :: HiddenClockResetEnable dom
--           =&gt; Signal dom Int -&gt; Vec 4 (Signal dom Int)
--   window4 = window
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System window4 [1::Int,2,3,4,5] :: [Vec 4 Int]
--   [1 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; Nil,2 :&gt; 1 :&gt; 0 :&gt; 0 :&gt; Nil,3 :&gt; 2 :&gt; 1 :&gt; 0 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil,5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil,...
--   ...
--   </pre>
window :: (HiddenClockResetEnable dom, KnownNat n, Default a, NFDataX a) => Signal dom a -> Vec (n + 1) (Signal dom a)

-- | Give a delayed window over a <a>Signal</a>
--   
--   <pre>
--   windowD3
--     :: HiddenClockResetEnable dom
--     =&gt; Signal dom Int
--     -&gt; Vec 3 (Signal dom Int)
--   windowD3 = windowD
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System windowD3 [1::Int,2,3,4] :: [Vec 3 Int]
--   [0 :&gt; 0 :&gt; 0 :&gt; Nil,1 :&gt; 0 :&gt; 0 :&gt; Nil,2 :&gt; 1 :&gt; 0 :&gt; Nil,3 :&gt; 2 :&gt; 1 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; Nil,...
--   ...
--   </pre>
windowD :: (HiddenClockResetEnable dom, KnownNat n, Default a, NFDataX a) => Signal dom a -> Vec (n + 1) (Signal dom a)

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (HiddenClockResetEnable dom, NFDataX a, Bounded a, Eq a) => a -> Signal dom a -> Signal dom Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (HiddenClockResetEnable dom, NFDataX a, Bounded a, Eq a) => a -> Signal dom a -> Signal dom Bool

-- | Give a pulse every <tt>n</tt> clock cycles. This is a useful helper
--   function when combined with functions like <tt><a>regEn</a></tt> or
--   <tt><a>mux</a></tt>, in order to delay a register by a known amount.
--   
--   To be precise: the given signal will be <tt><a>False</a></tt> for the
--   next <tt>n-1</tt> cycles, followed by a single <tt><a>True</a></tt>
--   value:
--   
--   <pre>
--   &gt;&gt;&gt; Prelude.last (sampleN @System 1025 (riseEvery d1024)) == True
--   True
--   
--   &gt;&gt;&gt; Prelude.or (sampleN @System 1024 (riseEvery d1024)) == False
--   True
--   </pre>
--   
--   For example, to update a counter once every 10 million cycles:
--   
--   <pre>
--   counter = <a>regEn</a> 0 (<a>riseEvery</a> (<a>SNat</a> :: <a>SNat</a> 10000000)) (counter + 1)
--   </pre>
riseEvery :: HiddenClockResetEnable dom => SNat n -> Signal dom Bool

-- | Oscillate a <tt><a>Bool</a></tt> for a given number of cycles. This is
--   a convenient function when combined with something like
--   <tt><a>regEn</a></tt>, as it allows you to easily hold a register
--   value for a given number of cycles. The input <tt><a>Bool</a></tt>
--   determines what the initial value is.
--   
--   To oscillate on an interval of 5 cycles:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 11 (oscillate False d5)
--   [False,False,False,False,False,False,True,True,True,True,True]
--   </pre>
--   
--   To oscillate between <tt><a>True</a></tt> and <tt><a>False</a></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 11 (oscillate False d1)
--   [False,False,True,False,True,False,True,False,True,False,True]
--   </pre>
--   
--   An alternative definition for the above could be:
--   
--   <pre>
--   &gt;&gt;&gt; let osc' = register False (not &lt;$&gt; osc')
--   
--   &gt;&gt;&gt; sampleN @System 200 (oscillate False d1) == sampleN @System 200 osc'
--   True
--   </pre>
oscillate :: HiddenClockResetEnable dom => Bool -> SNat n -> Signal dom Bool

-- | Trace a single signal. Will emit an error if a signal with the same
--   name was previously registered.
--   
--   <b>NB</b>: Associates the traced signal with a clock period of
--   <i>1</i>, which results in incorrect VCD files when working with
--   circuits that have multiple clocks. Use <a>traceSignal</a> when
--   working with circuits that have multiple clocks.
traceSignal1 :: (BitPack a, NFDataX a, Typeable a) => String -> Signal dom a -> Signal dom a

-- | Trace a single vector signal: each element in the vector will show up
--   as a different trace. If the trace name already exists, this function
--   will emit an error.
--   
--   <b>NB</b>: Associates the traced signal with a clock period of
--   <i>1</i>, which results in incorrect VCD files when working with
--   circuits that have multiple clocks. Use <a>traceSignal</a> when
--   working with circuits that have multiple clocks.
traceVecSignal1 :: (KnownNat n, BitPack a, NFDataX a, Typeable a) => String -> Signal dom (Vec (n + 1) a) -> Signal dom (Vec (n + 1) a)

-- | Trace a single signal. Will emit an error if a signal with the same
--   name was previously registered.
--   
--   <b>NB</b>: Works correctly when creating VCD files from traced signal
--   in multi-clock circuits. However <a>traceSignal1</a> might be more
--   convenient to use when the domain of your circuit is polymorphic.
traceSignal :: forall dom a. (KnownDomain dom, BitPack a, NFDataX a, Typeable a) => String -> Signal dom a -> Signal dom a

-- | Trace a single vector signal: each element in the vector will show up
--   as a different trace. If the trace name already exists, this function
--   will emit an error.
--   
--   <b>NB</b>: Works correctly when creating VCD files from traced signal
--   in multi-clock circuits. However <a>traceSignal1</a> might be more
--   convenient to use when the domain of your circuit is polymorphic.
traceVecSignal :: forall dom a n. (KnownDomain dom, KnownNat n, BitPack a, NFDataX a, Typeable a) => String -> Signal dom (Vec (n + 1) a) -> Signal dom (Vec (n + 1) a)

-- | Produce a four-state VCD (Value Change Dump) according to IEEE
--   1364-{1995,2001}. This function fails if a trace name contains either
--   non-printable or non-VCD characters.
--   
--   Due to lazy evaluation, the created VCD files might not contain all
--   the traces you were expecting. You therefore have to provide a list of
--   names you definately want to be dumped in the VCD file.
--   
--   For example:
--   
--   <pre>
--   vcd &lt;- dumpVCD (0, 100) cntrOut ["main", "sub"]
--   </pre>
--   
--   Evaluates <i>cntrOut</i> long enough in order for to guarantee that
--   the <tt>main</tt>, and <tt>sub</tt> traces end up in the generated VCD
--   file.
dumpVCD :: NFDataX a => (Int, Int) -> Signal dom a -> [String] -> IO (Either String Text)

-- | A reset signal belonging to a domain called <i>dom</i>.
--   
--   The underlying representation of resets is <a>Bool</a>.
data Reset (dom :: Domain)

-- | A differential clock signal belonging to a domain named <i>dom</i>.
--   The clock input of a design with such an input has two ports which are
--   in antiphase. The first input is the positive phase, the second the
--   negative phase. When using <a>makeTopEntity</a>, the names of the
--   inputs will end in <tt>_p</tt> and <tt>_n</tt> respectively.
--   
--   To create a differential clock in a test bench, you can use
--   <a>clockToDiffClock</a>.
data DiffClock (dom :: Domain)

-- | A clock signal belonging to a domain named <i>dom</i>.
data Clock (dom :: Domain)

-- | A signal of booleans, indicating whether a component is enabled. No
--   special meaning is implied, it's up to the component itself to decide
--   how to respond to its enable line. It is used throughout Clash as a
--   global enable signal.
data Enable dom

-- | Clash has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (dom :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>dom</i> is the <i>clock-</i>
--   (and <i>reset-</i>) domain to which the memory elements manipulating
--   these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>dom</i>, is of the kind <a>Domain</a> - a
--   simple string. That string refers to a single <i>synthesis domain</i>.
--   A synthesis domain describes the behavior of certain aspects of memory
--   elements in it.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   <li><b>NB</b>: For the best compatibility make sure your period is
--   divisible by 2, because some VHDL simulators don't support fractions
--   of picoseconds.</li>
--   <li><b>NB</b>: Whether <a>System</a> has good defaults depends on your
--   target platform. Check out <a>IntelSystem</a> and <a>XilinxSystem</a>
--   too!</li>
--   </ul>
--   
--   Signals have the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i Signal
--   type role Signal nominal representational
--   ...
--   </pre>
--   
--   as it is safe to coerce the underlying value of a signal, but not safe
--   to coerce a signal between different synthesis domains.
--   
--   See the module documentation of <a>Clash.Signal</a> for more
--   information about domains.
data Signal (dom :: Domain) a
type Domain = Symbol

-- | Same as SDomainConfiguration but allows for easy updates through
--   record update syntax. Should be used in combination with
--   <a>vDomain</a> and <a>createDomain</a>. Example:
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
data VDomainConfiguration
VDomainConfiguration :: String -> Natural -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> VDomainConfiguration

-- | Corresponds to <a>_name</a> on <a>DomainConfiguration</a>
[vName] :: VDomainConfiguration -> String

-- | Corresponds to <a>_period</a> on <a>DomainConfiguration</a>
[vPeriod] :: VDomainConfiguration -> Natural

-- | Corresponds to <a>_activeEdge</a> on <a>DomainConfiguration</a>
[vActiveEdge] :: VDomainConfiguration -> ActiveEdge

-- | Corresponds to <a>_resetKind</a> on <a>DomainConfiguration</a>
[vResetKind] :: VDomainConfiguration -> ResetKind

-- | Corresponds to <a>_initBehavior</a> on <a>DomainConfiguration</a>
[vInitBehavior] :: VDomainConfiguration -> InitBehavior

-- | Corresponds to <a>_resetPolarity</a> on <a>DomainConfiguration</a>
[vResetPolarity] :: VDomainConfiguration -> ResetPolarity

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and synchronously to
--   changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type XilinxSystem = ("XilinxSystem" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type IntelSystem = ("IntelSystem" :: Domain)

-- | A clock (and reset) dom with clocks running at 100 MHz. Memory
--   elements respond to the rising edge of the clock, and asynchronously
--   to changes in reset signals. It has defined initial values, and
--   active-high resets.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
type System = ("System" :: Domain)

-- | A <a>KnownDomain</a> constraint indicates that a circuit's behavior
--   depends on some properties of a domain. See <a>DomainConfiguration</a>
--   for more information.
class (KnownSymbol dom, KnownNat (DomainPeriod dom)) => KnownDomain (dom :: Domain) where {
    type family KnownConf dom :: DomainConfiguration;
}

-- | Returns <a>SDomainConfiguration</a> corresponding to an instance's
--   <a>DomainConfiguration</a>.
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; knownDomain @System
--   SDomainConfiguration {sName = SSymbol @"System", sPeriod = SNat @10000, sActiveEdge = SRising, sResetKind = SAsynchronous, sInitBehavior = SDefined, sResetPolarity = SActiveHigh}
--   </pre>
knownDomain :: KnownDomain dom => SDomainConfiguration dom (KnownConf dom)
type KnownConfiguration dom conf = (KnownDomain dom, KnownConf dom ~ conf)

-- | Singleton version of <a>DomainConfiguration</a>
data SDomainConfiguration (dom :: Domain) (conf :: DomainConfiguration)
[SDomainConfiguration] :: {sName :: SSymbol dom " Domain name", sPeriod :: SNat period " Period of clock in /ps/", sActiveEdge :: SActiveEdge edge " Active edge of the clock (not yet implemented)", sResetKind :: SResetKind reset " Whether resets are synchronous (edge-sensitive) or asynchronous (level-sensitive)", sInitBehavior :: SInitBehavior init " Whether the initial (or "power up") value of memory elements is unknown/undefined, or configurable to a specific value", sResetPolarity :: SResetPolarity polarity " Whether resets are active high or active low"} -> SDomainConfiguration dom ('DomainConfiguration dom period edge reset init polarity)

-- | Convenience type to help to extract the reset polarity from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetPolarity dom ~ 'ActiveHigh) =&gt; ...
--   </pre>
type DomainResetPolarity (dom :: Domain) = DomainConfigurationResetPolarity (KnownConf dom)

-- | Convenience type to constrain a domain to have initial values. Example
--   usage:
--   
--   <pre>
--   myFunc :: HasDefinedInitialValues dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   Note that there is no <tt>UnknownInitialValues dom</tt> as a component
--   that works without initial values will also work if it does have them.
--   
--   <a>Click here for usage hints</a>
type HasDefinedInitialValues (dom :: Domain) = (KnownDomain dom, DomainInitBehavior dom ~ 'Defined)

-- | Convenience type to help to extract the initial value behavior from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainInitBehavior dom ~ 'Defined) =&gt; ...
--   </pre>
type DomainInitBehavior (dom :: Domain) = DomainConfigurationInitBehavior (KnownConf dom)

-- | Convenience type to constrain a domain to have asynchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasAsynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasAsynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Asynchronous)

-- | Convenience type to constrain a domain to have synchronous resets.
--   Example usage:
--   
--   <pre>
--   myFunc :: HasSynchronousReset dom =&gt; ...
--   </pre>
--   
--   Using this type implies <a>KnownDomain</a>.
--   
--   <a>Click here for usage hints</a>
type HasSynchronousReset (dom :: Domain) = (KnownDomain dom, DomainResetKind dom ~ 'Synchronous)

-- | Convenience type to help to extract the reset synchronicity from a
--   domain. Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainResetKind dom ~ 'Synchronous) =&gt; ...
--   </pre>
type DomainResetKind (dom :: Domain) = DomainConfigurationResetKind (KnownConf dom)

-- | Convenience type to help to extract the active edge from a domain.
--   Example usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainActiveEdge dom ~ 'Rising) =&gt; ...
--   </pre>
type DomainActiveEdge (dom :: Domain) = DomainConfigurationActiveEdge (KnownConf dom)

-- | Convenience type to help to extract a period from a domain. Example
--   usage:
--   
--   <pre>
--   myFunc :: (KnownDomain dom, DomainPeriod dom ~ 6000) =&gt; ...
--   </pre>
type DomainPeriod (dom :: Domain) = DomainConfigurationPeriod (KnownConf dom)

-- | A domain with a name (<tt>Domain</tt>). Configures the behavior of
--   various aspects of a circuits. See the documentation of this record's
--   field types for more information on the options.
--   
--   See module documentation of <a>Clash.Explicit.Signal</a> for more
--   information on how to create custom synthesis domains.
data DomainConfiguration
DomainConfiguration :: Domain -> Nat -> ActiveEdge -> ResetKind -> InitBehavior -> ResetPolarity -> DomainConfiguration

-- | Domain name
[_name] :: DomainConfiguration -> Domain

-- | Period of clock in <i>ps</i>
[_period] :: DomainConfiguration -> Nat

-- | Active edge of the clock
[_activeEdge] :: DomainConfiguration -> ActiveEdge

-- | Whether resets are synchronous (edge-sensitive) or asynchronous
--   (level-sensitive)
[_resetKind] :: DomainConfiguration -> ResetKind

-- | Whether the initial (or "power up") value of memory elements is
--   unknown/undefined, or configurable to a specific value
[_initBehavior] :: DomainConfiguration -> InitBehavior

-- | Whether resets are active high or active low
[_resetPolarity] :: DomainConfiguration -> ResetPolarity
data SInitBehavior (init :: InitBehavior)
[SUnknown] :: SInitBehavior 'Unknown
[SDefined] :: SInitBehavior 'Defined
data InitBehavior

-- | Power up value of memory elements is <i>unknown</i>.
Unknown :: InitBehavior

-- | If applicable, power up value of a memory element is defined. Applies
--   to <a>register</a>s for example, but not to <a>blockRam</a>.
Defined :: InitBehavior

-- | Singleton version of <a>ResetPolarity</a>
data SResetPolarity (polarity :: ResetPolarity)
[SActiveHigh] :: SResetPolarity 'ActiveHigh
[SActiveLow] :: SResetPolarity 'ActiveLow

-- | Determines the value for which a reset line is considered "active"
data ResetPolarity

-- | Reset is considered active if underlying signal is <a>True</a>.
ActiveHigh :: ResetPolarity

-- | Reset is considered active if underlying signal is <a>False</a>.
ActiveLow :: ResetPolarity

-- | Singleton version of <a>ResetKind</a>
data SResetKind (resetKind :: ResetKind)
[SAsynchronous] :: SResetKind 'Asynchronous
[SSynchronous] :: SResetKind 'Synchronous
data ResetKind

-- | Elements respond <i>asynchronously</i> to changes in their reset
--   input. This means that they do <i>not</i> wait for the next active
--   clock edge, but respond immediately instead. Common on Intel FPGA
--   platforms.
Asynchronous :: ResetKind

-- | Elements respond <i>synchronously</i> to changes in their reset input.
--   This means that changes in their reset input won't take effect until
--   the next active clock edge. Common on Xilinx FPGA platforms.
Synchronous :: ResetKind

-- | Singleton version of <a>ActiveEdge</a>
data SActiveEdge (edge :: ActiveEdge)
[SRising] :: SActiveEdge 'Rising
[SFalling] :: SActiveEdge 'Falling

-- | Determines clock edge memory elements are sensitive to. Not yet
--   implemented.
data ActiveEdge

-- | Elements are sensitive to the rising edge (low-to-high) of the clock.
Rising :: ActiveEdge

-- | Elements are sensitive to the falling edge (high-to-low) of the clock.
Falling :: ActiveEdge

-- | Convenience value to allow easy "subclassing" of System domain. Should
--   be used in combination with <a>createDomain</a>. For example, if you
--   just want to change the period but leave all other settings intact
--   use:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
vSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of IntelSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vIntelSystem{vName="Intel10", vPeriod=10}
--   </pre>
vIntelSystem :: VDomainConfiguration

-- | Convenience value to allow easy "subclassing" of XilinxSystem domain.
--   Should be used in combination with <a>createDomain</a>. For example,
--   if you just want to change the period but leave all other settings
--   intact use:
--   
--   <pre>
--   createDomain vXilinxSystem{vName="Xilinx10", vPeriod=10}
--   </pre>
vXilinxSystem :: VDomainConfiguration

-- | Convert <a>SDomainConfiguration</a> to <a>VDomainConfiguration</a>.
--   Should be used in combination with <a>createDomain</a> only.
vDomain :: SDomainConfiguration dom conf -> VDomainConfiguration

-- | Convenience method to express new domains in terms of others.
--   
--   <pre>
--   createDomain (knownVDomain @System){vName="System10", vPeriod=10}
--   </pre>
--   
--   This duplicates the settings in the <a>System</a> domain, replaces the
--   name and period, and creates an instance for it. As most users often
--   want to update the system domain, a shortcut is available in the form:
--   
--   <pre>
--   createDomain vSystem{vName="System10", vPeriod=10}
--   </pre>
--   
--   The function will create two extra identifiers. The first:
--   
--   <pre>
--   type System10 = ..
--   </pre>
--   
--   You can use that as the dom to Clocks/Resets/Enables/Signals. For
--   example: <tt>Signal System10 Int</tt>. Additionally, it will create a
--   <a>VDomainConfiguration</a> that you can use in later calls to
--   <a>createDomain</a>:
--   
--   <pre>
--   vSystem10 = knownVDomain @System10
--   </pre>
--   
--   It will also make <tt>System10</tt> an instance of <a>KnownDomain</a>.
--   
--   If either identifier is already in scope it will not be generated a
--   second time. Note: This can be useful for example when documenting a
--   new domain:
--   
--   <pre>
--   -- | Here is some documentation for CustomDomain
--   type CustomDomain = ("CustomDomain" :: Domain)
--   
--   -- | Here is some documentation for vCustomDomain
--   createDomain vSystem{vName="CustomDomain"}
--   </pre>
createDomain :: VDomainConfiguration -> Q [Dec]

-- | We either get evidence that this function was instantiated with the
--   same domains, or Nothing.
sameDomain :: forall (domA :: Domain) (domB :: Domain). (KnownDomain domA, KnownDomain domB) => Maybe (domA :~: domB)

-- | Convert <a>Enable</a> construct to its underlying representation: a
--   signal of bools.
fromEnable :: Enable dom -> Signal dom Bool

-- | Convert a signal of bools to an <a>Enable</a> construct
toEnable :: Signal dom Bool -> Enable dom

-- | Enable generator for some domain. Is simply always True.
enableGen :: Enable dom

-- | Clock generator for simulations. Do <b>not</b> use this clock
--   generator for the <i>testBench</i> function, use <a>tbClockGen</a>
--   instead.
--   
--   To be used like:
--   
--   <pre>
--   clkSystem = clockGen @System
--   </pre>
--   
--   See <a>DomainConfiguration</a> for more information on how to use
--   synthesis domains.
clockGen :: KnownDomain dom => Clock dom

-- | Reset generator for simulation purposes. Asserts the reset for a
--   single cycle.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem = resetGen @System
--   </pre>
--   
--   See <a>tbClockGen</a> for example usage.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGen :: forall dom. KnownDomain dom => Reset dom

-- | Reset generator for simulation purposes. Asserts the reset for the
--   first <i>n</i> cycles.
--   
--   To be used like:
--   
--   <pre>
--   rstSystem5 = resetGen @System d5
--   </pre>
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (unsafeToActiveHigh (resetGenN @System d3))
--   [True,True,True,False,False,False,False]
--   </pre>
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
resetGenN :: forall dom n. (KnownDomain dom, 1 <= n) => SNat n -> Reset dom

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveHigh :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active high reset. Has no effect if reset is
--   already an active high reset. Is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToHighPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeToActiveLow :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | Convert a reset to an active low reset. Has no effect if reset is
--   already an active low reset. It is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeToActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeToLowPolarity :: forall dom. KnownDomain dom => Reset dom -> Signal dom Bool

-- | <a>unsafeFromReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeToActiveLow</a> or
--   <a>unsafeToActiveHigh</a>.
unsafeFromReset :: Reset dom -> Signal dom Bool

-- | <a>unsafeToReset</a> is unsafe. For asynchronous resets it is unsafe
--   because it can introduce combinatorial loops. In case of synchronous
--   resets it can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.
--   
--   <b>NB</b>: You probably want to use <a>unsafeFromActiveLow</a> or
--   <a>unsafeFromActiveHigh</a>.
unsafeToReset :: KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveHigh</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromHighPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active high reset and convert it to
--   a reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveHigh :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.

-- | <i>Deprecated: Use <a>unsafeFromActiveLow</a> instead. This function
--   will be removed in Clash 1.12.</i>
unsafeFromLowPolarity :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | Interpret a signal of bools as an active low reset and convert it to a
--   reset signal corresponding to the domain's setting.
--   
--   For asynchronous resets it is unsafe because it can cause
--   combinatorial loops. In case of synchronous resets it can lead to
--   <a>meta-stability</a> in the presence of asynchronous resets.
unsafeFromActiveLow :: forall dom. KnownDomain dom => Signal dom Bool -> Reset dom

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.||.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>||</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.||.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 2 .||.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&amp;&amp;.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&amp;&amp;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.&&.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 3 .&&.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>mux</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a
--   </pre>
--   
--   A multiplexer. Given "<tt><a>mux</a> b t f</tt>", output <tt>t</tt>
--   when <tt>b</tt> is <a>True</a>, and <tt>f</tt> when <tt>b</tt> is
--   <a>False</a>.
mux :: Applicative f => f Bool -> f a -> f a -> f a

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.==.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>==</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.==.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 .==.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(./=.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>/=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(./=.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 ./=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&lt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<=.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>.

-- | The above type is a generalization for:
--   
--   <pre>
--   <b>(.&gt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>=.

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList :: NFDataX a => [a] -> Signal dom a

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5] :: Signal System Int)
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromList_lazy :: [a] -> Signal dom a

-- | Calculate the period in <b>ps</b>, given a frequency in <b>Hz</b>
--   
--   I.e., to calculate the clock period for a circuit to run at 240 MHz we
--   get
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod 240e6
--   4166
--   </pre>
--   
--   If the value <tt>hzToPeriod</tt> is applied to is not of the type
--   <a>Ratio</a> <a>Natural</a>, you can use <tt>hzToPeriod
--   (<a>realToFrac</a> f)</tt>. Note that if <tt>f</tt> is negative,
--   <tt>realToFrac</tt> will give an <tt><a>Underflow</a> ::
--   <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Natural</a>. To
--   get the old behavior of this function, use a type application:
--   
--   <pre>
--   &gt;&gt;&gt; hzToPeriod @Natural 240e6
--   4166
--   </pre>
--   
--   <ul>
--   <li><b>NB</b>: This function is not synthesizable</li>
--   <li><b>NB</b>: This function is lossy. I.e., <tt>periodToHz .
--   hzToPeriod /= id</tt>.</li>
--   </ul>
hzToPeriod :: (HasCallStack, Integral a) => Ratio Natural -> a

-- | Calculate the frequency in <b>Hz</b>, given the period in <b>ps</b>
--   
--   I.e., to calculate the clock frequency of a clock with a period of
--   5000 ps:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz 5000
--   2.0e8
--   </pre>
--   
--   Note that if <tt>p</tt> in <tt>periodToHz (<a>fromIntegral</a> p)</tt>
--   is negative, <tt>fromIntegral</tt> will give an <tt><a>Underflow</a>
--   :: <a>ArithException</a></tt> without a call stack, making debugging
--   cumbersome.
--   
--   Before Clash 1.8, this function always returned a <a>Ratio</a>
--   <a>Natural</a>. To get the old behavior of this function, use a type
--   application:
--   
--   <pre>
--   &gt;&gt;&gt; periodToHz @(Ratio Natural) 5000
--   200000000 % 1
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
periodToHz :: (HasCallStack, Fractional a) => Natural -> a

-- | Get the clock period from a KnownDomain context
clockPeriod :: forall dom period. (KnownDomain dom, DomainPeriod dom ~ period) => SNat period

-- | Get <a>ActiveEdge</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case activeEdge @dom of
--       SRising -&gt; foo
--       SFalling -&gt; bar
--   </pre>
activeEdge :: forall dom edge. (KnownDomain dom, DomainActiveEdge dom ~ edge) => SActiveEdge edge

-- | Get <a>ResetKind</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetKind @dom of
--       SAsynchronous -&gt; foo
--       SSynchronous -&gt; bar
--   </pre>
resetKind :: forall dom sync. (KnownDomain dom, DomainResetKind dom ~ sync) => SResetKind sync

-- | Get <a>InitBehavior</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case initBehavior @dom of
--       SDefined -&gt; foo
--       SUnknown -&gt; bar
--   </pre>
initBehavior :: forall dom init. (KnownDomain dom, DomainInitBehavior dom ~ init) => SInitBehavior init

-- | Get <a>ResetPolarity</a> from a KnownDomain context. Example usage:
--   
--   <pre>
--   f :: forall dom . KnownDomain dom =&gt; ....
--   f a b c =
--     case resetPolarity @dom of
--       SActiveHigh -&gt; foo
--       SActiveLow -&gt; bar
--   </pre>
resetPolarity :: forall dom polarity. (KnownDomain dom, DomainResetPolarity dom ~ polarity) => SResetPolarity polarity

-- | Like 'knownDomain but yields a <a>VDomainConfiguration</a>. Should
--   only be used in combination with <a>createDomain</a>.
knownVDomain :: forall dom. KnownDomain dom => VDomainConfiguration

-- | Isomorphism between a <a>Signal</a> of a product type (e.g. a tuple)
--   and a product type of <a>Signal</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <a>Unbundled</a> clk D = <a>Signal</a> clk D
--     <a>bundle</a>   s = s
--     <a>unbundle</a> s = s
--   </pre>
--   
--   For custom product types you'll have to write the instance manually:
--   
--   <pre>
--   data Pair a b = MkPair { getA :: a, getB :: b }
--   
--   instance Bundle (Pair a b) where
--     type Unbundled dom (Pair a b) = Pair (Signal dom a) (Signal dom b)
--   
--     -- bundle :: Pair (Signal dom a) (Signal dom b) -&gt; Signal dom (Pair a b)
--     bundle   (MkPair as bs) = MkPair <a>&lt;$&gt;</a> as <a>&lt;*&gt;</a> bs
--   
--     -- unbundle :: Signal dom (Pair a b) -&gt; Pair (Signal dom a) (Signal dom b)
--     unbundle pairs = MkPair (getA <a>&lt;$&gt;</a> pairs) (getB <a>&lt;$&gt;</a> pairs)
--   </pre>
class Bundle a where {
    type family Unbundled (dom :: Domain) a = res | res -> dom a;
    type Unbundled dom a = Signal dom a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> dom a, <a>Signal</a> dom b) -&gt; <a>Signal</a> dom (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
bundle :: (Bundle a, Signal dom a ~ Unbundled dom a) => Unbundled dom a -> Signal dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: Bundle a => Signal dom a -> Unbundled dom a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom (a,b) -&gt; (<a>Signal</a> dom a, <a>Signal</a> dom b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> dom <a>Bit</a> -&gt; <a>Signal</a> dom <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, Unbundled dom a ~ Signal dom a) => Signal dom a -> Unbundled dom a

-- | Helper type to emulate the "old" behavior of Bundle's unit instance.
--   I.e., the instance for <tt>Bundle ()</tt> used to be defined as:
--   
--   <pre>
--   class Bundle () where
--     bundle   :: () -&gt; Signal dom ()
--     unbundle :: Signal dom () -&gt; ()
--   </pre>
--   
--   In order to have sensible type inference, the <a>Bundle</a> class
--   specifies that the argument type of <a>bundle</a> should uniquely
--   identify the result type, and vice versa for <a>unbundle</a>. The type
--   signatures in the snippet above don't though, as <tt>()</tt> doesn't
--   uniquely map to a specific domain. In other words, <tt>domain</tt>
--   should occur in both the argument and result of both functions.
--   
--   <a>TaggedEmptyTuple</a> tackles this by carrying the domain in its
--   type. The <a>bundle</a> and <a>unbundle</a> instance now looks like:
--   
--   <pre>
--   class Bundle EmptyTuple where
--     bundle   :: TaggedEmptyTuple dom -&gt; Signal dom EmptyTuple
--     unbundle :: Signal dom EmptyTuple -&gt; TaggedEmptyTuple dom
--   </pre>
--   
--   <tt>dom</tt> is now mentioned both the argument and result for both
--   <a>bundle</a> and <a>unbundle</a>.
data TaggedEmptyTuple (dom :: Domain)
TaggedEmptyTuple :: TaggedEmptyTuple (dom :: Domain)

-- | See <a>TaggedEmptyTuple</a>
data EmptyTuple
EmptyTuple :: EmptyTuple

-- | The <i>out</i> part of an <b>inout</b> port
--   
--   Wraps (multiple) writing signals. The semantics are such that only one
--   of the signals may write at a single time step.
--   
--   BiSignalOut has the <a>type role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalOut
--   type role BiSignalOut nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalOut (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | The <i>in</i> part of an <b>inout</b> port. BiSignalIn has the <a>type
--   role</a>
--   
--   <pre>
--   &gt;&gt;&gt; :i BiSignalIn
--   type role BiSignalIn nominal nominal nominal
--   ...
--   </pre>
--   
--   as it is not safe to coerce the default behaviour, synthesis domain or
--   width of the data in the signal.
data BiSignalIn (ds :: BiSignalDefault) (dom :: Domain) (n :: Nat)

-- | Used to specify the <i>default</i> behavior of a "BiSignal" in Haskell
--   simulation, i.e. what value is read when no value is being written to
--   it.
data BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-up resistor
PullUp :: BiSignalDefault

-- | <b>inout</b> port behaves as if connected to a pull-down resistor
PullDown :: BiSignalDefault

-- | <b>inout</b> port behaves as if is <i>floating</i>. Reading a
--   <i>floating</i> "BiSignal" value in simulation will yield an errorX
--   (undefined value).
Floating :: BiSignalDefault

-- | Read the value from an <b>inout</b> port
readFromBiSignal :: (HasCallStack, BitPack a) => BiSignalIn ds d (BitSize a) -> Signal d a

-- | Combine several <b>inout</b> signals into one.
mergeBiSignalOuts :: (HasCallStack, KnownNat n) => Vec n (BiSignalOut defaultState dom m) -> BiSignalOut defaultState dom m

-- | Write to an <b>inout</b> port
writeToBiSignal :: (HasCallStack, BitPack a, NFDataX a) => BiSignalIn ds d (BitSize a) -> Signal d (Maybe a) -> BiSignalOut ds d (BitSize a)

-- | Converts the <tt>out</tt> part of a BiSignal to an <tt>in</tt> part.
--   In simulation it checks whether multiple components are writing and
--   will error accordingly. Make sure this is only called ONCE for every
--   BiSignal.
veryUnsafeToBiSignalIn :: (HasCallStack, KnownNat n, Given (SBiSignalDefault ds)) => BiSignalOut ds d n -> BiSignalIn ds d n

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: Should only be used for simulation, and <b>not</b> for the
--   <i>testBench</i> function. For the <i>testBench</i> function, used
--   <a>tbSystemClockGen</a>
systemClockGen :: Clock System

-- | Reset generator for use in simulation, for the <a>System</a> clock
--   domain. Asserts the reset for a single cycle.
--   
--   <b>NB</b>: While this can be used in the <tt>testBench</tt> function,
--   it cannot be synthesized to hardware.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = <a>systemResetGen</a>
--   </pre>
systemResetGen :: Reset System

-- | The resetSynchronizer will synchronize an incoming reset according to
--   whether the domain is synchronous or asynchronous.
--   
--   For asynchronous resets this synchronizer ensures the reset will only
--   be de-asserted synchronously but it can still be asserted
--   asynchronously. The reset assert is immediate, but reset de-assertion
--   is delayed by two cycles.
--   
--   Normally, asynchronous resets can be both asynchronously asserted and
--   de-asserted. Asynchronous de-assertion can induce meta-stability in
--   the component which is being reset. To ensure this doesn't happen,
--   <a>resetSynchronizer</a> ensures that de-assertion of a reset happens
--   synchronously. Assertion of the reset remains asynchronous.
--   
--   Note that asynchronous assertion does not induce meta-stability in the
--   component whose reset is asserted. However, when a component "A" in
--   another clock or reset domain depends on the value of a component "B"
--   being reset, then asynchronous assertion of the reset of component "B"
--   can induce meta-stability in component "A". To prevent this from
--   happening you need to use a proper synchronizer, for example one of
--   the synchronizers in <a>Clash.Explicit.Synchronizer</a>.
--   
--   For synchronous resets this function ensures that the reset is
--   asserted and de-asserted synchronously. Both the assertion and
--   de-assertion of the reset are delayed by two cycles.
--   
--   <h3><b>Example 1</b></h3>
--   
--   The circuit below detects a rising bit (i.e., a transition from 0 to
--   1) in a given argument. It takes a reset that is not synchronized to
--   any of the other incoming signals and synchronizes it using
--   <a>resetSynchronizer</a>.
--   
--   <pre>
--   topEntity
--     :: Clock  System
--     -&gt; Reset  System
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk asyncRst key1 =
--     withClockResetEnable clk rst enableGen leds
--    where
--     rst   = <a>resetSynchronizer</a> clk asyncRst
--     key1R = isRising 1 key1
--     leds  = mealy blinkerT (1, False, 0) key1R
--   </pre>
--   
--   <h3><b>Example 2</b></h3>
--   
--   Similar to <i>Example 1</i> this circuit detects a rising bit (i.e., a
--   transition from 0 to 1) in a given argument. It takes a clock that is
--   not stable yet and a reset signal that is not synchronized to any
--   other signals. It stabilizes the clock and then synchronizes the reset
--   signal.
--   
--   Note that the function <a>altpllSync</a> provides this functionality
--   in a convenient form, obviating the need for
--   <tt>resetSynchronizer</tt> for this use case.
--   
--   <pre>
--   topEntity
--     :: Clock  System
--     -&gt; Reset  System
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk rst key1 =
--       let  (pllOut,pllStable) = unsafeAltpll clk rst
--            rstSync            = <a>resetSynchronizer</a> pllOut (unsafeFromActiveLow pllStable)
--       in   exposeClockResetEnable leds pllOut rstSync enableGen
--     where
--       key1R  = isRising 1 key1
--       leds   = mealy blinkerT (1, False, 0) key1R
--   </pre>
--   
--   <h3><b>Implementation details</b></h3>
--   
--   <a>resetSynchronizer</a> implements the following circuit for
--   asynchronous domains:
--   
--   <pre>
--                                   rst
--   --------------------------------------+
--                       |                 |
--                  +----v----+       +----v----+
--     deasserted   |         |       |         |
--   ---------------&gt;         +-------&gt;         +--------&gt;
--                  |         |       |         |
--              +---|&gt;        |   +---|&gt;        |
--              |   |         |   |   |         |
--              |   +---------+   |   +---------+
--      clk     |                 |
--   -----------------------------+
--   </pre>
--   
--   This corresponds to figure 3d at
--   <a>https://www.embedded.com/asynchronous-reset-synchronization-and-distribution-challenges-and-solutions/</a>
--   
--   For synchronous domains two sequential dflipflops are used:
--   
--   <pre>
--                  +---------+       +---------+
--     rst          |         |       |         |
--   ---------------&gt;         +-------&gt;         +--------&gt;
--                  |         |       |         |
--              +---|&gt;        |   +---|&gt;        |
--              |   |         |   |   |         |
--              |   +---------+   |   +---------+
--      clk     |                 |
--   -----------------------------+
--   </pre>
resetSynchronizer :: forall dom. KnownDomain dom => Clock dom -> Reset dom -> Reset dom

-- | Filter glitches from reset signals by only triggering a reset after it
--   has been asserted for <i>glitchlessPeriod</i> cycles. Similarly, it
--   will stay asserted until a <i>glitchlessPeriod</i> number of
--   deasserted cycles have been observed.
--   
--   This circuit can only be used on platforms supporting initial values.
--   This restriction can be worked around by using
--   <a>unsafeResetGlitchFilter</a> but this is not recommended.
--   
--   On platforms without initial values, you should instead use
--   <a>resetGlitchFilterWithReset</a> with an additional power-on reset,
--   or <a>holdReset</a> if filtering is only needed on deassertion.
--   
--   At power-on, the reset will be asserted. If the filtered reset input
--   remains unasserted, the output reset will deassert after
--   <i>glitchlessPeriod</i> clock cycles.
--   
--   If <tt>resetGlitchFilter</tt> is used in a domain with asynchronous
--   resets (<a>Asynchronous</a>), <tt>resetGlitchFilter</tt> will first
--   synchronize the reset input with <a>dualFlipFlopSynchronizer</a>.
--   
--   <h3><b>Example 1</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let sampleResetN n = sampleN n . unsafeToActiveHigh
--   
--   &gt;&gt;&gt; let resetFromList = unsafeFromActiveHigh . fromList
--   
--   &gt;&gt;&gt; let rst = resetFromList [True, True, False, False, True, False, False, True, True, False, True, True]
--   
--   &gt;&gt;&gt; sampleResetN 12 (resetGlitchFilter d2 (clockGen @XilinxSystem) rst)
--   [True,True,True,True,False,False,False,False,False,True,True,True]
--   </pre>
resetGlitchFilter :: forall dom glitchlessPeriod. (HasCallStack, HasDefinedInitialValues dom, 1 <= glitchlessPeriod) => SNat glitchlessPeriod -> Clock dom -> Reset dom -> Reset dom

-- | A <i>constraint</i> that indicates the component needs a <a>Clock</a>,
--   a <a>Reset</a>, and an <a>Enable</a> belonging to the <a>System</a>
--   domain.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type SystemClockResetEnable = (Hidden (HiddenClockName System) (Clock System), Hidden (HiddenResetName System) (Reset System), Hidden (HiddenEnableName System) (Enable System))

-- | A <i>constraint</i> that indicates the component needs a <a>Clock</a>,
--   a <a>Reset</a>, and an <a>Enable</a> belonging to the same
--   <tt>dom</tt>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenClockResetEnable dom = (HiddenClock dom, HiddenReset dom, HiddenEnable dom)

-- | A <i>constraint</i> that indicates the component needs an
--   <a>Enable</a>
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenEnable dom = (Hidden (HiddenEnableName dom) (Enable dom), KnownDomain dom)

-- | A <i>constraint</i> that indicates the component needs a <a>Reset</a>
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenReset dom = (Hidden (HiddenResetName dom) (Reset dom), KnownDomain dom)

-- | A <i>constraint</i> that indicates the component has a hidden
--   <a>Clock</a>
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
type HiddenClock dom = (Hidden (HiddenClockName dom) (Clock dom), KnownDomain dom)

-- | Expose a hidden <a>Clock</a> argument of a component, so it can be
--   applied explicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClock reg clockGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeClock</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClock @System reg clockGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
exposeClock :: forall dom r. (HiddenClock dom => r) -> KnownDomain dom => Clock dom -> r

-- | Hide the <a>Clock</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideClock :: forall dom r. HiddenClock dom => (Clock dom -> r) -> r

-- | Connect an explicit <a>Clock</a> to a function with a hidden
--   <a>Clock</a>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClock clockGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withClock</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClock @System clockGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withClock :: forall dom r. KnownDomain dom => Clock dom -> (HiddenClock dom => r) -> r

-- | Connect a hidden <a>Clock</a> to an argument where a normal
--   <a>Clock</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hasClock :: forall dom. HiddenClock dom => Clock dom

-- | Expose a hidden <a>Reset</a> argument of a component, so it can be
--   applied explicitly.
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeReset reg resetGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeReset</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeReset @System reg resetGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
exposeReset :: forall dom r. (HiddenReset dom => r) -> KnownDomain dom => Reset dom -> r

-- | Hide the <a>Reset</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideReset :: forall dom r. HiddenReset dom => (Reset dom -> r) -> r

-- | Connect an explicit <a>Reset</a> to a function with a hidden
--   <a>Reset</a>.
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withReset resetGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withReset</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withReset @System resetGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withReset :: forall dom r. KnownDomain dom => Reset dom -> (HiddenReset dom => r) -> r

-- | Connect a hidden <a>Reset</a> to an argument where a normal
--   <a>Reset</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hasReset :: forall dom. HiddenReset dom => Reset dom

-- | Expose a hidden <a>Enable</a> argument of a component, so it can be
--   applied explicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeEnable reg enableGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeEnable</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeEnable @System reg enableGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
exposeEnable :: forall dom r. (HiddenEnable dom => r) -> KnownDomain dom => Enable dom -> r

-- | Hide the <a>Enable</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideEnable :: forall dom r. HiddenEnable dom => (Enable dom -> r) -> r

-- | Connect an explicit <a>Enable</a> to a function with a hidden
--   <a>Enable</a>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withEnable enableGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withEnable</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withEnable @System enableGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withEnable :: forall dom r. KnownDomain dom => Enable dom -> (HiddenEnable dom => r) -> r

-- | Connect a hidden <a>Enable</a> to an argument where a normal
--   <a>Enable</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hasEnable :: forall dom. HiddenEnable dom => Enable dom

-- | Merge enable signal with signal of bools by applying the boolean AND
--   operation.
--   
--   <b>NB: The component given to <a>andEnable</a> as an argument needs an
--   explicit type signature.</b> Please read <a>Monomorphism restriction
--   leads to surprising behavior</a>.
--   
--   The component whose enable is modified will only be enabled when both
--   the encompassing <a>HiddenEnable</a> and the <a>Signal</a>
--   <tt>dom</tt> <a>Bool</a> are asserted.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; f en = andEnable en reg
--   
--   &gt;&gt;&gt; sampleN @System 10 (f (riseEvery d2))
--   [5,5,5,6,6,7,7,8,8,9]
--   </pre>
--   
--   Force <a>andEnable</a> to work on <a>System</a> (hence <a>sampleN</a>
--   not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; f en = andEnable @System en reg
--   
--   &gt;&gt;&gt; sampleN 10 (f (riseEvery d2))
--   [5,5,5,6,6,7,7,8,8,9]
--   </pre>
andEnable :: forall dom r. HiddenEnable dom => Signal dom Bool -> (HiddenEnable dom => r) -> r

-- | Expose hidden <a>Clock</a>, <a>Reset</a>, and <a>Enable</a> arguments
--   of a component, so they can be applied explicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClockResetEnable reg clockGen resetGen enableGen
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>exposeClockResetEnable</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = exposeClockResetEnable @System reg clockGen resetGen enableGen
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Usage in a testbench context:
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier' ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockResetEnable (expectedOutput (topEntity &lt;$&gt; testInput)) clk rst en
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = systemResetGen
--       en             = enableGen
--   </pre>
exposeClockResetEnable :: forall dom r. (HiddenClockResetEnable dom => r) -> KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> r

-- | Hide the <a>Clock</a>, <a>Reset</a>, and <a>Enable</a> arguments of a
--   component, so they can be routed implicitly.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
hideClockResetEnable :: forall dom r. HiddenClockResetEnable dom => (KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> r) -> r

-- | Connect an explicit <a>Clock</a>, <a>Reset</a>, and <a>Enable</a> to a
--   function with a hidden <a>Clock</a>, <a>Reset</a>, and <a>Enable</a>.
--   
--   <a>Click here to read more about hidden clocks, resets, and
--   enables</a>
--   
--   <h3><b>Example</b></h3>
--   
--   Usage with a <i>polymorphic</i> domain:
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClockResetEnable clockGen resetGen enableGen reg
--   
--   &gt;&gt;&gt; sampleN @System 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
--   
--   Force <a>withClockResetEnable</a> to work on <a>System</a> (hence
--   <a>sampleN</a> not needing an explicit domain later):
--   
--   <pre>
--   &gt;&gt;&gt; reg = register 5 (reg + 1)
--   
--   &gt;&gt;&gt; sig = withClockResetEnable @System clockGen resetGen enableGen reg
--   
--   &gt;&gt;&gt; sampleN 10 sig
--   [5,5,6,7,8,9,10,11,12,13]
--   </pre>
withClockResetEnable :: forall dom r. KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> (HiddenClockResetEnable dom => r) -> r

-- | Special version of <a>delay</a> that doesn't take enable signals of
--   any kind. Initial value will be undefined.
dflipflop :: forall dom a. (HiddenClock dom, NFDataX a) => Signal dom a -> Signal dom a

-- | <a>delay</a> <tt>dflt</tt> <tt>s</tt> delays the values in
--   <a>Signal</a> <tt>s</tt> for once cycle, the value at time 0 is
--   <i>dflt</i>.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 3 (delay 0 (fromList [1,2,3,4]))
--   [0,1,2]
--   </pre>
delay :: forall dom a. (NFDataX a, HiddenClock dom, HiddenEnable dom) => a -> Signal dom a -> Signal dom a

-- | Version of <a>delay</a> that only updates when its second argument is
--   a <a>Just</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; let input = fromList [Just 1, Just 2, Nothing, Nothing, Just 5, Just 6, Just (7::Int)]
--   
--   &gt;&gt;&gt; sampleN @System 7 (delayMaybe 0 input)
--   [0,1,2,2,2,5,6]
--   </pre>
delayMaybe :: forall dom a. (NFDataX a, HiddenClock dom, HiddenEnable dom) => a -> Signal dom (Maybe a) -> Signal dom a

-- | Version of <a>delay</a> that only updates when its second argument is
--   asserted.
--   
--   <pre>
--   &gt;&gt;&gt; let input = fromList [1,2,3,4,5,6,7::Int]
--   
--   &gt;&gt;&gt; let enable = fromList [True,True,False,False,True,True,True]
--   
--   &gt;&gt;&gt; sampleN @System 7 (delayEn 0 enable input)
--   [0,1,2,2,2,5,6]
--   </pre>
delayEn :: forall dom a. (NFDataX a, HiddenClock dom, HiddenEnable dom) => a -> Signal dom Bool -> Signal dom a -> Signal dom a

-- | <a>register</a> <tt>i s</tt> delays the values in <a>Signal</a>
--   <tt>s</tt> for one cycle, and sets the value at time 0 to <tt>i</tt>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 5 (register 8 (fromList [1,1,2,3,4]))
--   [8,8,1,2,3]
--   </pre>
register :: forall dom a. (HiddenClockResetEnable dom, NFDataX a) => a -> Signal dom a -> Signal dom a
infixr 3 `register`

-- | Version of <a>register</a> that only updates its content when its
--   second argument is a <a>Just</a> value. So given:
--   
--   <pre>
--   sometimes1 = s where
--     s = <a>register</a> Nothing (switch <a>&lt;$&gt;</a> s)
--   
--     switch Nothing = Just 1
--     switch _       = Nothing
--   
--   countSometimes = s where
--     s     = <a>regMaybe</a> 0 (plusM (<a>pure</a> <a>&lt;$&gt;</a> s) sometimes1)
--     plusM = <a>liftA2</a> (liftA2 (+))
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 9 sometimes1
--   [Nothing,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]
--   
--   &gt;&gt;&gt; sampleN @System 9 countSometimes
--   [0,0,0,1,1,2,2,3,3]
--   </pre>
regMaybe :: forall dom a. (HiddenClockResetEnable dom, NFDataX a) => a -> Signal dom (Maybe a) -> Signal dom a
infixr 3 `regMaybe`

-- | Version of <a>register</a> that only updates its content when its
--   second argument is asserted. So given:
--   
--   <pre>
--   oscillate = <a>register</a> False (<a>not</a> <a>&lt;$&gt;</a> oscillate)
--   count     = <a>regEn</a> 0 oscillate (count + 1)
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 9 oscillate
--   [False,False,True,False,True,False,True,False,True]
--   
--   &gt;&gt;&gt; sampleN @System 9 count
--   [0,0,0,1,1,2,2,3,3]
--   </pre>
regEn :: forall dom a. (HiddenClockResetEnable dom, NFDataX a) => a -> Signal dom Bool -> Signal dom a -> Signal dom a

-- | Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sample</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sample</a> will not drop the value
--   produced by the circuit while the reset was asserted. If you want
--   this, or if you want more than a single cycle reset, consider using
--   <a>sampleWithReset</a>.
--   
--   <b>NB</b>: This function is not synthesizable
sample :: forall dom a. (KnownDomain dom, NFDataX a) => (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Get a list of <i>n</i> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN @System 3 s == [s0, s1, s2]
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sampleN</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sampleN</a> will not drop the value
--   produced by the circuit while the reset was asserted. If you want
--   this, or if you want more than a single cycle reset, consider using
--   <a>sampleWithResetN</a>.
--   
--   <b>NB</b>: This function is not synthesizable
sampleN :: forall dom a. (KnownDomain dom, NFDataX a) => Int -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Get an infinite list of samples from a <a>Signal</a>, while asserting
--   the reset line for <i>m</i> clock cycles. <a>sampleWithReset</a> does
--   not return the first <i>m</i> cycles, i.e., when the reset is
--   asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleWithReset :: forall dom a m. (KnownDomain dom, NFDataX a, 1 <= m) => SNat m -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Get a list of <i>n</i> samples from a <a>Signal</a>, while asserting
--   the reset line for <i>m</i> clock cycles. <a>sampleWithReset</a> does
--   not return the first <i>m</i> cycles, i.e., while the reset is
--   asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleWithResetN :: forall dom a m. (KnownDomain dom, NFDataX a, 1 <= m) => SNat m -> Int -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | <i>Lazily</i> get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sample_lazy</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sample_lazy</a> will not drop the
--   value produced by the circuit while the reset was asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sample_lazy :: forall dom a. KnownDomain dom => (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Lazily get a list of <i>n</i> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN @System 3 s == [s0, s1, s2]
--   </pre>
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>sampleN_lazy</a> will supply them. The reset will be
--   asserted for a single cycle. <a>sampleN_lazy</a> will not drop the
--   value produced by the circuit while the reset was asserted.
--   
--   <b>NB</b>: This function is not synthesizable
sampleN_lazy :: forall dom a. KnownDomain dom => Int -> (HiddenClockResetEnable dom => Signal dom a) -> [a]

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System (register 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   Where <a>System</a> denotes the <i>domain</i> to simulate on. The
--   reset line is asserted for a single cycle. The first value is
--   therefore supplied twice to the circuit: once while reset is high, and
--   once directly after. The first <i>output</i> value (the value produced
--   while the reset is asserted) is dropped.
--   
--   If you only want to simulate a finite number of samples, see
--   <a>simulateN</a>. If you need the reset line to be asserted for more
--   than one cycle or if you need a custom reset value, see
--   <a>simulateWithReset</a> and <a>simulateWithResetN</a>.
--   
--   <b>NB</b>: This function is not synthesizable
simulate :: forall dom a b. (KnownDomain dom, NFDataX a, NFDataX b) => (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Same as <a>simulate</a>, but only sample the first <i>Int</i> output
--   values.
--   
--   <b>NB</b>: This function is not synthesizable
simulateN :: forall dom a b. (KnownDomain dom, NFDataX a, NFDataX b) => Int -> (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Same as <a>simulate</a>, but with the reset line asserted for <i>n</i>
--   cycles. Similar to <a>simulate</a>, <a>simulateWithReset</a> will drop
--   the output values produced while the reset is asserted. While the
--   reset is asserted, the reset value <i>a</i> is supplied to the
--   circuit.
simulateWithReset :: forall dom a b m. (KnownDomain dom, NFDataX a, NFDataX b, 1 <= m) => SNat m -> a -> (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Same as <a>simulateWithReset</a>, but only sample the first <i>Int</i>
--   output values.
simulateWithResetN :: forall dom a b m. (KnownDomain dom, NFDataX a, NFDataX b, 1 <= m) => SNat m -> a -> Int -> (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | <i>Lazily</i> simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a>
--   b</tt>) function given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulate @System (register 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulate_lazy :: forall dom a b. KnownDomain dom => (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> [a] -> [b]

-- | Simulate a (<tt><a>Unbundled</a> a -&gt; <a>Unbundled</a> b</tt>)
--   function given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System (unbundle . register (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulateB :: forall dom a b. (KnownDomain dom, Bundle a, Bundle b, NFDataX a, NFDataX b) => (HiddenClockResetEnable dom => Unbundled dom a -> Unbundled dom b) -> [a] -> [b]

-- | <i>Lazily</i> simulate a (<tt><a>Unbundled</a> a -&gt;
--   <a>Unbundled</a> b</tt>) function given a list of samples of type
--   <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB @System (unbundle . register (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
simulateB_lazy :: forall dom a b. (KnownDomain dom, Bundle a, Bundle b) => (HiddenClockResetEnable dom => Unbundled dom a -> Unbundled dom b) -> [a] -> [b]

-- | Simulate a component until it matches a condition
--   
--   If the given component has not yet been given a clock, reset, or
--   enable line, <a>runUntil</a> will supply them. The reset will be
--   asserted for a single cycle.
--   
--   It prints a message of the form
--   
--   <pre>
--   Signal sampled for N cycles until value X
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
--   
--   <h3><b>Example with test bench</b></h3>
--   
--   A common usage is with a test bench using <a>outputVerifier</a>.
--   
--   <b>NB</b>: Since this uses <a>assert</a>, when using <tt>clashi</tt>,
--   read the note at <a>Clash.Explicit.Testbench#assert-clashi</a>.
--   
--   <pre>
--   import Clash.Prelude
--   import Clash.Explicit.Testbench
--   
--   topEntity
--     :: <a>Signal</a> <a>System</a> Int
--     -&gt; <a>Signal</a> <a>System</a> Int
--   topEntity = id
--   
--   testBench
--     :: <a>Signal</a> <a>System</a> Bool
--   testBench = done
--    where
--     testInput = <a>stimuliGenerator</a> clk rst $(<a>listToVecTH</a> [1 :: Int .. 10])
--     expectedOutput =
--       <a>outputVerifier'</a> clk rst $(<a>listToVecTH</a> $ [1 :: Int .. 9] <a>&lt;&gt;</a> [42])
--     done = expectedOutput $ topEntity testInput
--     clk = <a>tbSystemClockGen</a> (not &lt;$&gt; done)
--     rst = <a>systemResetGen</a>
--   </pre>
--   
--   <pre>
--   &gt; runUntil id testBench
--   
--   
--   cycle(&lt;Clock: System&gt;): 10, outputVerifier
--   expected value: 42, not equal to actual value: 10
--   Signal sampled for 11 cycles until value True
--   </pre>
--   
--   When you need to verify multiple test benches, the following
--   invocations come in handy:
--   
--   <pre>
--   &gt; <a>mapM_</a> (runUntil id) [ testBenchA, testBenchB ]
--   </pre>
--   
--   or when the test benches are in different clock domains:
--   
--   <pre>
--   testBenchA :: Signal DomA Bool
--   testBenchB :: Signal DomB Bool
--   </pre>
--   
--   <pre>
--   &gt; <a>sequence_</a> [ runUntil id testBenchA, runUntil id testBenchB ]
--   </pre>
runUntil :: forall dom a. (KnownDomain dom, NFDataX a, ShowX a) => (a -> Bool) -> (HiddenClockResetEnable dom => Signal dom a) -> IO ()

-- | <tt>testFor n s</tt> tests the signal <i>s</i> for <i>n</i> cycles.
--   
--   <b>NB</b>: This function is not synthesizable
testFor :: KnownDomain dom => Int -> (HiddenClockResetEnable dom => Signal dom Bool) -> Property

-- | Hold reset for a number of cycles relative to an implicit reset
--   signal.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN @System 8 (unsafeToActiveHigh (holdReset (SNat @2)))
--   [True,True,True,False,False,False,False,False]
--   </pre>
--   
--   <a>holdReset</a> holds the reset for an additional 2 clock cycles for
--   a total of 3 clock cycles where the reset is asserted.
holdReset :: forall dom m. HiddenClockResetEnable dom => SNat m -> Reset dom

-- | Like <a>fromList</a>, but resets on reset and has a defined reset
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; let rst = unsafeFromActiveHigh (fromList [True, True, False, False, True, False])
--   
--   &gt;&gt;&gt; let res = withReset rst (fromListWithReset Nothing [Just 'a', Just 'b', Just 'c'])
--   
--   &gt;&gt;&gt; sampleN @System 6 res
--   [Nothing,Nothing,Just 'a',Just 'b',Nothing,Just 'a']
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
fromListWithReset :: forall dom a. (HiddenReset dom, NFDataX a) => a -> [a] -> Signal dom a

-- | Build an <a>Automaton</a> from a function over <a>Signal</a>s.
--   
--   <b>NB</b>: Consumption of continuation of the <a>Automaton</a> must be
--   affine; that is, you can only apply the continuation associated with a
--   particular element at most once.
signalAutomaton :: forall dom a b. KnownDomain dom => (HiddenClockResetEnable dom => Signal dom a -> Signal dom b) -> Automaton (->) a b

-- | Fixed size vectors.
--   
--   <ul>
--   <li>Lists with their length encoded in their type</li>
--   <li><a>Vec</a>tor elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.</li>
--   </ul>
data Vec :: Nat -> Type -> Type
[Nil] :: Vec 0 a
[Cons] :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the head of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; 3:&gt;4:&gt;5:&gt;Nil
--   3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = 3:&gt;4:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 3 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (x :&gt; y :&gt; _) = x + y
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   7
--   </pre>
--   
--   Also in conjunctions with (<a>:&lt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:>) :: a -> Vec n a -> Vec (n + 1) a

-- | Add an element to the tail of a vector.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   3 :&gt; 4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; let x = (3:&gt;4:&gt;5:&gt;Nil) :&lt; 1
--   
--   &gt;&gt;&gt; :t x
--   x :: Num a =&gt; Vec 4 a
--   </pre>
--   
--   Can be used as a pattern:
--   
--   <pre>
--   &gt;&gt;&gt; let f (_ :&lt; y :&lt; x) = y + x
--   
--   &gt;&gt;&gt; :t f
--   f :: Num a =&gt; Vec ((n + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; f (3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;Nil)
--   13
--   </pre>
--   
--   Also in conjunctions with (<a>:&gt;</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let g (a :&gt; b :&gt; (_ :&lt; y :&lt; x)) = a + b +  x + y
--   
--   &gt;&gt;&gt; :t g
--   g :: Num a =&gt; Vec ((((n + 1) + 1) + 1) + 1) a -&gt; a
--   
--   &gt;&gt;&gt; g (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   12
--   </pre>
pattern (:<) :: Vec n a -> a -> Vec (n + 1) a
infixr 5 :>
infixl 5 :<
infixr 5 `Cons`

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from left to right:
--   
--   <pre>
--   foldl f z (x1 :&gt; x2 :&gt; ... :&gt; xn :&gt; Nil) == (...((z `f` x1) `f` x2) `f`...) `f` xn
--   foldl f z Nil                            == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldl :: (b -> a -> b) -> b -> Vec n a -> b

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z (x1 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn1 `f` (xn `f` z))...)
--   foldr r z Nil                             == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldr :: (a -> b -> b) -> b -> Vec n a -> b

-- | "<a>map</a> <tt>f xs</tt>" is the vector obtained by applying <i>f</i>
--   to each element of <i>xs</i>, i.e.,
--   
--   <pre>
--   map f (x1 :&gt; x2 :&gt;  ... :&gt; xn :&gt; Nil) == (f x1 :&gt; f x2 :&gt; ... :&gt; f xn :&gt; Nil)
--   </pre>
--   
--   and corresponds to the following circuit layout:
--   
map :: (a -> b) -> Vec n a -> Vec n b

-- | Convert a <a>BitVector</a> to a <a>Vec</a> of <a>Bit</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 6 :: BitVector 8
--   
--   &gt;&gt;&gt; x
--   0b0000_0110
--   
--   &gt;&gt;&gt; bv2v x
--   0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 1 :&gt; 0 :&gt; Nil
--   </pre>
bv2v :: KnownNat n => BitVector n -> Vec n Bit

-- | To be used as the motive <i>p</i> for <a>dfold</a>, when the <i>f</i>
--   in "<a>dfold</a> <tt>p f</tt>" is a variation on (<a>:&gt;</a>), e.g.:
--   
--   <pre>
--   map' :: forall n a b . KnownNat n =&gt; (a -&gt; b) -&gt; Vec n a -&gt; Vec n b
--   map' f = <a>dfold</a> (Proxy @(<a>VCons</a> b)) (_ x xs -&gt; f x :&gt; xs)
--   </pre>
data VCons (a :: Type) (f :: TyFun Nat Type) :: Type
traverse# :: forall a f b n. Applicative f => (a -> f b) -> Vec n a -> f (Vec n b)

-- | Create a vector of one element
--   
--   <pre>
--   &gt;&gt;&gt; singleton 5
--   5 :&gt; Nil
--   </pre>
singleton :: a -> Vec 1 a

-- | Extract the first element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; head (1:&gt;2:&gt;3:&gt;Nil)
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; head Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘head’, namely ‘Nil’
--         In the expression: head Nil
--         In an equation for ‘it’: it = head Nil
--   </pre>
head :: Vec (n + 1) a -> a

-- | Extract the elements after the head of a vector
--   
--   <pre>
--   &gt;&gt;&gt; tail (1:&gt;2:&gt;3:&gt;Nil)
--   2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; tail Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘tail’, namely ‘Nil’
--         In the expression: tail Nil
--         In an equation for ‘it’: it = tail Nil
--   </pre>
tail :: Vec (n + 1) a -> Vec n a

-- | Extract the last element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; last (1:&gt;2:&gt;3:&gt;Nil)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; last Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘last’, namely ‘Nil’
--         In the expression: last Nil
--         In an equation for ‘it’: it = last Nil
--   </pre>
last :: Vec (n + 1) a -> a

-- | Extract all the elements of a vector except the last element
--   
--   <pre>
--   &gt;&gt;&gt; init (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; init Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘init’, namely ‘Nil’
--         In the expression: init Nil
--         In an equation for ‘it’: it = init Nil
--   </pre>
init :: Vec (n + 1) a -> Vec n a

-- | Shift in elements to the head of a vector, bumping out elements at the
--   tail. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; Nil,3 :&gt; 4 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (-1 :&gt; Nil,0 :&gt; 1 :&gt; Nil)
--   </pre>
shiftInAt0 :: KnownNat n => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift in element to the tail of a vector, bumping out elements at the
--   head. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; Nil)
--   (3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; Nil) (2 :&gt; 3 :&gt; Nil)
--   (3 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftInAtN :: KnownNat m => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Add an element to the head of a vector, and extract all but the last
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; 1 +&gt;&gt; Nil
--   Nil
--   </pre>
(+>>) :: KnownNat n => a -> Vec n a -> Vec n a
infixr 4 +>>

-- | Add an element to the tail of a vector, and extract all but the first
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) &lt;&lt;+ 1
--   4 :&gt; 5 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; Nil &lt;&lt;+ 1
--   Nil
--   </pre>
(<<+) :: Vec n a -> a -> Vec n a
infixl 4 <<+

-- | Shift <i>m</i> elements out from the head of a vector, filling up the
--   tail with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFrom0 d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (3 :&gt; 4 :&gt; 5 :&gt; 0 :&gt; 0 :&gt; Nil,1 :&gt; 2 :&gt; Nil)
--   </pre>
shiftOutFrom0 :: (Default a, KnownNat m) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Shift <i>m</i> elements out from the tail of a vector, filling up the
--   head with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFromN d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (0 :&gt; 0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil,4 :&gt; 5 :&gt; Nil)
--   </pre>
shiftOutFromN :: (Default a, KnownNat n) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Append two vectors.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;Nil) ++ (7:&gt;8:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 8 :&gt; Nil
--   </pre>
(++) :: Vec n a -> Vec m a -> Vec (n + m) a
infixr 5 ++

-- | Split a vector into two vectors at the given point.
--   
--   <pre>
--   &gt;&gt;&gt; splitAt (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   
--   &gt;&gt;&gt; splitAt d3 (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil,7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAt :: SNat m -> Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector into two vectors where the length of the two is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; splitAtI (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil) :: (Vec 2 Int, Vec 3 Int)
--   (1 :&gt; 2 :&gt; Nil,3 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
splitAtI :: KnownNat m => Vec (m + n) a -> (Vec m a, Vec n a)

-- | Concatenate a vector of vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concat ((1:&gt;2:&gt;3:&gt;Nil) :&gt; (4:&gt;5:&gt;6:&gt;Nil) :&gt; (7:&gt;8:&gt;9:&gt;Nil) :&gt; (10:&gt;11:&gt;12:&gt;Nil) :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil
--   </pre>
concat :: Vec n (Vec m a) -> Vec (n * m) a

-- | Map a function over all the elements of a vector and concatentate the
--   resulting vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concatMap (replicate d3) (1:&gt;2:&gt;3:&gt;Nil)
--   1 :&gt; 1 :&gt; 1 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; 3 :&gt; 3 :&gt; 3 :&gt; Nil
--   </pre>
concatMap :: (a -> Vec m b) -> Vec n a -> Vec (n * m) b

-- | Split a vector of (n * m) elements into a vector of "vectors of length
--   <i>m</i>", where the length <i>m</i> is given.
--   
--   <pre>
--   &gt;&gt;&gt; unconcat d4 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcat :: KnownNat n => SNat m -> Vec (n * m) a -> Vec n (Vec m a)

-- | Split a vector of <i>(n * m)</i> elements into a vector of "vectors of
--   length <i>m</i>", where the length <i>m</i> is determined by the
--   context.
--   
--   <pre>
--   &gt;&gt;&gt; unconcatI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil) :: Vec 2 (Vec 6 Int)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; 9 :&gt; 10 :&gt; 11 :&gt; 12 :&gt; Nil) :&gt; Nil
--   </pre>
unconcatI :: (KnownNat n, KnownNat m) => Vec (n * m) a -> Vec n (Vec m a)

-- | Merge two vectors, alternating their elements, i.e.,
--   
--   <pre>
--   &gt;&gt;&gt; merge (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   1 :&gt; 5 :&gt; 2 :&gt; 6 :&gt; 3 :&gt; 7 :&gt; 4 :&gt; 8 :&gt; Nil
--   </pre>
merge :: KnownNat n => Vec n a -> Vec n a -> Vec (2 * n) a

-- | The elements in a vector in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; reverse (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
reverse :: Vec n a -> Vec n a

-- | Apply a function of every element of a vector and its index.
--   
--   <pre>
--   &gt;&gt;&gt; :t imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Index 4)
--   
--   &gt;&gt;&gt; imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   2 :&gt; 3 :&gt; *** Exception: X: Clash.Sized.Index: result 4 is out of bounds: [0..3]
--   ...
--   
--   &gt;&gt;&gt; imap (\i a -&gt; extend (bitCoerce i) + a) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Unsigned 8)
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
imap :: forall n a b. KnownNat n => (Index n -> a -> b) -> Vec n a -> Vec n b

-- | Zip two vectors with a functions that also takes the elements'
--   indices.
--   
--   <pre>
--   &gt;&gt;&gt; izipWith (\i a b -&gt; i + a + b) (2 :&gt; 2 :&gt; Nil)  (3 :&gt; 3:&gt; Nil)
--   *** Exception: X: Clash.Sized.Index: result 3 is out of bounds: [0..1]
--   ...
--   
--   &gt;&gt;&gt; izipWith (\i a b -&gt; extend (bitCoerce i) + a + b) (2 :&gt; 2 :&gt; Nil) (3 :&gt; 3 :&gt; Nil) :: Vec 2 (Unsigned 8)
--   5 :&gt; 6 :&gt; Nil
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>izipWith</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third. This matters when <a>izipWith</a> is
--   used in a recursive setting. See <a>lazyV</a> for more information.
izipWith :: KnownNat n => (Index n -> a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | Right fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findLeftmost x xs = ifoldr (\i a b -&gt; if a == x then Just i else b) Nothing xs
--   
--   &gt;&gt;&gt; findLeftmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; findLeftmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldr :: KnownNat n => (Index n -> a -> b -> b) -> b -> Vec n a -> b

-- | Left fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findRightmost x xs = ifoldl (\a i b -&gt; if b == x then Just i else a) Nothing xs
--   
--   &gt;&gt;&gt; findRightmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 4
--   
--   &gt;&gt;&gt; findRightmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldl :: KnownNat n => (a -> Index n -> b -> a) -> a -> Vec n b -> a

-- | Generate a vector of indices.
--   
--   <pre>
--   &gt;&gt;&gt; indices d4
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indices :: KnownNat n => SNat n -> Vec n (Index n)

-- | Generate a vector of indices, where the length of the vector is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; indicesI :: Vec 4 (Index 4)
--   0 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
indicesI :: KnownNat n => Vec n (Index n)

-- | "<a>findIndex</a> <tt>p xs</tt>" returns the index of the <i>first</i>
--   element of <i>xs</i> satisfying the predicate <i>p</i>, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 3) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 3
--   
--   &gt;&gt;&gt; findIndex (&gt; 8) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
findIndex :: KnownNat n => (a -> Bool) -> Vec n a -> Maybe (Index n)

-- | "<a>elemIndex</a> <tt>a xs</tt>" returns the index of the <i>first</i>
--   element which is equal (by <a>==</a>) to the query element <i>a</i>,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndex 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; elemIndex 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
elemIndex :: (KnownNat n, Eq a) => a -> Vec n a -> Maybe (Index n)

-- | <a>zipWith</a> generalizes <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "<a>zipWith</a> <tt>(+)</tt>" applied to two vectors produces
--   the vector of corresponding sums.
--   
--   <pre>
--   zipWith f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) == (f x1 y1 :&gt; f x2 y2 :&gt; ... :&gt; f xn yn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith</a> <tt>f xs ys</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <a>zipWith</a> is <i>strict</i> in its second argument, and
--   <i>lazy</i> in its third. This matters when <a>zipWith</a> is used in
--   a recursive setting. See <a>lazyV</a> for more information.
zipWith :: (a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>zipWith3</a> generalizes <a>zip3</a> by zipping with the function
--   given as the first argument, instead of a tupling function.
--   
--   <pre>
--   zipWith3 f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) (z1 :&gt; z2 :&gt; ... :&gt; zn :&gt; Nil) == (f x1 y1 z1 :&gt; f x2 y2 z2 :&gt; ... :&gt; f xn yn zn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith3</a> <tt>f xs ys zs</tt>" corresponds to the following
--   circuit layout:
--   
--   
--   <b>NB</b>: <a>zipWith3</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third and fourth. This matters when
--   <a>zipWith3</a> is used in a recursive setting. See <a>lazyV</a> for
--   more information.
zipWith3 :: (a -> b -> c -> d) -> Vec n a -> Vec n b -> Vec n c -> Vec n d
zipWith4 :: (a -> b -> c -> d -> e) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e
zipWith5 :: (a -> b -> c -> d -> e -> f) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f
zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g
zipWith7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n h

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldr1 f (x1 :&gt; ... :&gt; xn2 :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn2 `f` (xn1 `f` xn))...)
--   foldr1 f (x1 :&gt; Nil)                            == x1
--   foldr1 f Nil                                    == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (/) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldr1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldl1 f (x1 :&gt; x2 :&gt; x3 :&gt; ... :&gt; xn :&gt; Nil) == (...((x1 `f` x2) `f` x3) `f`...) `f` xn
--   foldl1 f (x1 :&gt; Nil)                          == x1
--   foldl1 f Nil                                  == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (/) (1 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldl1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>fold</a> is a variant of <a>foldr1</a> and <a>foldl1</a>, but
--   instead of reducing from right to left, or left to right, it reduces a
--   vector using a tree-like structure. The depth, or delay, of the
--   structure produced by "<tt><a>fold</a> f xs</tt>", is hence
--   <tt>O(log_2(<a>length</a> xs))</tt>, and not <tt>O(<a>length</a>
--   xs)</tt>.
--   
--   <b>NB</b>: The binary operator "<tt>f</tt>" in "<tt><a>fold</a> f
--   xs</tt>" must be associative.
--   
--   <pre>
--   fold f (x1 :&gt; x2 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == ((x1 `f` x2) `f` ...) `f` (... `f` (xn1 `f` xn))
--   fold f (x1 :&gt; Nil)                           == x1
--   fold f Nil                                   == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fold (+) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   15
--   </pre>
--   
--   "<a>fold</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
fold :: forall n a. (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a vector of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == z :&gt; (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   0 :&gt; 5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>scanl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>last (scanl f z xs) == foldl f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanl :: (b -> a -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>scanl</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanl1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   1 :&gt; -1 :&gt; -4 :&gt; -8 :&gt; Nil
--   </pre>
scanl1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>scanr</a> with no seed value
--   
--   <pre>
--   &gt;&gt;&gt; scanr1 (-) (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   -2 :&gt; 3 :&gt; -1 :&gt; 4 :&gt; Nil
--   </pre>
scanr1 :: KnownNat n => (a -> a -> a) -> Vec (n + 1) a -> Vec (n + 1) a

-- | <a>postscanl</a> is a variant of <a>scanl</a> where the first result
--   is dropped:
--   
--   <pre>
--   postscanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   5 :&gt; 9 :&gt; 12 :&gt; 14 :&gt; Nil
--   </pre>
--   
--   "<a>postscanl</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanl :: (b -> a -> b) -> b -> Vec n a -> Vec n b

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a vector of
--   successive reduced values from the right:
--   
--   <pre>
--   scanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; z :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; 0 :&gt; Nil
--   </pre>
--   
--   "<a>scanr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <ul>
--   <li><b>NB</b>:<pre>head (scanr f z xs) == foldr f z xs</pre></li>
--   <li>For a different trade-off between circuit size and logic depth for
--   associative operators, see <a>Clash.Sized.RTree#scans</a></li>
--   </ul>
scanr :: (a -> b -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>postscanr</a> is a variant of <a>scanr</a> that where the last
--   result is dropped:
--   
--   <pre>
--   postscanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   14 :&gt; 9 :&gt; 5 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   "<a>postscanr</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanr :: (a -> b -> b) -> b -> Vec n a -> Vec n b

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumL (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,1 :&gt; 2 :&gt; 4 :&gt; 7 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumL</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumL :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumR (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,10 :&gt; 8 :&gt; 5 :&gt; 1 :&gt; Nil)
--   </pre>
--   
--   "<a>mapAccumR</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumR :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | <a>zip</a> takes two vectors and returns a vector of corresponding
--   pairs.
--   
--   <pre>
--   &gt;&gt;&gt; zip (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil)
--   (1,4) :&gt; (2,3) :&gt; (3,2) :&gt; (4,1) :&gt; Nil
--   </pre>
zip :: Vec n a -> Vec n b -> Vec n (a, b)

-- | <a>zip3</a> takes three vectors and returns a vector of corresponding
--   triplets.
--   
--   <pre>
--   &gt;&gt;&gt; zip3 (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil) (5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   (1,4,5) :&gt; (2,3,6) :&gt; (3,2,7) :&gt; (4,1,8) :&gt; Nil
--   </pre>
zip3 :: Vec n a -> Vec n b -> Vec n c -> Vec n (a, b, c)

-- | <a>zip4</a> takes four vectors and returns a list of quadruples,
--   analogous to <a>zip</a>.
zip4 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n (a, b, c, d)

-- | <a>zip5</a> takes five vectors and returns a list of five-tuples,
--   analogous to <a>zip</a>.
zip5 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n (a, b, c, d, e)

-- | <a>zip6</a> takes six vectors and returns a list of six-tuples,
--   analogous to <a>zip</a>.
zip6 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n (a, b, c, d, e, f)

-- | <a>zip7</a> takes seven vectors and returns a list of seven-tuples,
--   analogous to <a>zip</a>.
zip7 :: Vec n a -> Vec n b -> Vec n c -> Vec n d -> Vec n e -> Vec n f -> Vec n g -> Vec n (a, b, c, d, e, f, g)

-- | <a>unzip</a> transforms a vector of pairs into a vector of first
--   components and a vector of second components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip ((1,4):&gt;(2,3):&gt;(3,2):&gt;(4,1):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   </pre>
unzip :: Vec n (a, b) -> (Vec n a, Vec n b)

-- | <a>unzip3</a> transforms a vector of triplets into a vector of first
--   components, a vector of second components, and a vector of third
--   components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip3 ((1,4,5):&gt;(2,3,6):&gt;(3,2,7):&gt;(4,1,8):&gt;Nil)
--   (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil,4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil,5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   </pre>
unzip3 :: Vec n (a, b, c) -> (Vec n a, Vec n b, Vec n c)

-- | <a>unzip4</a> takes a vector of quadruples and returns four vectors,
--   analogous to <a>unzip</a>.
unzip4 :: Vec n (a, b, c, d) -> (Vec n a, Vec n b, Vec n c, Vec n d)

-- | <a>unzip5</a> takes a vector of five-tuples and returns five vectors,
--   analogous to <a>unzip</a>.
unzip5 :: Vec n (a, b, c, d, e) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e)

-- | <a>unzip6</a> takes a vector of six-tuples and returns six vectors,
--   analogous to <a>unzip</a>.
unzip6 :: Vec n (a, b, c, d, e, f) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f)

-- | <a>unzip7</a> takes a vector of seven-tuples and returns seven
--   vectors, analogous to <a>unzip</a>.
unzip7 :: Vec n (a, b, c, d, e, f, g) -> (Vec n a, Vec n b, Vec n c, Vec n d, Vec n e, Vec n f, Vec n g)

-- | "<tt>xs</tt> <a>!!</a> <tt>n</tt>" returns the <i>n</i>'th element of
--   <i>xs</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 4
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! (length (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) - 1)
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 1
--   2
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 4
--   ...
--   </pre>
(!!) :: (KnownNat n, Enum i) => Vec n a -> i -> a

-- | The length of a <a>Vec</a>tor as an <a>Int</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; length (6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   3
--   </pre>
length :: KnownNat n => Vec n a -> Int

-- | "<a>replace</a> <tt>n a xs</tt>" returns the vector <i>xs</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; replace 3 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 7 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 0 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   7 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; replace 9 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; *** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 4
--   ...
--   </pre>
replace :: (KnownNat n, Enum i) => i -> a -> Vec n a -> Vec n a

-- | "<a>take</a> <tt>n xs</tt>" returns the <i>n</i>-length prefix of
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; take (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; take d0               (1:&gt;2:&gt;Nil)
--   Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘4 + n0’ with ‘2’
--         Expected type: Vec (4 + n0) a
--           Actual type: Vec (1 + 1) a
--         The type variable ‘n0’ is ambiguous
--       • In the second argument of ‘take’, namely ‘(1 :&gt; 2 :&gt; Nil)’
--         In the expression: take d4 (1 :&gt; 2 :&gt; Nil)
--         In an equation for ‘it’: it = take d4 (1 :&gt; 2 :&gt; Nil)
--   </pre>
take :: SNat m -> Vec (m + n) a -> Vec m a

-- | "<a>takeI</a> <tt>xs</tt>" returns the prefix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; takeI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   1 :&gt; 2 :&gt; Nil
--   </pre>
takeI :: KnownNat m => Vec (m + n) a -> Vec m a

-- | "<a>drop</a> <tt>n xs</tt>" returns the suffix of <i>xs</i> after the
--   first <i>n</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; drop (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   4 :&gt; 5 :&gt; Nil
--   
--   &gt;&gt;&gt; drop d0               (1:&gt;2:&gt;Nil)
--   1 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; drop d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...: error:...
--       • Couldn't match...type ‘4 + n0...
--         The type variable ‘n0’ is ambiguous
--       • In the first argument of ‘print’, namely ‘it’
--         In a stmt of an interactive GHCi command: print it
--   </pre>
drop :: SNat m -> Vec (m + n) a -> Vec n a

-- | "<a>dropI</a> <tt>xs</tt>" returns the suffix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; dropI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   4 :&gt; 5 :&gt; Nil
--   </pre>
dropI :: KnownNat m => Vec (m + n) a -> Vec n a

-- | "<a>at</a> <tt>n xs</tt>" returns <i>n</i>'th element of <i>xs</i>
--   
--   <b>NB</b>: Vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; at (SNat :: SNat 1) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   
--   &gt;&gt;&gt; at d1               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   </pre>
at :: SNat m -> Vec (m + (n + 1)) a -> a

-- | "<a>select</a> <tt>f s n xs</tt>" selects <i>n</i> elements with
--   step-size <i>s</i> and offset <tt>f</tt> from <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; select (SNat :: SNat 1) (SNat :: SNat 2) (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; select d1 d2 d3 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   2 :&gt; 4 :&gt; 6 :&gt; Nil
--   </pre>
select :: CmpNat (i + s) (s * n) ~ 'GT => SNat f -> SNat s -> SNat n -> Vec (f + i) a -> Vec n a

-- | "<a>selectI</a> <tt>f s xs</tt>" selects as many elements as demanded
--   by the context with step-size <i>s</i> and offset <i>f</i> from
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; selectI d1 d2 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil) :: Vec 2 Int
--   2 :&gt; 4 :&gt; Nil
--   </pre>
selectI :: (CmpNat (i + s) (s * n) ~ 'GT, KnownNat n) => SNat f -> SNat s -> Vec (f + i) a -> Vec n a

-- | "<a>replicate</a> <tt>n a</tt>" returns a vector that has <i>n</i>
--   copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; replicate (SNat :: SNat 3) 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   
--   &gt;&gt;&gt; replicate d3 6
--   6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
replicate :: SNat n -> a -> Vec n a

-- | "<a>repeat</a> <tt>a</tt>" creates a vector with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; repeat 6 :: Vec 5 Int
--   6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; 6 :&gt; Nil
--   </pre>
repeat :: KnownNat n => a -> Vec n a

-- | "<a>iterate</a> <tt>n f x</tt>" returns a vector starting with
--   <i>x</i> followed by <i>n</i> repeated applications of <i>f</i> to
--   <i>x</i>.
--   
--   <pre>
--   iterate (SNat :: SNat 4) f x == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   iterate d4 f x               == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterate d4 (+1) 1
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>iterate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
iterate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>iterateI</a> <tt>f x</tt>" returns a vector starting with
--   <tt>x</tt> followed by <tt>n</tt> repeated applications of <tt>f</tt>
--   to <tt>x</tt>, where <tt>n</tt> is determined by the context.
--   
--   <pre>
--   iterateI f x :: Vec 3 a == (x :&gt; f x :&gt; f (f x) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterateI (+1) 1 :: Vec 3 Int
--   1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   "<a>iterateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
iterateI :: forall n a. KnownNat n => (a -> a) -> a -> Vec n a

-- | "<a>unfoldr</a> <tt>n f s</tt>" builds a vector of length <tt>n</tt>
--   from a seed value <tt>s</tt>, where every element <tt>a</tt> is
--   created by successive calls of <tt>f</tt> on <tt>s</tt>. Unlike
--   <a>unfoldr</a> from <a>Data.List</a> the generating function
--   <tt>f</tt> cannot dictate the length of the resulting vector, it must
--   be statically known.
--   
--   a simple use of <a>unfoldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr d10 (\s -&gt; (s,s-1)) 10
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldr :: SNat n -> (s -> (a, s)) -> s -> Vec n a

-- | "<a>unfoldrI</a> <tt>f s</tt>" builds a vector from a seed value
--   <tt>s</tt>, where every element <tt>a</tt> is created by successive
--   calls of <tt>f</tt> on <tt>s</tt>; the length of the vector is
--   inferred from the context. Unlike <a>unfoldr</a> from <a>Data.List</a>
--   the generating function <tt>f</tt> cannot dictate the length of the
--   resulting vector, it must be statically known.
--   
--   a simple use of <a>unfoldrI</a>:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldrI (\s -&gt; (s,s-1)) 10 :: Vec 10 Int
--   10 :&gt; 9 :&gt; 8 :&gt; 7 :&gt; 6 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil
--   </pre>
unfoldrI :: KnownNat n => (s -> (a, s)) -> s -> Vec n a

-- | "<a>generate</a> <tt>n f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>.
--   
--   <pre>
--   generate (SNat :: SNat 4) f x == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   generate d4 f x               == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generate d4 (+1) 1
--   2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
--   
--   "<a>generate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
generate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>generateI</a> <tt>f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>, where <tt>n</tt> is
--   determined by the context.
--   
--   <pre>
--   generateI f x :: Vec 3 a == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generateI (+1) 1 :: Vec 3 Int
--   2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   "<a>generateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
generateI :: KnownNat n => (a -> a) -> a -> Vec n a

-- | Transpose a matrix: go from row-major to column-major
--   
--   <pre>
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;Nil):&gt;(3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; transpose xss
--   (1 :&gt; 3 :&gt; 5 :&gt; Nil) :&gt; (2 :&gt; 4 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
transpose :: KnownNat n => Vec m (Vec n a) -> Vec n (Vec m a)

-- | 1-dimensional stencil computations
--   
--   "<a>stencil1d</a> <tt>stX f xs</tt>", where <i>xs</i> has <i>stX +
--   n</i> elements, applies the stencil computation <i>f</i> on: <i>n +
--   1</i> overlapping (1D) windows of length <i>stX</i>, drawn from
--   <i>xs</i>. The resulting vector has <i>n + 1</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t stencil1d d2 sum xs
--   stencil1d d2 sum xs :: Num b =&gt; Vec 5 b
--   
--   &gt;&gt;&gt; stencil1d d2 sum xs
--   3 :&gt; 5 :&gt; 7 :&gt; 9 :&gt; 11 :&gt; Nil
--   </pre>
stencil1d :: KnownNat n => SNat (stX + 1) -> (Vec (stX + 1) a -> b) -> Vec ((stX + n) + 1) a -> Vec (n + 1) b

-- | 2-dimensional stencil computations
--   
--   "<a>stencil2d</a> <tt>stY stX f xss</tt>", where <i>xss</i> is a
--   matrix of <i>stY + m</i> rows of <i>stX + n</i> elements, applies the
--   stencil computation <i>f</i> on: <i>(m + 1) * (n + 1)</i> overlapping
--   (2D) windows of <i>stY</i> rows of <i>stX</i> elements, drawn from
--   <i>xss</i>. The result matrix has <i>m + 1</i> rows of <i>n + 1</i>
--   elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t stencil2d d2 d2 (sum . map sum) xss
--   stencil2d d2 d2 (sum . map sum) xss :: Num b =&gt; Vec 3 (Vec 3 b)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stencil2d d2 d2 (sum . map sum) xss
--   (14 :&gt; 18 :&gt; 22 :&gt; Nil) :&gt; (30 :&gt; 34 :&gt; 38 :&gt; Nil) :&gt; (46 :&gt; 50 :&gt; 54 :&gt; Nil) :&gt; Nil
--   </pre>
stencil2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> (Vec (stY + 1) (Vec (stX + 1) a) -> b) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) b)

-- | "<a>windows1d</a> <tt>stX xs</tt>", where the vector <i>xs</i> has
--   <i>stX + n</i> elements, returns a vector of <i>n + 1</i> overlapping
--   (1D) windows of <i>xs</i> of length <i>stX</i>.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t windows1d d2 xs
--   windows1d d2 xs :: Num a =&gt; Vec 5 (Vec 2 a)
--   
--   &gt;&gt;&gt; windows1d d2 xs
--   (1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 4 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil
--   </pre>
windows1d :: KnownNat n => SNat (stX + 1) -> Vec ((stX + n) + 1) a -> Vec (n + 1) (Vec (stX + 1) a)

-- | "<a>windows2d</a> <tt>stY stX xss</tt>", where matrix <i>xss</i> has
--   <i>stY + m</i> rows of <i>stX + n</i>, returns a matrix of <i>m+1</i>
--   rows of <i>n+1</i> elements. The elements of this new matrix are the
--   overlapping (2D) windows of <i>xss</i>, where every window has
--   <i>stY</i> rows of <i>stX</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   
--   &gt;&gt;&gt; :t windows2d d2 d2 xss
--   windows2d d2 d2 xss :: Num a =&gt; Vec 3 (Vec 3 (Vec 2 (Vec 2 a)))
--   
--   &gt;&gt;&gt; windows2d d2 d2 xss
--   (((1 :&gt; 2 :&gt; Nil) :&gt; (5 :&gt; 6 :&gt; Nil) :&gt; Nil) :&gt; ((2 :&gt; 3 :&gt; Nil) :&gt; (6 :&gt; 7 :&gt; Nil) :&gt; Nil) :&gt; ((3 :&gt; 4 :&gt; Nil) :&gt; (7 :&gt; 8 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((5 :&gt; 6 :&gt; Nil) :&gt; (9 :&gt; 10 :&gt; Nil) :&gt; Nil) :&gt; ((6 :&gt; 7 :&gt; Nil) :&gt; (10 :&gt; 11 :&gt; Nil) :&gt; Nil) :&gt; ((7 :&gt; 8 :&gt; Nil) :&gt; (11 :&gt; 12 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; (((9 :&gt; 10 :&gt; Nil) :&gt; (13 :&gt; 14 :&gt; Nil) :&gt; Nil) :&gt; ((10 :&gt; 11 :&gt; Nil) :&gt; (14 :&gt; 15 :&gt; Nil) :&gt; Nil) :&gt; ((11 :&gt; 12 :&gt; Nil) :&gt; (15 :&gt; 16 :&gt; Nil) :&gt; Nil) :&gt; Nil) :&gt; Nil
--   </pre>
windows2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) (Vec (stY + 1) (Vec (stX + 1) a)))

-- | Forward permutation specified by an index mapping, <i>ix</i>. The
--   result vector is initialized by the given defaults, <i>def</i>, and an
--   further values that are permuted into the result are added to the
--   current value using the given combination function, <i>f</i>.
--   
--   The combination function must be <i>associative</i> and
--   <i>commutative</i>.
permute :: (Enum i, KnownNat n, KnownNat m) => (a -> a -> a) -> Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>backpermute</a> <tt>xs is</tt>" is equivalent to "<a>map</a>
--   <tt>(xs <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; backpermute input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
backpermute :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | Copy elements from the source vector, <i>xs</i>, to the destination
--   vector according to an index mapping <i>is</i>. This is a forward
--   permute operation where a <i>to</i> vector encodes an input to output
--   index mapping. Output elements for indices that are not mapped assume
--   the value in the default vector <i>def</i>.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let defVec = 0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;Nil
--   
--   &gt;&gt;&gt; let to = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;8:&gt;Nil
--   
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; scatter defVec to input
--   0 :&gt; 1 :&gt; 4 :&gt; 9 :&gt; 0 :&gt; 4 :&gt; 0 :&gt; 6 :&gt; 2 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: If the same index appears in the index mapping more than
--   once, the latest mapping is chosen.
scatter :: (Enum i, KnownNat n, KnownNat m) => Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>gather</a> <tt>xs is</tt>" is equivalent to "<a>map</a> <tt>(xs
--   <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; gather input from
--   9 :&gt; 4 :&gt; 1 :&gt; 6 :&gt; 2 :&gt; 4 :&gt; Nil
--   </pre>
gather :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | "<a>interleave</a> <tt>d xs</tt>" creates a vector:
--   
--   <pre>
--   &lt;x_0,x_d,x_(2d),...,x_1,x_(d+1),x_(2d+1),...,x_(d-1),x_(2d-1),x_(3d-1)&gt;
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; Nil
--   
--   &gt;&gt;&gt; interleave d3 xs
--   1 :&gt; 4 :&gt; 7 :&gt; 2 :&gt; 5 :&gt; 8 :&gt; 3 :&gt; 6 :&gt; 9 :&gt; Nil
--   </pre>
interleave :: (KnownNat n, KnownNat d) => SNat d -> Vec (n * d) a -> Vec (d * n) a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs (-1)
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeftS</a> if you want to rotate left by a
--   <i>static</i> amount.
rotateLeft :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 2
--   3 :&gt; 4 :&gt; 1 :&gt; 2 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs (-1)
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRightS</a> if you want to rotate right by a
--   <i>static</i> amount.
rotateRight :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeftS xs d1
--   2 :&gt; 3 :&gt; 4 :&gt; 1 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateLeft</a> if you want to rotate left by a
--   <i>dynamic</i> amount.
rotateLeftS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRightS xs d1
--   4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: Use <a>rotateRight</a> if you want to rotate right by a
--   <i>dynamic</i> amount.
rotateRightS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | Convert a vector to a list.
--   
--   <pre>
--   &gt;&gt;&gt; toList (1:&gt;2:&gt;3:&gt;Nil)
--   [1,2,3]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesizable
toList :: Vec n a -> [a]

-- | Create a vector literal from a list literal.
--   
--   <pre>
--   $(listToVecTH [1::Signed 8,2,3,4,5]) == (8:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 5 (Signed 8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1 :: Signed 8,2,3,4,5]
--   [1,2,3,4,5]
--   
--   &gt;&gt;&gt; $(listToVecTH [1::Signed 8,2,3,4,5])
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil
--   </pre>
listToVecTH :: Lift a => [a] -> ExpQ

-- | <a>Vec</a>tor as a <a>Proxy</a> for <a>Nat</a>
asNatProxy :: Vec n a -> Proxy n

-- | Length of a <a>Vec</a>tor as an <a>SNat</a> value
lengthS :: KnownNat n => Vec n a -> SNat n

-- | What you should use when your vector functions are too strict in their
--   arguments.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwapL a b = if a &lt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; :{
--   let sortVL :: (Ord a, KnownNat (n + 1)) =&gt; Vec ((n + 1) + 1) a -&gt; Vec ((n + 1) + 1) a
--       sortVL xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith compareSwapL (lazyV lefts) rights
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let sortV_flip xs = map fst sorted :&lt; (snd (last sorted))
--         where
--           lefts  = head xs :&gt; map snd (init sorted)
--           rights = tail xs
--           sorted = zipWith (flip compareSwapL) rights lefts
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   For example:
--   
--   <pre>
--   -- Bubble sort for 1 iteration
--   sortV xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL lefts rights
--   
--   -- Compare and swap
--   compareSwapL a b = if a &lt; b then (a,b)
--                               else (b,a)
--   </pre>
--   
--   Will not terminate because <a>zipWith</a> is too strict in its second
--   argument.
--   
--   In this case, adding <a>lazyV</a> on <a>zipWith</a>s second argument:
--   
--   <pre>
--   sortVL xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; map snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL (<a>lazyV</a> lefts) rights
--   </pre>
--   
--   Results in a successful computation:
--   
--   <pre>
--   &gt;&gt;&gt; sortVL (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: There is also a solution using <a>flip</a>, but it slightly
--   obfuscates the meaning of the code:
--   
--   <pre>
--   sortV_flip xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> (<a>flip</a> compareSwapL) rights lefts
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sortV_flip (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
lazyV :: KnownNat n => Vec n a -> Vec n a

-- | A <i>dependently</i> typed fold.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -fplugin GHC.TypeLits.Normalise
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data Append (m :: Nat) (a :: Type) (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply (Append m a) l = Vec (l + m) a
--   
--   &gt;&gt;&gt; let append' xs ys = dfold (Proxy :: Proxy (Append m a)) (const (:&gt;)) ys xs
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   Using lists, we can define <i>append</i> (a.k.a.
--   <tt>Data.List.</tt><a>++</a>) in terms of
--   <tt>Data.List.</tt><a>foldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List
--   
--   &gt;&gt;&gt; let append xs ys = Data.List.foldr (:) ys xs
--   
--   &gt;&gt;&gt; append [1,2] [3,4]
--   [1,2,3,4]
--   </pre>
--   
--   However, when we try to do the same for <a>Vec</a>, by defining
--   <i>append'</i> in terms of <tt>Clash.Sized.Vector.</tt><a>foldr</a>:
--   
--   <pre>
--   append' xs ys = <a>foldr</a> (:&gt;) ys xs
--   </pre>
--   
--   we get a type error:
--   
--   <pre>
--   <b>&gt;&gt;&gt; let append' xs ys = foldr (:&gt;) ys xs</b>
--   
--   &lt;interactive&gt;:...
--       • Occurs check: cannot construct the infinite type: ... ~ ... + 1
--         Expected type: a -&gt; Vec ... a -&gt; Vec ... a
--           Actual type: a -&gt; Vec ... a -&gt; Vec (... + 1) a
--       • In the first argument of ‘foldr’, namely ‘(:&gt;)’
--         In the expression: foldr (:&gt;) ys xs
--         In an equation for ‘append'’: append' xs ys = foldr (:&gt;) ys xs
--       • Relevant bindings include
--           ys :: Vec ... a (bound at ...)
--           append' :: Vec n a -&gt; Vec ... a -&gt; Vec ... a
--             (bound at ...)
--   </pre>
--   
--   The reason is that the type of <a>foldr</a> is:
--   
--   <pre>
--   &gt;&gt;&gt; :t foldr
--   foldr :: (a -&gt; b -&gt; b) -&gt; b -&gt; Vec n a -&gt; b
--   </pre>
--   
--   While the type of (<a>:&gt;</a>) is:
--   
--   <pre>
--   &gt;&gt;&gt; :t (:&gt;)
--   (:&gt;) :: a -&gt; Vec n a -&gt; Vec (n + 1) a
--   </pre>
--   
--   We thus need a <tt>fold</tt> function that can handle the growing
--   vector type: <a>dfold</a>. Compared to <a>foldr</a>, <a>dfold</a>
--   takes an extra parameter, called the <i>motive</i>, that allows the
--   folded function to have an argument and result type that
--   <i>depends</i> on the current length of the vector. Using
--   <a>dfold</a>, we can now correctly define <i>append'</i>:
--   
--   <pre>
--   import Data.Singletons
--   import Data.Proxy
--   
--   data Append (m :: Nat) (a :: Type) (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> (Append m a) l = <a>Vec</a> (l + m) a
--   
--   append' xs ys = <a>dfold</a> (Proxy :: Proxy (Append m a)) (const (<a>:&gt;</a>)) ys xs
--   </pre>
--   
--   We now see that <i>append'</i> has the appropriate type:
--   
--   <pre>
--   &gt;&gt;&gt; :t append'
--   append' :: KnownNat k =&gt; Vec k a -&gt; Vec m a -&gt; Vec (k + m) a
--   </pre>
--   
--   And that it works:
--   
--   <pre>
--   &gt;&gt;&gt; append' (1 :&gt; 2 :&gt; Nil) (3 :&gt; 4 :&gt; Nil)
--   1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   </pre>
--   
--   <b>NB</b>: "<tt><a>dfold</a> m f z xs</tt>" creates a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Look at <a>dtfold</a> for a <i>dependently</i> typed fold
--   that produces a structure with a depth of O(log_2(<tt><a>length</a>
--   xs</tt>)).
dfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (forall l. SNat l -> a -> (p @@ l) -> p @@ (l + 1)) -> (p @@ 0) -> Vec k a -> p @@ k

-- | A combination of <a>dfold</a> and <a>fold</a>: a <i>dependently</i>
--   typed fold that reduces a vector in a tree-like structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XUndecidableInstances
--   
--   &gt;&gt;&gt; import Data.Singletons (Apply, Proxy (..), TyFun)
--   
--   &gt;&gt;&gt; data IIndex (f :: TyFun Nat Type) :: Type
--   
--   &gt;&gt;&gt; type instance Apply IIndex l = Index ((2^l)+1)
--   
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat k, KnownNat (2^k)) =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--       populationCount' bv = dtfold (Proxy @IIndex)
--                                    fromIntegral
--                                    (\_ x y -&gt; add x y)
--                                    (bv2v bv)
--   :}
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <a>BitVector</a>. Given a vector of <i>n</i> bits, we
--   only need we need a data type that can represent the number <i>n</i>:
--   <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a range of
--   <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits), hence we need
--   <a>Index</a> <tt>n+1</tt>. As an initial attempt we will use
--   <a>sum</a>, because it gives a nice (<tt>log2(n)</tt>) tree-structure
--   of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (n+1), KnownNat (n+2))
--                   =&gt; <a>BitVector</a> (n+1) -&gt; <a>Index</a> (n+2)
--   populationCount = sum . map fromIntegral . <a>bv2v</a>
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>add</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <a>fold</a> to create a tree-structure
--   of <a>add</a>es:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (n+1), KnownNat (n+2))
--                        =&gt; BitVector (n+1) -&gt; Index (n+2)
--       populationCount' = fold add . map fromIntegral . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘((n + 2) + (n + 2)) - 1’ with ‘n + 2’
--         Expected type: Index (n + 2) -&gt; Index (n + 2) -&gt; Index (n + 2)
--           Actual type: Index (n + 2)
--                        -&gt; Index (n + 2) -&gt; AResult (Index (n + 2)) (Index (n + 2))
--       • In the first argument of ‘fold’, namely ‘add’
--         In the first argument of ‘(.)’, namely ‘fold add’
--         In the expression: fold add . map fromIntegral . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (n + 1) -&gt; Index (n + 2)
--             (bound at ...)
--   </pre>
--   
--   because <a>fold</a> expects a function of type "<tt>a -&gt; a -&gt;
--   a</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>add</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons
--   import Data.Proxy
--   
--   data IIndex (f :: <a>TyFun</a> Nat Type) :: Type
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>dtfold</a> (Proxy @IIndex)
--                                fromIntegral
--                                (\_ x y -&gt; <a>add</a> x y)
--                                (<a>bv2v</a> bv)
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
--   
--   Some final remarks:
--   
--   <ul>
--   <li>By using <a>dtfold</a> instead of <a>fold</a>, we had to restrict
--   our <a>BitVector</a> argument to have bit-width that is a power of
--   2.</li>
--   <li>Even though our original <i>populationCount</i> function specified
--   a structure where all adders had the same width. Most
--   VHDL/(System)Verilog synthesis tools will create a more efficient
--   circuit, i.e. one where the adders have an increasing bit-width for
--   every layer, from the VHDL/(System)Verilog produced by the Clash
--   compiler.</li>
--   </ul>
--   
--   <b>NB</b>: The depth, or delay, of the structure produced by
--   "<tt><a>dtfold</a> m f g xs</tt>" is O(log_2(<tt><a>length</a>
--   xs</tt>)).
dtfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat Type -> Type) -> (a -> p @@ 0) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> p @@ (l + 1)) -> Vec (2 ^ k) a -> p @@ k

-- | Specialised version of <a>dfold</a> that builds a triangular
--   computational structure.
--   
--   <h3><b>doctests setup</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; let compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   
--   &gt;&gt;&gt; let insert y xs = let (y',xs') = mapAccumL compareSwap y xs in xs' :&lt; y'
--   
--   &gt;&gt;&gt; let insertionSort = vfold (const insert)
--   </pre>
--   
--   <h3>Example usage</h3>
--   
--   <pre>
--   compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   insert y xs     = let (y',xs') = <a>mapAccumL</a> compareSwap y xs in xs' <a>:&lt;</a> y'
--   insertionSort   = <a>vfold</a> (const insert)
--   </pre>
--   
--   Builds a triangular structure of compare and swaps to sort a row.
--   
--   <pre>
--   &gt;&gt;&gt; insertionSort (7 :&gt; 3 :&gt; 9 :&gt; 1 :&gt; Nil)
--   1 :&gt; 3 :&gt; 7 :&gt; 9 :&gt; Nil
--   </pre>
--   
--   The circuit layout of <tt>insertionSort</tt>, build using
--   <a>vfold</a>, is:
--   
vfold :: forall k a b. KnownNat k => (forall l. SNat l -> a -> Vec l b -> Vec (l + 1) b) -> Vec k a -> Vec k b

-- | The largest element of a non-empty vector
maximum :: Ord a => Vec (n + 1) a -> a

-- | The least element of a non-empty vector
minimum :: Ord a => Vec (n + 1) a -> a

-- | Apply a function to every element of a vector and the element's
--   position (as an <a>SNat</a> value) in the vector.
--   
--   <pre>
--   &gt;&gt;&gt; let rotateMatrix = smap (flip rotateRightS)
--   
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; Nil
--   
--   &gt;&gt;&gt; rotateMatrix xss
--   (1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (3 :&gt; 1 :&gt; 2 :&gt; Nil) :&gt; (2 :&gt; 3 :&gt; 1 :&gt; Nil) :&gt; Nil
--   </pre>
smap :: forall k a b. KnownNat k => (forall l. SNat l -> a -> b) -> Vec k a -> Vec k b
concatBitVector# :: forall n m. (KnownNat n, KnownNat m) => Vec n (BitVector m) -> BitVector (n * m)
unconcatBitVector# :: forall n m. (KnownNat n, KnownNat m) => BitVector (n * m) -> Vec n (BitVector m)

-- | Convert a <a>Vec</a> of <a>Bit</a>s to a <a>BitVector</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let x = (0:&gt;0:&gt;0:&gt;1:&gt;0:&gt;0:&gt;1:&gt;0:&gt;Nil) :: Vec 8 Bit
--   
--   &gt;&gt;&gt; x
--   0 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; 0 :&gt; 1 :&gt; 0 :&gt; Nil
--   
--   &gt;&gt;&gt; v2bv x
--   0b0001_0010
--   </pre>
v2bv :: KnownNat n => Vec n Bit -> BitVector n

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument
seqV :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqV`

-- | Evaluate all elements of a vector to WHNF
forceV :: KnownNat n => Vec n a -> Vec n a

-- | Evaluate all elements of a vector to WHNF, returning the second
--   argument. Does not propagate <a>XException</a>s.
seqVX :: KnownNat n => Vec n a -> b -> b
infixr 0 `seqVX`

-- | Evaluate all elements of a vector to WHNF. Does not propagate
--   <a>XException</a>s.
forceVX :: KnownNat n => Vec n a -> Vec n a

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <a>id</a>
--   <a>to</a> . <a>from</a> ≡ <a>id</a>
--   </pre>
class Generic a

-- | Representable types of kind <tt>* -&gt; *</tt> (or kind <tt>k -&gt;
--   *</tt>, when <tt>PolyKinds</tt> is enabled). This class is derivable
--   in GHC with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic1</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from1</a> . <a>to1</a> ≡ <a>id</a>
--   <a>to1</a> . <a>from1</a> ≡ <a>id</a>
--   </pre>
class Generic1 (f :: k -> Type)

-- | A <a>Lift</a> instance can have any of its values turned into a
--   Template Haskell expression. This is needed when a value used within a
--   Template Haskell quotation is bound outside the Oxford brackets
--   (<tt>[| ... |]</tt> or <tt>[|| ... ||]</tt>) but not at the top level.
--   As an example:
--   
--   <pre>
--   add1 :: Int -&gt; Q (TExp Int)
--   add1 x = [|| x + 1 ||]
--   </pre>
--   
--   Template Haskell has no way of knowing what value <tt>x</tt> will take
--   on at splice-time, so it requires the type of <tt>x</tt> to be an
--   instance of <a>Lift</a>.
--   
--   A <a>Lift</a> instance must satisfy <tt>$(lift x) ≡ x</tt> and
--   <tt>$$(liftTyped x) ≡ x</tt> for all <tt>x</tt>, where <tt>$(...)</tt>
--   and <tt>$$(...)</tt> are Template Haskell splices. It is additionally
--   expected that <tt><a>lift</a> x ≡ <a>unTypeQ</a> (<a>liftTyped</a>
--   x)</tt>.
--   
--   <a>Lift</a> instances can be derived automatically by use of the
--   <tt>-XDeriveLift</tt> GHC language extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveLift #-}
--   module Foo where
--   
--   import Language.Haskell.TH.Syntax
--   
--   data Bar a = Bar1 a (Bar a) | Bar2 String
--     deriving Lift
--   </pre>
--   
--   Levity-polymorphic since <i>template-haskell-2.16.0.0</i>.
class Lift (t :: TYPE r)

-- | Turn a value into a Template Haskell expression, suitable for use in a
--   splice.
lift :: Lift t => t -> Q Exp

-- | Turn a value into a Template Haskell typed expression, suitable for
--   use in a typed splice.
liftTyped :: Lift t => t -> Q (TExp t)

-- | <a>autoReg</a> is a "smart" version of <a>register</a>. It does two
--   things:
--   
--   <ol>
--   <li>It splits product types over their fields. For example, given a
--   3-tuple, the corresponding HDL will end up with three instances of a
--   register (or more if the three fields can be split up similarly).</li>
--   <li>Given a data type where a constructor indicates (parts) of the
--   data will (not) be updated a given cycle, it will split the data in
--   two parts. The first part will contain the "always interesting" parts
--   (the constructor bits). The second holds the "potentially
--   uninteresting" data (the rest). Both parts will be stored in separate
--   registers. The register holding the "potentially uninteresting" part
--   will only be enabled if the constructor bits indicate they're
--   interesting.</li>
--   </ol>
--   
--   The most important example of this is <a>Maybe</a>. Consider <tt>Maybe
--   (Signed 16)</tt>; when viewed as bits, a <a>Nothing</a> would look
--   like:
--   
--   <pre>
--   &gt;&gt;&gt; pack @(Maybe (Signed 16)) Nothing
--   0b0_...._...._...._....
--   </pre>
--   
--   and <a>Just</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack @(Maybe (Signed 16)) (Just 3)
--   0b1_0000_0000_0000_0011
--   </pre>
--   
--   In the first case, Nothing, we don't particularly care about updating
--   the register holding the <tt>Signed 16</tt> field, as they'll be
--   unknown anyway. We can therefore deassert its enable line.
--   
--   Making Clash lay it out like this increases the chances of synthesis
--   tools clock gating the registers, saving energy.
--   
--   This version of <a>autoReg</a> will split the given data type up
--   recursively. For example, given <tt>a :: Maybe (Maybe Int, Maybe
--   Int)</tt>, a total of five registers will be rendered. Both the
--   "interesting" and "uninteresting" enable lines of the inner Maybe
--   types will be controlled by the outer one, in addition to the inner
--   parts controlling their "uninteresting" parts as described in (2).
--   
--   The default implementation is just <a>register</a>. If you don't need
--   or want the special features of <a>AutoReg</a>, you can use that by
--   writing an empty instance.
--   
--   <pre>
--   data MyDataType = ...
--   instance AutoReg MyDataType
--   </pre>
--   
--   If you have a product type you can use <a>deriveAutoReg</a> to derive
--   an instance.
class NFDataX a => AutoReg a

-- | Implicit version of <a>autoReg</a>
autoReg :: (HasCallStack, HiddenClockResetEnable dom, AutoReg a) => a -> Signal dom a -> Signal dom a

-- | Automatically derives an <a>AutoReg</a> instance for a product type
--   
--   Usage:
--   
--   <pre>
--   data Pair a b = MkPair { getA :: a, getB :: b } deriving (Generic, NFDataX)
--   data Tup3 a b c = MkTup3 { getAB :: Pair a b, getC :: c } deriving (Generic, NFDataX)
--   deriveAutoReg ''Pair
--   deriveAutoReg ''Tup3
--   </pre>
--   
--   <b>NB</b>: Because of the way template haskell works the order here
--   matters, if you try to <tt>deriveAutoReg ''Tup3</tt> before
--   <tt>Pair</tt> it will complain about missing an <tt>instance AutoReg
--   (Pair a b)</tt>.
deriveAutoReg :: Name -> DecsQ

-- | The kind of types with lifted values. For example <tt>Int ::
--   Type</tt>.
type Type = Type

-- | The kind of constraints, like <tt>Show a</tt>
data Constraint


module Clash.Tutorial


module Clash.Examples.Internal
decoderCase :: Bool -> BitVector 4 -> BitVector 16
decoderShift :: Bool -> BitVector 4 -> BitVector 16
encoderCase :: Bool -> BitVector 16 -> BitVector 4
upCounter :: HiddenClockResetEnable dom => Signal dom Bool -> Signal dom (Unsigned 8)
upCounterLdT :: Num a => a -> (Bool, Bool, a) -> (a, a)
upCounterLd :: HiddenClockResetEnable dom => Signal dom (Bool, Bool, Unsigned 8) -> Signal dom (Unsigned 8)
upDownCounter :: HiddenClockResetEnable dom => Signal dom Bool -> Signal dom (Unsigned 8)
lfsrF' :: BitVector 16 -> BitVector 16
lfsrF :: HiddenClockResetEnable dom => BitVector 16 -> Signal dom Bit
lfsrGP :: (KnownNat (n + 1), Bits a) => Vec (n + 1) Bool -> Vec (n + 1) a -> Vec (n + 1) a
lfsrG :: HiddenClockResetEnable dom => BitVector 16 -> Signal dom Bit
grayCounter :: HiddenClockResetEnable dom => Signal dom Bool -> Signal dom (BitVector 8)
oneHotCounter :: HiddenClockResetEnable dom => Signal dom Bool -> Signal dom (BitVector 8)
crcT :: (Bits a, BitPack a) => a -> Bit -> a
crc :: HiddenClockResetEnable dom => Signal dom Bool -> Signal dom Bool -> Signal dom Bit -> Signal dom (BitVector 16)
data RxReg
RxReg :: BitVector 8 -> BitVector 8 -> Unsigned 4 -> Unsigned 4 -> Bool -> Bool -> Bool -> Bit -> Bit -> Bool -> RxReg
[_rx_reg] :: RxReg -> BitVector 8
[_rx_data] :: RxReg -> BitVector 8
[_rx_sample_cnt] :: RxReg -> Unsigned 4
[_rx_cnt] :: RxReg -> Unsigned 4
[_rx_frame_err] :: RxReg -> Bool
[_rx_over_run] :: RxReg -> Bool
[_rx_empty] :: RxReg -> Bool
[_rx_d1] :: RxReg -> Bit
[_rx_d2] :: RxReg -> Bit
[_rx_busy] :: RxReg -> Bool
rx_sample_cnt :: Lens' RxReg (Unsigned 4)
rx_reg :: Lens' RxReg (BitVector 8)
rx_over_run :: Lens' RxReg Bool
rx_frame_err :: Lens' RxReg Bool
rx_empty :: Lens' RxReg Bool
rx_data :: Lens' RxReg (BitVector 8)
rx_d2 :: Lens' RxReg Bit
rx_d1 :: Lens' RxReg Bit
rx_cnt :: Lens' RxReg (Unsigned 4)
rx_busy :: Lens' RxReg Bool
data TxReg
TxReg :: BitVector 8 -> Bool -> Bool -> Bit -> Unsigned 4 -> TxReg
[_tx_reg] :: TxReg -> BitVector 8
[_tx_empty] :: TxReg -> Bool
[_tx_over_run] :: TxReg -> Bool
[_tx_out] :: TxReg -> Bit
[_tx_cnt] :: TxReg -> Unsigned 4
tx_reg :: Lens' TxReg (BitVector 8)
tx_over_run :: Lens' TxReg Bool
tx_out :: Lens' TxReg Bit
tx_empty :: Lens' TxReg Bool
tx_cnt :: Lens' TxReg (Unsigned 4)
uartTX :: TxReg -> Bool -> BitVector 8 -> Bool -> TxReg
uartRX :: RxReg -> Bit -> Bool -> Bool -> RxReg
uart :: forall (dom :: Domain). (KnownDomain dom, ?clock :: Clock dom, ?enable :: Enable dom, ?reset :: Reset dom) => Signal dom Bool -> Signal dom (BitVector 8) -> Signal dom Bool -> Signal dom Bit -> Signal dom Bool -> Signal dom Bool -> (Signal dom Bit, Signal dom Bool, Signal dom (BitVector 8), Signal dom Bool)
instance Clash.XException.NFDataX Clash.Examples.Internal.TxReg
instance GHC.Generics.Generic Clash.Examples.Internal.TxReg
instance Clash.XException.NFDataX Clash.Examples.Internal.RxReg
instance GHC.Generics.Generic Clash.Examples.Internal.RxReg


module Clash.Examples


-- | We simulate DDR signal by using <a>Signal</a>s which have exactly half
--   the period (or double the speed) of our normal <a>Signal</a>s.
--   
--   The primitives in this module can be used to produce or consume DDR
--   signals.
--   
--   DDR signals are not meant to be used internally in a design, but only
--   to communicate with the outside world.
--   
--   In some cases hardware specific DDR IN registers can be inferred by
--   synthesis tools from these generic primitives. But to be sure your
--   design will synthesize to dedicated hardware resources use the
--   functions from <a>Clash.Intel.DDR</a> or <a>Clash.Xilinx.DDR</a>.
module Clash.Explicit.DDR

-- | DDR input primitive
--   
--   Consumes a DDR input signal and produces a regular signal containing a
--   pair of values.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 5 $ ddrIn systemClockGen systemResetGen enableGen (-1,-2,-3) (fromList [0..10] :: Signal "Fast" Int)
--   [(-1,-2),(-1,-2),(-3,2),(3,4),(5,6)]
--   </pre>
ddrIn :: (HasCallStack, NFDataX a, KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity)) => Clock slow -> Reset slow -> Enable slow -> (a, a, a) -> Signal fast a -> Signal slow (a, a)

-- | DDR output primitive
--   
--   Produces a DDR output signal from a normal signal of pairs of input.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 7 (ddrOut systemClockGen systemResetGen enableGen (-1) (fromList [(0,1),(2,3),(4,5)]) :: Signal "Fast" Int)
--   [-1,-1,-1,2,3,4,5]
--   </pre>
ddrOut :: (HasCallStack, NFDataX a, KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity)) => Clock slow -> Reset slow -> Enable slow -> a -> Signal slow (a, a) -> Signal fast a
ddrIn# :: forall a slow fast fPeriod polarity edge reset init. (HasCallStack, NFDataX a, KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity)) => Clock slow -> Reset slow -> Enable slow -> a -> a -> a -> Signal fast a -> Signal slow (a, a)
ddrOut# :: (HasCallStack, NFDataX a, KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity)) => Clock slow -> Reset slow -> Enable slow -> a -> Signal slow a -> Signal slow a -> Signal fast a


-- | DDR primitives for Xilinx FPGAs
--   
--   For general information about DDR primitives see
--   <a>Clash.Explicit.DDR</a>.
--   
--   For more information about the Xilinx DDR primitives see:
--   
--   <ul>
--   <li>Vivado Design Suite 7 Series FPGA and Zynq-7000 All Programmable
--   SoC Libraries Guide, UG953 (v2018.3) December 5, 2018,
--   p371-373,p481-483,
--   <a>https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_3/ug953-vivado-7series-libraries.pdf</a></li>
--   </ul>
module Clash.Xilinx.DDR

-- | Xilinx specific variant of <a>ddrIn</a> implemented using the Xilinx
--   IDDR primitive in <tt>SAME_EDGE</tt> mode.
--   
--   Reset values are <tt>0</tt>
iddr :: (HasCallStack, KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity), KnownNat m) => Clock slow -> Reset slow -> Enable slow -> Signal fast (BitVector m) -> Signal slow (BitVector m, BitVector m)

-- | Xilinx specific variant of <a>ddrOut</a> implemented using the Xilinx
--   ODDR primitive in <tt>SAME_EDGE</tt> mode.
--   
--   Reset value is <tt>0</tt>
oddr :: (KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity), KnownNat m) => Clock slow -> Reset slow -> Enable slow -> Signal slow (BitVector m, BitVector m) -> Signal fast (BitVector m)


-- | DDR primitives for Intel FPGAs using ALTDDIO primitives.
--   
--   For general information about DDR primitives see
--   <a>Clash.Explicit.DDR</a>.
--   
--   Note that a reset is only available on certain devices, see ALTDDIO
--   userguide for the specifics:
--   <a>https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_altddio.pdf</a>
module Clash.Intel.DDR

-- | Intel specific variant of <a>ddrIn</a> implemented using the
--   ALTDDIO_IN IP core.
--   
--   Reset values are <tt>0</tt>
altddioIn :: (HasCallStack, KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity), KnownNat m) => SSymbol deviceFamily -> Clock slow -> Reset slow -> Enable slow -> Signal fast (BitVector m) -> Signal slow (BitVector m, BitVector m)

-- | Intel specific variant of <a>ddrOut</a> implemented using the
--   ALTDDIO_OUT IP core.
--   
--   Reset value is <tt>0</tt>
altddioOut :: (HasCallStack, KnownConfiguration fast ('DomainConfiguration fast fPeriod edge reset init polarity), KnownConfiguration slow ('DomainConfiguration slow (2 * fPeriod) edge reset init polarity), KnownNat m) => SSymbol deviceFamily -> Clock slow -> Reset slow -> Enable slow -> Signal slow (BitVector m, BitVector m) -> Signal fast (BitVector m)