Copyright	(c) Matthew Naylor 2019 (c) Alexandre Joannou 2019-2021
License	MIT
Maintainer	mattfn@gmail.com
Stability	experimental
Safe Haskell	Safe-Inferred
Language	GHC2021

Blarney.Core.Prim

Contents

Prim primitive type and helpers
Other primitive types
Netlists

Description

This module provides a set of circuit primitives.

Synopsis

data Prim
- = Const OutputWidth Integer
- | DontCare OutputWidth
- | Add OutputWidth
- | Sub OutputWidth
- | Mul {
  - primMulInputWidth :: InputWidth
  - primMulSigned :: Bool
  - primMulFullPrecision :: Bool
  }
- | Div OutputWidth
- | Mod OutputWidth
- | Not OutputWidth
- | And OutputWidth
- | Or OutputWidth
- | Xor OutputWidth
- | ShiftLeft InputWidth OutputWidth
- | ShiftRight InputWidth OutputWidth
- | ArithShiftRight InputWidth OutputWidth
- | Equal InputWidth
- | NotEqual InputWidth
- | LessThan InputWidth
- | LessThanEq InputWidth
- | ReplicateBit OutputWidth
- | ZeroExtend InputWidth OutputWidth
- | SignExtend InputWidth OutputWidth
- | SelectBits InputWidth BitIndex BitIndex
- | Concat InputWidth InputWidth
- | Mux Int InputWidth OutputWidth
- | Identity OutputWidth
- | Register InitVal InputWidth
- | RegisterEn InitVal InputWidth
- | MergeWrites MergeStrategy Int Width
- | Input OutputWidth String
- | Output InputWidth String
- | BRAM {
  - ramKind :: BRAMKind
  - ramInitFile :: Maybe String
  - ramAddrWidth :: Width
  - ramDataWidth :: Width
  - ramHasByteEn :: Bool
  }
- | Custom {
  - customName :: String
  - customInputs :: [(String, InputWidth)]
  - customOutputs :: [(String, OutputWidth)]
  - customParams :: [Param]
  - customIsClocked :: Bool
  - customResetable :: Bool
  - customNetlist :: Maybe CustomNetlist
  }
- | RegFileMake RegFileInfo
- | RegFileRead RegFileInfo
- | RegFileWrite RegFileInfo
- | Display [DisplayArg]
- | Finish
- | TestPlusArgs String
- | Assert String
canInline :: Prim -> Bool
canInlineInput :: Prim -> Bool
clamp :: (Num a, Bits a) => Width -> a -> a
primStr :: Prim -> String
primSemEvalRaw :: PrimSample a => Prim -> Maybe ([a] -> [a])
primSemEval :: PrimSample a => Prim -> [a] -> [a]
primDontKill :: Prim -> Bool
primIsRoot :: Prim -> Bool
primInputs :: Prim -> [(String, InputWidth)]
primOutputs :: Prim -> [(String, OutputWidth)]
primOutIndex :: Prim -> OutputName -> Maybe Int
primOutWidth :: Prim -> OutputName -> OutputWidth
data BRAMKind
- = BRAMSinglePort
- | BRAMDualPort
- | BRAMTrueDualPort
type InstId = Int
type Width = Int
type InputWidth = Width
type OutputWidth = Width
type OutputName = Maybe String
type InitVal = Ternary
type BitIndex = Int
data MergeStrategy = MStratOr
data RegFileInfo = RegFileInfo {
- regFileId :: Int
- regFileInitFile :: String
- regFileAddrWidth :: InputWidth
- regFileDataWidth :: Width
}
data DisplayArg
- = DisplayArgString String
- | DisplayArgBit {
  - displayArgWidth :: InputWidth
  - displayArgRadix :: DisplayArgRadix
  - displayArgPad :: Maybe Int
  - displayArgZeroPad :: Bool
  }
- | DisplayCondBlockBegin
- | DisplayCondBlockEnd
data DisplayArgRadix
- = Bin
- | Dec
- | Hex
data Param = String :-> String
data NameHint
- = NmPrefix Int String
- | NmRoot Int String
- | NmSuffix Int String
type NameHints = Set NameHint
data Net = Net {
- netPrim :: Prim
- netInstId :: InstId
- netInputs :: [NetInput]
- netNameHints :: NameHints
}
type WireId = (InstId, OutputName)
data NetInput
- = InputWire WireId
- | InputTree Prim [NetInput]
type Netlist = Array InstId Net
newtype CustomNetlist = CustomNetlist Netlist

`Prim` primitive type and helpers

data Prim Source #

The Prim type is used to represent the fundamental operations in blarney. Each Prim constructor can expect some statically known arguments such as desired widths for inputs or outputs, initial values for registers, etc... Each Prim will expect to be used with a list of inputs, and to provide a list of outputs. The shape of these lists is documented here for convenience, but these are not enforced in the Prim type. The primInputs and primOutputs functions can be used to query the shape of the inputs and outpus lists that can be used for a given Prim.

Constructors

Const OutputWidth Integer	`Const w n` represents a constant value inputs no input, i.e. `[]` outputs a single output, the `w`-bit value `n`
DontCare OutputWidth	`DontCare w` represents a don't care value inputs no input, i.e. `[]` outputs a single output, a `w`-bit don't care value
Add OutputWidth	`Add w` represents an adder inputs `[x, y]`, two `w`-bit values outputs a single output, the `w`-bit sum `x + y`
Sub OutputWidth	`Sub w` represents a subtractor inputs `[x, y]`, two `w`-bit values outputs a single output, the `w`-bit difference `x - y`
Mul	Mul { primMulInputWidth = w , primMulSigned = isSigned , primMulFullPrecision = isFullPrecision } represents a multiplier inputs `[x, y]`, two `w`-bit values outputs a single output, the `wout`-bit product `x * y` with `wout = 2*w` if `isFullPrecision` is `True` and `wout = w` if `isFullPrecision` is `False`
Fields primMulInputWidth :: InputWidth Input width primMulSigned :: Bool Operation is signed primMulFullPrecision :: Bool Operation is full precision
Div OutputWidth	`Div w` represents a quotient inputs `[x, y]`, two `w`-bit values outputs a single output, the `w`-bit quotient x `div` y
Mod OutputWidth	`Mod w` represents a remainder inputs `[x, y]`, two `w`-bit values outputs a single output, the `w`-bit remainder x `mod` y
Not OutputWidth	`Not w` represents a bitwise not inputs `[x]`, a single `w`-bit value outputs a single output, the `w`-bit bitwise not of `x`
And OutputWidth	`And w` represents a bitwise and inputs `[x, y]`, two `w`-bit values outputs a single output, the `w`-bit bitwise and x `&` y
Or OutputWidth	`Or w` represents a bitwise or inputs `[x, y]`, two `w`-bit values outputs a single output, the `w`-bit bitwise or x `\|` y
Xor OutputWidth	`Xor w` represents a bitwise xor inputs `[x, y]`, two `w`-bit values outputs a single output, the `w`-bit bitwise xor x `^` y
ShiftLeft InputWidth OutputWidth	`ShiftLeft iw ow` represents a logical left shifter inputs `[x, y]`, with `x` an `ow`-bit value and `y` an `iw`-bit value outputs a single output, the `ow`-bit logical (i.e. zero-injecting) left shift of `x` by `y`
ShiftRight InputWidth OutputWidth	`ShiftRight iw ow` represents a logical right shifter inputs `[x, y]`, with `x` an `ow`-bit value and `y` an `iw`-bit value outputs a single output, the `ow`-bit logical (i.e. zero-injecting) right shift of `x` by `y`
ArithShiftRight InputWidth OutputWidth	`ArithShiftRight iw ow` represents an arithmetic right shifter inputs `[x, y]`, with `x` an `ow`-bit value and `y` an `iw`-bit value outputs a single output, the `ow`-bit arithmetic (i.e. sign-preserving) right shift of `x` by `y`
Equal InputWidth	`Equal w` represents an equality comparator inputs `[x, y]`, two `w`-bit values outputs a single output, the single-bit result of `x == y`
NotEqual InputWidth	`NotEqual w` represents a difference comparator inputs `[x, y]`, two `w`-bit values outputs a single output, the single-bit result of `x /= y`
LessThan InputWidth	`LessThan w` represents a less-than comparator inputs `[x, y]`, two `w`-bit values outputs a single output, the single-bit result of `x < y`
LessThanEq InputWidth	`LessThanEq w` represents a less-than-or-equal comparator inputs `[x, y]`, two `w`-bit values outputs a single output, the single-bit result of `x <= y`
ReplicateBit OutputWidth	`ReplicateBit w` represents the replication of a single bit inputs `[x]`, a single 1-bit value outputs a single output, the `w`-bit value obtained with `w` replications of `x`
ZeroExtend InputWidth OutputWidth	`ZeroExtend iw ow` represents zero-extension inputs `[x]`, a single `iw`-bit value outputs a single output, the `ow`-bit zero-extension of `x`
SignExtend InputWidth OutputWidth	`SignExtend iw ow` represents sign-extension inputs `[x]`, a single `iw`-bit value outputs a single output, the `ow`-bit sign-extension of `x`
SelectBits InputWidth BitIndex BitIndex	`SelectBits iw hi lo` represents bit selection (compile-time range) inputs `[x]`, a single `iw`-bit value outputs a single output, the `(hi - lo + 1)`-bit slice `x[hi:lo]`
Concat InputWidth InputWidth	`Concat w0 w1` represents bit vector concatenation inputs `[x, y]`, with `x` a `w0`-bit value and `y` an `w1`-bit value outputs a single output, the `(w0 + w1)`-bit concatenation `{x, y}`
Mux Int InputWidth OutputWidth	`Mux n wsel w` represents an `n`-input multiplexer inputs `sel:inpts`, with `sel` a `(log2 n)`-bit value and `inpts` an `n`-sized list of `w`-bit values outputs a single output, the `w`-bit value at position `sel` in `inpts` (the width of `sel` is `wsel`)
Identity OutputWidth	`Identity w` represents an identity function inputs `[x]`, a single `w`-bit value outputs a single output, the `w`-bit input value `x`
Register InitVal InputWidth	`Register initial w` represents a register with an initial value. inputs `[x]`, a single `w`-bit value outputs a single output, the `w`-bit value `initial` or the last written input value `x`
RegisterEn InitVal InputWidth	`RegisterEn initial w` represents a register with an initial value and an enable signal. inputs `[en, x]`, with `en` a 1-bit value and `x` a `w`-bit value outputs a single output, the `w`-bit value `initial` or the last written input value `x` when `en` was asserted
MergeWrites MergeStrategy Int Width	`MergeWrites mStrat n w` represents a merging primitive with the `mStrat` merging strategy, `n` pairs of 1-bit enables and associated `w`-wide inputs, and one `w`-wide output inputs `[en0, in0, en1, in1, ...]`, `n` pairs of `enN` 1-bit enables and `inN` `w`-bit values outputs a single output, a `w`-bit value result of the merging of the `n` inputs according to `mStrat`
Input OutputWidth String	`Input w name` represents a named external input inputs no input, i.e. `[]` outputs a single output, the `w`-bit value received as an input from outside the circuit
Output InputWidth String	`Output w name` represents a named external output inputs `[x]`, a single `w`-bit value outputs no output, as this primitive stands for the node that exports `x` outside of the circuit
BRAM	Block RAM
Fields ramKind :: BRAMKind ramInitFile :: Maybe String ramAddrWidth :: Width ramDataWidth :: Width ramHasByteEn :: Bool
Custom	Custom component
Fields customName :: String Component name customInputs :: [(String, InputWidth)] Input names customOutputs :: [(String, OutputWidth)] Output names/widths customParams :: [Param] Parameters customIsClocked :: Bool Pass clock? customResetable :: Bool Pass reset? customNetlist :: Maybe CustomNetlist Optional netlist for this component
RegFileMake RegFileInfo	Register file declaration (only used in RTL context, not expression context)
RegFileRead RegFileInfo	Register file lookup (input: index, output: data)
RegFileWrite RegFileInfo	Register file update (inputs: write-enable, address, data)
Display [DisplayArg]	Not for synthesis `Display args` outputs messages, useful for simulation inputs `en:inpts`, with `en` a 1-bit value, and `inpts` a list of values to be used in conjunction with `args` outputs no output, this primitive captures displaying of information provided through `args` and `inpt` when `en` is asserted
Finish	Not for synthesis `Finish` asks for termination, useful to end simulation inputs `en`, a single 1-bit value outputs no output, this primitive simply signals termination when `en` is asserted
TestPlusArgs String	Not for synthesis `TestPlusArgs plusArg` tests for a plus-args command line argument, useful to dynamically parameterise simulation inputs no input, i.e. `[]` outputs a single output, a 1-bit value signifying the presence or absence of the queried `plusArg` string on the command line
Assert String	Not for synthesis `Assert msg` asserts that a predicate holds inputs `[en, pred]`, two 1-bit values outputs no output, this primitive asserts that `pred` holds when `en` is asserted, and may display additional information together with `msg`

Instances

Instances details

Show Prim #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> Prim -> ShowS # show :: Prim -> String # showList :: [Prim] -> ShowS #

canInline :: Prim -> Bool Source #

Helper to tell whether a Prim can be inlined during Netlist optimisation

canInlineInput :: Prim -> Bool Source #

Helper to tell whether a Prim inputs can be inlined during Netlist optimisation

clamp :: (Num a, Bits a) => Width -> a -> a Source #

clamp a given sample to the provided width

primStr :: Prim -> String Source #

Helper to render a primitive name. Used to generate useful names

primSemEvalRaw :: PrimSample a => Prim -> Maybe ([a] -> [a]) Source #

Helper to retrieve a primitive's semantic evaluation function or lack thereof

primSemEval :: PrimSample a => Prim -> [a] -> [a] Source #

Helper to retrieve a primitive's semantic evaluation function

primDontKill :: Prim -> Bool Source #

Helper to tell if a Prim can be optimized away or not

primIsRoot :: Prim -> Bool Source #

Helper to tell if a Prim is a netlist root

primInputs :: Prim -> [(String, InputWidth)] Source #

Helper to get the inputs of a Prim

primOutputs :: Prim -> [(String, OutputWidth)] Source #

Helper to get the outputs of a Prim

primOutIndex :: Prim -> OutputName -> Maybe Int Source #

Helper to get the index of a given named output of a Prim

primOutWidth :: Prim -> OutputName -> OutputWidth Source #

Helper to get the OutputWidth for a given named output of a Prim

data BRAMKind Source #

Kind of block RAM

Constructors

BRAMSinglePort
BRAMDualPort
BRAMTrueDualPort

Instances

Instances details

Show BRAMKind #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> BRAMKind -> ShowS # show :: BRAMKind -> String # showList :: [BRAMKind] -> ShowS #

Other primitive types

type InstId = Int Source #

Unique identifier used to identify every instance of a component in a circuit

type Width = Int Source #

Bit vector width

type InputWidth = Width Source #

Width of an input to a primitive

type OutputWidth = Width Source #

Width of an output from a primitive

type OutputName = Maybe String Source #

Reference to a named output of a Prim

type InitVal = Ternary Source #

Initial value for registers

type BitIndex = Int Source #

Index into a bit vector

data MergeStrategy Source #

Merging Strategy

Constructors

MStratOr

Instances

Instances details

Show MergeStrategy #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> MergeStrategy -> ShowS # show :: MergeStrategy -> String # showList :: [MergeStrategy] -> ShowS #
Eq MergeStrategy #
Instance details Defined in Blarney.Core.Prim Methods (==) :: MergeStrategy -> MergeStrategy -> Bool # (/=) :: MergeStrategy -> MergeStrategy -> Bool #

data RegFileInfo Source #

Register file primitive parameters

Constructors

RegFileInfo
Fields regFileId :: Int Register file unique identifier regFileInitFile :: String Initialisation file regFileAddrWidth :: InputWidth Address width regFileDataWidth :: Width Data width

Instances

Instances details

Show RegFileInfo #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> RegFileInfo -> ShowS # show :: RegFileInfo -> String # showList :: [RegFileInfo] -> ShowS #

data DisplayArg Source #

For the Display primitive: display a string literal or a bit-vector value of a given width

Constructors

DisplayArgString String	Display a string
DisplayArgBit	Display a bit vector with formatting options
Fields displayArgWidth :: InputWidth Radix of bit vector to display displayArgRadix :: DisplayArgRadix Radix of bit vector to display displayArgPad :: Maybe Int Optional padding displayArgZeroPad :: Bool Pad with zeros or spaces?
DisplayCondBlockBegin	Subsequences of arguments of a display can be conditionally displayed
DisplayCondBlockEnd

Instances

Instances details

Show DisplayArg #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> DisplayArg -> ShowS # show :: DisplayArg -> String # showList :: [DisplayArg] -> ShowS #

data DisplayArgRadix Source #

Format for displaying bit vectors

Constructors

Bin	Binary radix
Dec	Decimal radix
Hex	Hexadecimal radix

Instances

Instances details

Show DisplayArgRadix #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> DisplayArgRadix -> ShowS # show :: DisplayArgRadix -> String # showList :: [DisplayArgRadix] -> ShowS #

data Param Source #

Custom components may have compile-time parameters. A parameter has a name and a value, both represented as strings

Constructors

String :-> String

Instances

Instances details

Show Param #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> Param -> ShowS # show :: Param -> String # showList :: [Param] -> ShowS #

data NameHint Source #

Hint to generate useful names when working with Nets

Constructors

NmPrefix Int String	Suggested name prefix
NmRoot Int String	Suggested name
NmSuffix Int String	Suggested name suffix

Instances

Instances details

Show NameHint #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> NameHint -> ShowS # show :: NameHint -> String # showList :: [NameHint] -> ShowS #
Eq NameHint #
Instance details Defined in Blarney.Core.Prim Methods (==) :: NameHint -> NameHint -> Bool # (/=) :: NameHint -> NameHint -> Bool #
Ord NameHint #
Instance details Defined in Blarney.Core.Prim Methods compare :: NameHint -> NameHint -> Ordering # (<) :: NameHint -> NameHint -> Bool # (<=) :: NameHint -> NameHint -> Bool # (>) :: NameHint -> NameHint -> Bool # (>=) :: NameHint -> NameHint -> Bool # max :: NameHint -> NameHint -> NameHint # min :: NameHint -> NameHint -> NameHint #

type NameHints = Set NameHint Source #

A set of NameHints

Netlists

data Net Source #

Net type representing a Netlist node

Constructors

Net
Fields netPrim :: Prim The `Net` 's `Prim`itive netInstId :: InstId The `Net` 's `InstId` identifier netInputs :: [NetInput] The `Net` 's list of `NetInput` inputs netNameHints :: NameHints The `Net` 's `NameHints`

Instances

Instances details

Show Net #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> Net -> ShowS # show :: Net -> String # showList :: [Net] -> ShowS #

type WireId = (InstId, OutputName) Source #

A WireId uniquely identify a wire with a Net's instance identifier (InstId) and an output name (OutputName)

data NetInput Source #

A Net's input (NetInput) can be: - a wire, using the InputWire constructor - a complex expression, using the InputTree constructor

Constructors

InputWire WireId
InputTree Prim [NetInput]

Instances

Instances details

Show NetInput #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> NetInput -> ShowS # show :: NetInput -> String # showList :: [NetInput] -> ShowS #

type Netlist = Array InstId Net Source #

A Netlist, represented as an 'Array InstId Net'

newtype CustomNetlist Source #

Netlist for a Custom Prim. We use a new type here so that we can keep automatic deriving of the Show class for Prim.

Constructors

CustomNetlist Netlist

Instances

Instances details

Show CustomNetlist #
Instance details Defined in Blarney.Core.Prim Methods showsPrec :: Int -> CustomNetlist -> ShowS # show :: CustomNetlist -> String # showList :: [CustomNetlist] -> ShowS #

Prim primitive type and helpers

Instances

Instances

Other primitive types

Instances

Instances

Instances

Instances

Instances

Instances

Netlists

Instances

Instances

Instances

`Prim` primitive type and helpers