Copyright	(C) 2019 Myrtle Software Ltd. 2020 QBayLogic B.V.
License	BSD2 (see the file LICENSE)
Maintainer	QBayLogic B.V. <devops@qbaylogic.com>
Safe Haskell	None
Language	Haskell2010

Clash.Primitives.DSL

Contents

Annotations
declarations

Description

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

Synopsis

blackBoxHaskell :: [Int] -> HDL -> Name -> Name -> Primitive
data BlockState backend = BlockState {
- _bsDeclarations :: [Declaration]
- _bsHigherOrderCalls :: IntMap Int
- _bsBackend :: backend
}
data TExpr
declaration :: Backend backend => Text -> State (BlockState backend) () -> State backend Doc
declarationReturn :: Backend backend => BlackBoxContext -> Text -> State (BlockState backend) TExpr -> State backend Doc
instDecl :: Backend backend => EntityOrComponent -> Identifier -> Identifier -> [(Text, LitHDL)] -> [(Text, TExpr)] -> [(Text, TExpr)] -> State (BlockState backend) ()
instHO :: Backend backend => BlackBoxContext -> Int -> (HWType, BlackBoxTemplate) -> [(TExpr, BlackBoxTemplate)] -> State (BlockState backend) TExpr
viaAnnotatedSignal :: (HasCallStack, Backend backend) => Text -> TExpr -> TExpr -> [Attr'] -> State (BlockState backend) ()
bvLit :: Int -> Integer -> TExpr
data LitHDL
- = B Bool
- | S String
- | I Integer
pattern High :: TExpr
pattern Low :: TExpr
tuple :: [TExpr] -> TExpr
vec :: (HasCallStack, Backend backend) => [TExpr] -> State (BlockState backend) TExpr
tInputs :: BlackBoxContext -> [(TExpr, HWType)]
tResult :: BlackBoxContext -> TExpr
getStr :: TExpr -> Maybe String
getBool :: TExpr -> Maybe Bool
exprToInteger :: Expr -> Maybe Integer
tExprToInteger :: TExpr -> Maybe Integer
untuple :: (HasCallStack, Backend backend) => TExpr -> [Identifier] -> State (BlockState backend) [TExpr]
unvec :: Backend backend => Identifier -> TExpr -> State (BlockState backend) [TExpr]
toBV :: Backend backend => Identifier -> TExpr -> State (BlockState backend) TExpr
fromBV :: (HasCallStack, Backend backend) => Identifier -> TExpr -> State (BlockState backend) TExpr
boolToBit :: (HasCallStack, Backend backend) => Identifier -> TExpr -> State (BlockState backend) TExpr
boolFromBit :: Backend backend => Identifier -> TExpr -> State (BlockState backend) TExpr
boolFromBitVector :: Backend backend => Size -> Identifier -> TExpr -> State (BlockState backend) TExpr
unsignedFromBitVector :: Size -> Identifier -> TExpr -> State (BlockState VHDLState) TExpr
boolFromBits :: [Identifier] -> TExpr -> State (BlockState VHDLState) [TExpr]
andExpr :: Backend backend => Identifier -> TExpr -> TExpr -> State (BlockState backend) TExpr
notExpr :: Backend backend => Identifier -> TExpr -> State (BlockState backend) TExpr
pureToBV :: Identifier -> Int -> TExpr -> State (BlockState VHDLState) TExpr
pureToBVResized :: Identifier -> Int -> TExpr -> State (BlockState VHDLState) TExpr
open :: Backend backend => HWType -> State (BlockState backend) TExpr
toIdentifier :: Backend backend => Identifier -> TExpr -> State (BlockState backend) TExpr
tySize :: Num i => HWType -> i
clog2 :: Num i => Integer -> i

Annotations

blackBoxHaskell Source #

Arguments

:: [Int]	Ignored arguments
-> HDL	hdl the blackbox is for
-> Name	blackbox name
-> Name	template function name
-> Primitive

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

{--}

declarations

data BlockState backend Source #

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 Clash.Netlist.BlackBox.Types.Decl _bsBackend :: backend Backend state

data TExpr Source #

A typed expression.

Instances

Show TExpr Source #
Instance details Defined in Clash.Primitives.DSL Methods showsPrec :: Int -> TExpr -> ShowS # show :: TExpr -> String # showList :: [TExpr] -> ShowS #

declaration Source #

Arguments

:: Backend backend
=> Text	block name
-> State (BlockState backend) ()	block builder
-> State backend Doc	pretty printed block

Run a block declaration.

declarationReturn Source #

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.

instDecl Source #

Arguments

:: Backend backend
=> EntityOrComponent	Type of instantiation
-> Identifier	component/entity name
-> Identifier	instantiation label
-> [(Text, LitHDL)]	attributes
-> [(Text, TExpr)]	in ports
-> [(Text, TExpr)]	out ports
-> State (BlockState backend) ()

Instantiate a component/entity in a block state.

instHO Source #

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 Source #

Arguments

:: (HasCallStack, Backend backend)
=> Text	Name given to signal
-> TExpr	expression the signal is assigned to
-> TExpr	expression (must be identifier) to which the signal is assigned
-> [Attr']	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.

Extraction

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

The TExp inputs from a blackbox context.

tResult :: BlackBoxContext -> TExpr Source #

The TExp result of a blackbox context.

getStr :: TExpr -> Maybe String Source #

Try to get the literal string value of an expression.

getBool :: TExpr -> Maybe Bool Source #

Try to get the literal bool value of an expression.

exprToInteger :: Expr -> Maybe Integer Source #

tExprToInteger :: TExpr -> Maybe Integer Source #

Try to get the literal nat value of an expression.

untuple Source #

Arguments

:: (HasCallStack, Backend backend)
=> TExpr	Tuple expression
-> [Identifier]	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 the block scope.

unvec Source #

Arguments

:: Backend backend
=> Identifier	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.

Conversion

toBV Source #

Arguments

:: Backend backend
=> Identifier	BitVector name
-> TExpr	expression
-> State (BlockState backend) TExpr	BitVector expression

Assign an input bitvector to an expression. Declares a new bitvector if the expression is not already a bitvector.

fromBV Source #

Arguments

:: (HasCallStack, Backend backend)
=> Identifier	BitVector name
-> TExpr	expression
-> State (BlockState backend) TExpr	bv expression

Assign an output bitvector to an expression. Declares a new bitvector if the expression is not already a bitvector.

boolToBit Source #

Arguments

:: (HasCallStack, Backend backend)
=> Identifier	Name hint for intermediate signal
-> TExpr
-> State (BlockState backend) TExpr

Convert a bool to a bit.

boolFromBit Source #

Arguments

:: Backend backend
=> Identifier	Name hint for intermediate signal
-> TExpr
-> State (BlockState backend) TExpr

Use to create an output HWType 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 Source #

Arguments

:: Backend backend
=> Size
-> Identifier	Name hint for intermediate signal
-> TExpr
-> State (BlockState backend) TExpr

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

unsignedFromBitVector Source #

Arguments

:: Size
-> Identifier	Name hint for intermediate signal
-> TExpr
-> State (BlockState VHDLState) TExpr

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

TODO: Implement for (System)Verilog

boolFromBits :: [Identifier] -> TExpr -> State (BlockState VHDLState) [TExpr] Source #

Used to create an output HWType 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

Operations

andExpr Source #

Arguments

:: Backend backend
=> Identifier	name hint
-> TExpr	a
-> TExpr	a
-> State (BlockState backend) TExpr	a && b

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

notExpr Source #

Arguments

:: Backend backend
=> Identifier	name hint
-> TExpr	a
-> State (BlockState backend) TExpr	not a

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

pureToBV Source #

Arguments

:: Identifier	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 Source #

Arguments

:: Identifier	name hint
-> Int	Size (n)
-> TExpr	ARG
-> State (BlockState VHDLState) TExpr	std_logic_vector(resize(ARG, Size))

Creates a BV that produces the following vhdl:

   std_logic_vector(resize(ARG, Size))

TODO: Implement for (System)Verilog

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

Allows assignment of a port to be "open"

Utilities

toIdentifier Source #

Arguments

:: Backend backend
=> Identifier	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 Source #

clog2 :: Num i => Integer -> i Source #

Num LitHDL Source #
Instance details 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 Source #
Instance details Defined in Clash.Primitives.DSL Methods showsPrec :: Int -> LitHDL -> ShowS # show :: LitHDL -> String # showList :: [LitHDL] -> ShowS #
IsString LitHDL Source #
Instance details Defined in Clash.Primitives.DSL Methods fromString :: String -> LitHDL #

:: (HasCallStack, Backend backend)
=> [TExpr]	Elements of vector
-> State (BlockState backend) TExpr	Vector elements

Annotations

declarations

Literals

Extraction

Conversion

Operations

Utilities