Clash.Primitives.DSL

This module contains a mini dsl for creating haskell blackbox instantiations.

Annotations

data BlackBoxHaskellOpts

Options for blackBoxHaskell function. Use def from package 'data-default' for a set of default options.

Constructors

BlackBoxHaskellOpts

Fields

• bo_ignoredArguments :: [Int]

  Arguments to ignore (i.e., remove during normalization)

  Default: []

• bo_supportedHdls :: [HDL]

  HDLs to use the blackbox for

  Default: all

• bo_multiResult :: Bool

  Does this blackbox assign its results to multiple binders?

  Default: False.

Instances

Default BlackBoxHaskellOpts

Defined in Clash.Primitives.DSL

Methods

def :: BlackBoxHaskellOpts

blackBoxHaskell

Arguments

:: Name

blackbox name

-> Name

template function name

-> BlackBoxHaskellOpts

Options, see data structure for more information

-> Primitive

Create a blackBoxHaskell primitive. To be used as part of an annotation:

{-# ANN myFunction (blackBoxHaskell 'myFunction 'myBBF def{bo_ignoredArguments=[1,2]}) #-}

[1,2] would mean this blackbox ignores its second and third argument.

Declarations

data BlockState backend

The state of a block. Contains a list of declarations and a the backend state.

Constructors

BlockState

Fields

• _bsDeclarations :: [Declaration]

  Declarations store

• _bsHigherOrderCalls :: IntMap Int

  Tracks how many times a higher order function has been instantiated. Needed to fill in the second field of Decl

• _bsBackend :: backend

  Backend state

Instances

Backend backend => HasIdentifierSet (BlockState backend)

Defined in Clash.Primitives.DSL

Methods

identifierSet :: Lens' (BlockState backend) IdentifierSet

HasUsageMap backend => HasUsageMap (BlockState backend)

Defined in Clash.Primitives.DSL

Methods

usageMap :: Lens' (BlockState backend) UsageMap

data TExpr

A typed expression.

Constructors

TExpr

Fields

• ety :: HWType
• eex :: Expr

Instances

Show TExpr

Defined in Clash.Primitives.DSL

Methods

showsPrec :: Int -> TExpr -> ShowS

show :: TExpr -> String

showList :: [TExpr] -> ShowS

addDeclaration :: Declaration -> State (BlockState backend) ()

Add a declaration to the state.

assign

Arguments

:: Backend backend

=> Text

Name hint for assignment

-> TExpr

expression to be assigned to freshly generated identifier

-> State (BlockState backend) TExpr

the identifier of the expression that actually got assigned

Assign an expression to an identifier, returns the new typed identifier expression.

compInBlock

Arguments

:: forall backend. Backend backend

=> Text

Component name

-> [(Text, HWType)]

in ports

-> [(Text, HWType)]

out ports

-> State (BlockState backend) ()

This creates a component declaration (for VHDL) given in and out port names, updating the 'BlockState backend' stored in the State monad.

A typical result is that a

component fifo port
   ( rst : in std_logic
   ...
   ; full : out std_logic
   ; empty : out std_logic );
 end component;

declaration would be added in the appropriate place.

declaration

Arguments

:: Backend backend

=> Text

block name

-> State (BlockState backend) ()

block builder

-> State backend Doc

pretty printed block

Run a block declaration.

declarationReturn

Arguments

:: Backend backend

=> BlackBoxContext

-> Text

block name

-> State (BlockState backend) [TExpr]

block builder yielding an expression that should be assigned to the result variable in the blackbox context

-> State backend Doc

pretty printed block

Run a block declaration. Assign the result of the block builder to the result variable in the given blackbox context.

declare

Arguments

:: Backend backend

=> Text

Name hint

-> HWType

Type of new signal

-> State (BlockState backend) TExpr

Expression pointing the the new signal

Declare a new signal with the given name and type.

declareN

Arguments

:: Backend backend

=> Text

Name hint

-> [HWType]

Types of the signals

-> State (BlockState backend) [TExpr]

Expressions pointing the the new signals

Declare n new signals with the given type and based on the given name

instDecl

Arguments

:: forall backend. Backend backend

=> EntityOrComponent

Type of instantiation

-> Identifier

Component/entity name

-> Identifier

Instantiation label

-> [(Text, TExpr)]

Generics / parameters

-> [(Text, TExpr)]

In ports

-> [(Text, TExpr)]

Out ports

-> State (BlockState backend) ()

Instantiate a component/entity in a block state

instHO

Arguments

:: Backend backend

=> BlackBoxContext

BlackBoxContext, used for rendering higher-order function and error reporting

-> Int

Position of HO-argument. For example:

fold :: forall n a . (a -> a -> a) -> Vec (n + 1) a -> a

would have its HO-argument at position 0, while

iterateI :: forall n a. KnownNat n => (a -> a) -> a -> Vec n a

would have it at position 1.

-> (HWType, BlackBoxTemplate)

Result type of HO function

-> [(TExpr, BlackBoxTemplate)]

Arguments and their types

-> State (BlockState backend) TExpr

Result of the function

Instantiate/call a higher-order function.

viaAnnotatedSignal

Arguments

:: (HasCallStack, Backend backend)

=> Identifier

Name given to signal

-> TExpr

expression the signal is assigned to

-> TExpr

expression (must be identifier) to which the signal is assigned

-> [Attr Text]

the attributes to annotate the signal with

-> State (BlockState backend) ()

Wires the two given TExprs together using a newly declared signal with (exactly) the given name sigNm. The new signal has an annotated type, using the given attributes.

Literals

bvLit

Arguments

:: Int

BitVector size

-> Integer

Literal

-> TExpr

Construct a fully defined BitVector literal

data LitHDL

A literal that can be used for hdl attributes. It has a Num and IsString instances for convenience.

Constructors

B Bool

S String

I Integer

Instances

Num LitHDL

Defined in Clash.Primitives.DSL

Methods

(+) :: LitHDL -> LitHDL -> LitHDL

(-) :: LitHDL -> LitHDL -> LitHDL

(*) :: LitHDL -> LitHDL -> LitHDL

negate :: LitHDL -> LitHDL

abs :: LitHDL -> LitHDL

signum :: LitHDL -> LitHDL

fromInteger :: Integer -> LitHDL

Show LitHDL

Defined in Clash.Primitives.DSL

Methods

showsPrec :: Int -> LitHDL -> ShowS

show :: LitHDL -> String

showList :: [LitHDL] -> ShowS

IsString LitHDL

Defined in Clash.Primitives.DSL

Methods

fromString :: String -> LitHDL

pattern High :: TExpr

The high literal bit.

pattern Low :: TExpr

The low literal bit.

constructProduct :: HWType -> [TExpr] -> TExpr

Construct a product type given its type and fields

tuple :: HasCallStack => [TExpr] -> TExpr

Create an n-tuple of TExpr

vec

Arguments

:: (HasCallStack, Backend backend)

=> [TExpr]

Elements of vector

-> State (BlockState backend) TExpr

Vector elements

Create a vector of TExprs

Extraction

tInputs :: BlackBoxContext -> [(TExpr, HWType)]

The TExp inputs from a blackbox context.

tResults :: BlackBoxContext -> [TExpr]

The TExp result of a blackbox context.

getStr :: TExpr -> Maybe String

Try to get the literal string value of an expression.

getBool :: TExpr -> Maybe Bool

Try to get the literal bool value of an expression.

getVec :: TExpr -> Maybe [TExpr]

Try to get a Vector of expressions.

exprToInteger :: Expr -> Maybe Integer

tExprToInteger :: TExpr -> Maybe Integer

Try to get the literal nat value of an expression.

deconstructProduct

Arguments

:: (HasCallStack, Backend backend)

=> TExpr

Product expression

-> [Text]

Name hints for element assignments

-> State (BlockState backend) [TExpr]

Extract the fields of a product type and return expressions to them. These new expressions are given unique names and get declared in the block scope.

untuple

Arguments

:: (HasCallStack, Backend backend)

=> TExpr

Tuple expression

-> [Text]

Name hints for element assignments

-> State (BlockState backend) [TExpr]

Extract the elements of a tuple expression and return expressions to them. These new expressions are given unique names and get declared in the block scope.

unvec

Arguments

:: (HasCallStack, Backend backend)

=> Text

Name hint for intermediate signal

-> TExpr

Vector expression

-> State (BlockState backend) [TExpr]

Vector elements

Extract the elements of a vector expression and return expressions to them. If given expression is not an identifier, an intermediate variable will be used to assign the given expression to which is subsequently indexed.

deconstructMaybe

Arguments

:: (HasCallStack, Backend backend)

=> TExpr

Maybe expression

-> (Text, Text)

Name hint for constructor bit, data

-> State (BlockState backend) (TExpr, TExpr)

Constructor represented as a Bit, contents of Just

Deconstruct a Maybe into its constructor Bit and contents of its Just field. Note that the contents might be undefined, if the constructor bit is set to Nothing.

Conversion

bitCoerce

Arguments

:: (HasCallStack, Backend backend)

=> Text

Name hints for intermediate variables

-> HWType

Type to convert to

-> TExpr

Expression to convert

-> State (BlockState backend) TExpr

Converted expression

Convert an expression from one type to another. Errors if result type and given expression are sized differently.

toBV

Arguments

:: Backend backend

=> Text

BitVector name hint

-> TExpr

Expression to convert to BitVector

-> State (BlockState backend) TExpr

BitVector expression

Convert an expression to a BitVector

toBvWithAttrs

Arguments

:: Backend backend

=> [Attr Text]

-> Text

BitVector name hint

-> TExpr

Expression to convert to BitVector

-> State (BlockState backend) TExpr

BitVector expression

Convert an expression to a BitVector and add the given HDL attributes

fromBV

Arguments

:: (HasCallStack, Backend backend)

=> Text

Result name hint

-> HWType

Type to convert to

-> TExpr

BitVector expression

-> State (BlockState backend) TExpr

Converted BitVector expression

Convert an expression from a BitVector into some type. If the expression is Annotated, only convert the expression within.

enableToBit

Arguments

:: (HasCallStack, Backend backend)

=> Text

Name hint for intermediate signal

-> TExpr

-> State (BlockState backend) TExpr

Convert an enable to a bit.

boolToBit

Arguments

:: (HasCallStack, Backend backend)

=> Text

Name hint for intermediate signal

-> TExpr

-> State (BlockState backend) TExpr

Convert a bool to a bit.

boolFromBit

Arguments

:: (HasCallStack, Backend backend)

=> Text

Name hint for intermediate signal

-> TExpr

-> State (BlockState backend) TExpr

Use to create an output Bool from a Bit. The expression given must be the identifier of the bool you wish to get assigned. Returns a reference to a declared Bit that should get assigned by something (usually the output port of an entity).

boolFromBitVector

Arguments

:: Size

-> Text

Name hint for intermediate signal

-> TExpr

-> State (BlockState VHDLState) TExpr

Used to create an output Bool from a BitVector of given size. Works in a similar way to boolFromBit above.

TODO: Implement for (System)Verilog

unsignedFromBitVector

Arguments

:: (HasCallStack, Backend backend)

=> Text

Name hint for intermediate signal

-> TExpr

BitVector expression

-> State (BlockState backend) TExpr

Unsigned expression

Used to create an output Unsigned from a BitVector of given size. Works in a similar way to boolFromBit above.

boolFromBits :: [Text] -> TExpr -> State (BlockState VHDLState) [TExpr]

Used to create an output Bool from a number of Bits, using conjunction. Similarly to untuple, it returns a list of references to declared values (the inputs to the function) which should get assigned by something---usually output ports of an entity.

TODO: Implement for (System)Verilog

unsafeToActiveHigh

Arguments

:: Backend backend

=> Text

Name hint

-> TExpr

Reset signal

-> State (BlockState backend) TExpr

Massage a reset to work as active-high reset.

unsafeToActiveLow

Arguments

:: Backend backend

=> Text

Name hint

-> TExpr

Reset signal

-> State (BlockState backend) TExpr

Massage a reset to work as active-low reset.

Operations

andExpr

Arguments

:: Backend backend

=> Text

name hint

-> TExpr

a

-> TExpr

a

-> State (BlockState backend) TExpr

a && b

And together (&&) two expressions, assigning it to a new identifier.

notExpr

Arguments

:: Backend backend

=> Text

name hint

-> TExpr

a

-> State (BlockState backend) TExpr

not a

Negate (not) an expression, assigning it to a new identifier.

pureToBV

Arguments

:: Text

name hint

-> Int

Size (n)

-> TExpr

ARG

-> State (BlockState VHDLState) TExpr

(0 to n => ARG)

Creates a BV that produces the following vhdl:

   (0 to n => ARG)

TODO: Implement for (System)Verilog

pureToBVResized

Arguments

:: Text

name hint

-> Int

Size (n)

-> TExpr

ARG

-> State (BlockState VHDLState) TExpr

std_logic_vector(resize(ARG, n))

Creates a BV that produces the following vhdl:

   std_logic_vector(resize(ARG, n))

TODO: Implement for (System)Verilog

open :: Backend backend => HWType -> State (BlockState backend) TExpr

Allows assignment of a port to be "open"

Utilities

clog2 :: Num i => Integer -> i

litTExpr :: LitHDL -> TExpr

Convert a LitHDL to a TExpr

N.B.: Clash 1.8 changed instDecl's type signature. Where it would previously accept LitHDL in its generics/parameters argument, it now accepts a TExpr. This function is mostly there to ease this transition.

toIdentifier

Arguments

:: Backend backend

=> Text

desired new identifier name, will be made unique

-> TExpr

expression to get identifier of

-> State (BlockState backend) TExpr

identifier to expression

Get an identifier to an expression, creating a new assignment if necessary.

tySize :: Num i => HWType -> i