clash-lib-1.8.1: Clash: a functional hardware description language - As a library

Copyright | (C) 2012-2016 University of Twente 2016-2017 Myrtle Software Ltd 2018 Google Inc. 2021 QBayLogic B.V. 2022 Google Inc.
License | BSD2 (see the file LICENSE)
Maintainer | QBayLogic B.V. <devops@qbaylogic.com>
Safe Haskell | Safe-Inferred
Language | Haskell2010

Clash.Primitives.Types

Description

Type and instance definitions for Primitive

Synopsis

- data TemplateSource
  - = TFile FilePath
  - | TInline Text
- data TemplateKind
  - = TDecl
  - | TExpr
- data TemplateFormat
  - = TTemplate
  - | THaskell
- data BlackBoxFunctionName = BlackBoxFunctionName [String] String
- data Primitive a b c d
  - = BlackBox {
    - name :: !Text
    - workInfo :: WorkInfo
    - renderVoid :: RenderVoid
    - multiResult :: Bool
    - kind :: TemplateKind
    - warning :: c
    - outputUsage :: Usage
    - libraries :: [a]
    - imports :: [a]
    - functionPlurality :: [(Int, Int)]
    - includes :: [((Text, Text), b)]
    - resultNames :: [b]
    - resultInits :: [b]
    - template :: b
    }
  - | BlackBoxHaskell {
    - name :: !Text
    - workInfo :: WorkInfo
    - usedArguments :: UsedArguments
    - multiResult :: Bool
    - functionName :: BlackBoxFunctionName
    - function :: d
    }
  - | Primitive {
    - name :: !Text
    - workInfo :: WorkInfo
    - primSort :: !Text
    }
- data UsedArguments
  - = UsedArguments [Int]
  - | IgnoredArguments [Int]
- type GuardedCompiledPrimitive = PrimitiveGuard CompiledPrimitive
- type GuardedResolvedPrimitive = PrimitiveGuard ResolvedPrimitive
- type PrimMap a = HashMap Text a
- type UnresolvedPrimitive = Primitive Text ((TemplateFormat, BlackBoxFunctionName), Maybe TemplateSource) (Maybe Text) (Maybe TemplateSource)
- type ResolvedPrimitive = Primitive Text ((TemplateFormat, BlackBoxFunctionName), Maybe Text) () (Maybe Text)
- type ResolvedPrimMap = PrimMap GuardedResolvedPrimitive
- type CompiledPrimitive = Primitive BlackBoxTemplate BlackBox () (Int, BlackBoxFunction)
- type CompiledPrimMap = PrimMap GuardedCompiledPrimitive

# Documentation

data TemplateSource Source #

Constructors

TFile FilePath | Template source stored in file on filesystem
TInline Text | Template stored inline

#### Instances

Instances details

FromJSON UnresolvedPrimitive Source # |
Instance details Defined in Clash.Primitives.Types Methods parseJSON :: Value -> Parser UnresolvedPrimitive Source # parseJSONList :: Value -> Parser [UnresolvedPrimitive] Source #
Generic TemplateSource Source # |
Instance details Defined in Clash.Primitives.Types Associated Types type Rep TemplateSource :: Type -> Type Source # Methods from :: TemplateSource -> Rep TemplateSource x Source # to :: Rep TemplateSource x -> TemplateSource Source #
Show TemplateSource Source # |
Instance details Defined in Clash.Primitives.Types Methods showsPrec :: Int -> TemplateSource -> ShowS Source # show :: TemplateSource -> String Source # showList :: [TemplateSource] -> ShowS Source #
NFData TemplateSource Source # |
Instance details Defined in Clash.Primitives.Types Methods rnf :: TemplateSource -> () Source #
Eq TemplateSource Source # |
Instance details Defined in Clash.Primitives.Types Methods (==) :: TemplateSource -> TemplateSource -> Bool Source # (/=) :: TemplateSource -> TemplateSource -> Bool Source #
Hashable TemplateSource Source # |
Instance details Defined in Clash.Primitives.Types Methods hashWithSalt :: Int -> TemplateSource -> Int Source # hash :: TemplateSource -> Int Source #
type Rep TemplateSource Source # |

Instance details

Defined in Clash.Primitives.Types

type Rep TemplateSource = D1 ('MetaData "TemplateSource" "Clash.Primitives.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "TFile" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FilePath)) :+: C1 ('MetaCons "TInline" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)))

data TemplateKind Source #

Constructors

TDecl |
TExpr |

#### Instances

Instances details

Generic TemplateKind Source # |
Instance details Defined in Clash.Netlist.BlackBox.Types Associated Types type Rep TemplateKind :: Type -> Type Source # Methods from :: TemplateKind -> Rep TemplateKind x Source # to :: Rep TemplateKind x -> TemplateKind Source #
Show TemplateKind Source # |
Instance details Defined in Clash.Netlist.BlackBox.Types Methods showsPrec :: Int -> TemplateKind -> ShowS Source # show :: TemplateKind -> String Source # showList :: [TemplateKind] -> ShowS Source #
Binary TemplateKind Source # |
Instance details Defined in Clash.Netlist.BlackBox.Types Methods put :: TemplateKind -> Put Source # get :: Get TemplateKind Source # putList :: [TemplateKind] -> Put Source #
NFData TemplateKind Source # |
Instance details Defined in Clash.Netlist.BlackBox.Types Methods rnf :: TemplateKind -> () Source #
Eq TemplateKind Source # |
Instance details Defined in Clash.Netlist.BlackBox.Types Methods (==) :: TemplateKind -> TemplateKind -> Bool Source # (/=) :: TemplateKind -> TemplateKind -> Bool Source #
Hashable TemplateKind Source # |
Instance details Defined in Clash.Netlist.BlackBox.Types Methods hashWithSalt :: Int -> TemplateKind -> Int Source # hash :: TemplateKind -> Int Source #
type Rep TemplateKind Source # |
Instance details Defined in Clash.Netlist.BlackBox.Types type Rep TemplateKind = D1 ('MetaData "TemplateKind" "Clash.Netlist.BlackBox.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "TDecl" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "TExpr" 'PrefixI 'False) (U1 :: Type -> Type))

data TemplateFormat Source #

Constructors

TTemplate |
THaskell |

#### Instances

Instances details

FromJSON UnresolvedPrimitive Source # |
Instance details Defined in Clash.Primitives.Types Methods parseJSON :: Value -> Parser UnresolvedPrimitive Source # parseJSONList :: Value -> Parser [UnresolvedPrimitive] Source #
Generic TemplateFormat Source # |
Instance details Defined in Clash.Primitives.Types Associated Types type Rep TemplateFormat :: Type -> Type Source # Methods from :: TemplateFormat -> Rep TemplateFormat x Source # to :: Rep TemplateFormat x -> TemplateFormat Source #
Show TemplateFormat Source # |
Instance details Defined in Clash.Primitives.Types Methods showsPrec :: Int -> TemplateFormat -> ShowS Source # show :: TemplateFormat -> String Source # showList :: [TemplateFormat] -> ShowS Source #
NFData TemplateFormat Source # |
Instance details Defined in Clash.Primitives.Types Methods rnf :: TemplateFormat -> () Source #
Eq TemplateFormat Source # |
Instance details Defined in Clash.Primitives.Types Methods (==) :: TemplateFormat -> TemplateFormat -> Bool Source # (/=) :: TemplateFormat -> TemplateFormat -> Bool Source #
Hashable TemplateFormat Source # |
Instance details Defined in Clash.Primitives.Types Methods hashWithSalt :: Int -> TemplateFormat -> Int Source # hash :: TemplateFormat -> Int Source #
type Rep TemplateFormat Source # |
Instance details Defined in Clash.Primitives.Types type Rep TemplateFormat = D1 ('MetaData "TemplateFormat" "Clash.Primitives.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "TTemplate" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "THaskell" 'PrefixI 'False) (U1 :: Type -> Type))

data BlackBoxFunctionName Source #

A BBFN is a parsed version of a fully qualified function name. It is guaranteed to have at least one module name which is not Main.

Constructors

BlackBoxFunctionName [String] String |

#### Instances

Instances details

FromJSON UnresolvedPrimitive Source # |
Instance details Defined in Clash.Primitives.Types Methods parseJSON :: Value -> Parser UnresolvedPrimitive Source # parseJSONList :: Value -> Parser [UnresolvedPrimitive] Source #
Generic BlackBoxFunctionName Source # |
Instance details Defined in Clash.Primitives.Types Associated Types type Rep BlackBoxFunctionName :: Type -> Type Source # Methods from :: BlackBoxFunctionName -> Rep BlackBoxFunctionName x Source # to :: Rep BlackBoxFunctionName x -> BlackBoxFunctionName Source #
Show BlackBoxFunctionName Source # |
Instance details Defined in Clash.Primitives.Types Methods showsPrec :: Int -> BlackBoxFunctionName -> ShowS Source # show :: BlackBoxFunctionName -> String Source # showList :: [BlackBoxFunctionName] -> ShowS Source #
Binary BlackBoxFunctionName Source # |
Instance details Defined in Clash.Primitives.Types Methods put :: BlackBoxFunctionName -> Put Source # get :: Get BlackBoxFunctionName Source # putList :: [BlackBoxFunctionName] -> Put Source #
NFData BlackBoxFunctionName Source # |
Instance details Defined in Clash.Primitives.Types Methods rnf :: BlackBoxFunctionName -> () Source #
Eq BlackBoxFunctionName Source # |
Instance details Defined in Clash.Primitives.Types Methods (==) :: BlackBoxFunctionName -> BlackBoxFunctionName -> Bool Source # (/=) :: BlackBoxFunctionName -> BlackBoxFunctionName -> Bool Source #
Hashable BlackBoxFunctionName Source # |
Instance details Defined in Clash.Primitives.Types Methods hashWithSalt :: Int -> BlackBoxFunctionName -> Int Source # hash :: BlackBoxFunctionName -> Int Source #
type Rep BlackBoxFunctionName Source # |

Instance details

Defined in Clash.Primitives.Types

type Rep BlackBoxFunctionName = D1 ('MetaData "BlackBoxFunctionName" "Clash.Primitives.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "BlackBoxFunctionName" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [String]) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))

data Primitive a b c d Source #

Externally defined primitive

Constructors

BlackBox | Primitive template written in a Clash specific templating language

Fields

- name :: !Text

  Name of the primitive

- workInfo :: WorkInfo

  Whether the primitive does any work, i.e. takes chip area

- renderVoid :: RenderVoid

  Whether this primitive should be rendered when its result type is void. Defaults to `NoRenderVoid`.

- multiResult :: Bool

  Wether this blackbox assigns its results to multiple variables. See `setupMultiResultPrim`

- kind :: TemplateKind

  Whether this results in an expression or a declaration

- warning :: c

  A warning to be outputted when the primitive is instantiated. This is intended to be used as a warning for primitives that are not synthesizable, but may also be used for other purposes.

- outputUsage :: Usage

  How the result is assigned in HDL. This is used to determine the type of declaration used to render the result (wire/reg or signal/variable). The default usage is continuous assignment.

- libraries :: [a]

  VHDL only: add library declarations for the given names

- imports :: [a]

  VHDL only: add use declarations for the given names

- functionPlurality :: [(Int, Int)]

  Indicates how often a function will be instantiated in a blackbox. For example, consider the following higher-order function that creates a tree structure:

  fold :: (a -> a -> a) -> Vec n a -> a

  In order to generate HDL for an instance of fold we need log2(n) calls to the first argument, `a -> a -> a` (plus a few more if n is not a power of two). Note that this only targets multiple textual instances of the function. If you can generate the HDL using a for-loop and only need to call ~INST once, you don't have to worry about this option. See the blackbox for `map` for an example of this.

  Right now, option can only be generated by BlackBoxHaskell. It cannot be used within JSON primitives. To see how to use this, see the Haskell blackbox for `fold`.

- includes :: [((Text, Text), b)]

  Create files to be included with the generated primitive. The fields are ((name, extension), content), where content is a template of the file Defaults to `[]` when not specified in the .primitives file

- resultNames :: [b]

  (Maybe) Control the generated name of the result

- resultInits :: [b]

  (Maybe) Control the initial/power-up value of the result

- template :: b

  Used to indiciate type of template (declaration or expression). Will be filled with `Template` or an `Either decl expr`.

BlackBoxHaskell | Primitive template rendered by a Haskell function (given as raw source code)

Fields

- name :: !Text

  Name of the primitive

- workInfo :: WorkInfo

  Whether the primitive does any work, i.e. takes chip area

- usedArguments :: UsedArguments

  Arguments used by blackbox. Used to remove arguments during normalization.

- multiResult :: Bool

  Wether this blackbox assigns its results to multiple variables. See `setupMultiResultPrim`

- functionName :: BlackBoxFunctionName
- function :: d

  Holds blackbox function and its hash, (Int, BlackBoxFunction), in a CompiledPrimitive.

Primitive | A primitive that carries additional information. These are "real" primitives, hardcoded in the compiler. For example: `mapSignal` in `GHC2Core.coreToTerm`.

Fields

- name :: !Text

  Name of the primitive

- workInfo :: WorkInfo

  Whether the primitive does any work, i.e. takes chip area

- primSort :: !Text

  Additional information

#### Instances

Instances details

FromJSON UnresolvedPrimitive Source # |
Instance details Defined in Clash.Primitives.Types Methods parseJSON :: Value -> Parser UnresolvedPrimitive Source # parseJSONList :: Value -> Parser [UnresolvedPrimitive] Source #
Functor (Primitive a b c) Source # |
Instance details Defined in Clash.Primitives.Types Methods fmap :: (a0 -> b0) -> Primitive a b c a0 -> Primitive a b c b0 Source # (<$) :: a0 -> Primitive a b c b0 -> Primitive a b c a0 Source #
Generic (Primitive a b c d) Source # |
Instance details Defined in Clash.Primitives.Types Associated Types type Rep (Primitive a b c d) :: Type -> Type Source # Methods from :: Primitive a b c d -> Rep (Primitive a b c d) x Source # to :: Rep (Primitive a b c d) x -> Primitive a b c d Source #
(Show c, Show a, Show b, Show d) => Show (Primitive a b c d) Source # |
Instance details Defined in Clash.Primitives.Types Methods showsPrec :: Int -> Primitive a b c d -> ShowS Source # show :: Primitive a b c d -> String Source # showList :: [Primitive a b c d] -> ShowS Source #
(Binary c, Binary a, Binary b, Binary d) => Binary (Primitive a b c d) Source # |
Instance details Defined in Clash.Primitives.Types Methods put :: Primitive a b c d -> Put Source # get :: Get (Primitive a b c d) Source # putList :: [Primitive a b c d] -> Put Source #
(NFData c, NFData a, NFData b, NFData d) => NFData (Primitive a b c d) Source # |
Instance details Defined in Clash.Primitives.Types Methods rnf :: Primitive a b c d -> () Source #
(Eq c, Eq a, Eq b, Eq d) => Eq (Primitive a b c d) Source # |
Instance details Defined in Clash.Primitives.Types Methods (==) :: Primitive a b c d -> Primitive a b c d -> Bool Source # (/=) :: Primitive a b c d -> Primitive a b c d -> Bool Source #
(Hashable c, Hashable a, Hashable b, Hashable d) => Hashable (Primitive a b c d) Source # |
Instance details Defined in Clash.Primitives.Types Methods hashWithSalt :: Int -> Primitive a b c d -> Int Source # hash :: Primitive a b c d -> Int Source #
type Rep (Primitive a b c d) Source # |

Instance details

Defined in Clash.Primitives.Types

type Rep (Primitive a b c d) = D1 ('MetaData "Primitive" "Clash.Primitives.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "BlackBox" 'PrefixI 'True) (((S1 ('MetaSel ('Just "name") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: (S1 ('MetaSel ('Just "workInfo") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 WorkInfo) :*: S1 ('MetaSel ('Just "renderVoid") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 RenderVoid))) :*: ((S1 ('MetaSel ('Just "multiResult") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool) :*: S1 ('MetaSel ('Just "kind") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TemplateKind)) :*: (S1 ('MetaSel ('Just "warning") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 c) :*: S1 ('MetaSel ('Just "outputUsage") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Usage)))) :*: ((S1 ('MetaSel ('Just "libraries") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [a]) :*: (S1 ('MetaSel ('Just "imports") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [a]) :*: S1 ('MetaSel ('Just "functionPlurality") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [(Int, Int)]))) :*: ((S1 ('MetaSel ('Just "includes") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [((Text, Text), b)]) :*: S1 ('MetaSel ('Just "resultNames") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [b])) :*: (S1 ('MetaSel ('Just "resultInits") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [b]) :*: S1 ('MetaSel ('Just "template") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 b))))) :+: (C1 ('MetaCons "BlackBoxHaskell" 'PrefixI 'True) ((S1 ('MetaSel ('Just "name") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: (S1 ('MetaSel ('Just "workInfo") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 WorkInfo) :*: S1 ('MetaSel ('Just "usedArguments") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 UsedArguments))) :*: (S1 ('MetaSel ('Just "multiResult") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool) :*: (S1 ('MetaSel ('Just "functionName") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 BlackBoxFunctionName) :*: S1 ('MetaSel ('Just "function") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 d)))) :+: C1 ('MetaCons "Primitive" 'PrefixI 'True) (S1 ('MetaSel ('Just "name") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: (S1 ('MetaSel ('Just "workInfo") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 WorkInfo) :*: S1 ('MetaSel ('Just "primSort") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text)))))

data UsedArguments Source #

Data type to indicate what arguments are in use by a BlackBox

Constructors

UsedArguments [Int] | Only these are used
IgnoredArguments [Int] | All but these are used

#### Instances

Instances details

Generic UsedArguments Source # |
Instance details Defined in Clash.Primitives.Types Associated Types type Rep UsedArguments :: Type -> Type Source # Methods from :: UsedArguments -> Rep UsedArguments x Source # to :: Rep UsedArguments x -> UsedArguments Source #
Show UsedArguments Source # |
Instance details Defined in Clash.Primitives.Types Methods showsPrec :: Int -> UsedArguments -> ShowS Source # show :: UsedArguments -> String Source # showList :: [UsedArguments] -> ShowS Source #
Binary UsedArguments Source # |
Instance details Defined in Clash.Primitives.Types Methods put :: UsedArguments -> Put Source # get :: Get UsedArguments Source # putList :: [UsedArguments] -> Put Source #
NFData UsedArguments Source # |
Instance details Defined in Clash.Primitives.Types Methods rnf :: UsedArguments -> () Source #
Eq UsedArguments Source # |
Instance details Defined in Clash.Primitives.Types Methods (==) :: UsedArguments -> UsedArguments -> Bool Source # (/=) :: UsedArguments -> UsedArguments -> Bool Source #
Hashable UsedArguments Source # |
Instance details Defined in Clash.Primitives.Types Methods hashWithSalt :: Int -> UsedArguments -> Int Source # hash :: UsedArguments -> Int Source #
type Rep UsedArguments Source # |

Instance details

Defined in Clash.Primitives.Types

type Rep UsedArguments = D1 ('MetaData "UsedArguments" "Clash.Primitives.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "UsedArguments" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Int])) :+: C1 ('MetaCons "IgnoredArguments" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Int])))

type GuardedCompiledPrimitive = PrimitiveGuard CompiledPrimitive Source #

type GuardedResolvedPrimitive = PrimitiveGuard ResolvedPrimitive Source #

type PrimMap a = HashMap Text a Source #

A `PrimMap` maps primitive names to a `Primitive`

type UnresolvedPrimitive = Primitive Text ((TemplateFormat, BlackBoxFunctionName), Maybe TemplateSource) (Maybe Text) (Maybe TemplateSource) Source #

An unresolved primitive still contains pointers to files.

type ResolvedPrimitive = Primitive Text ((TemplateFormat, BlackBoxFunctionName), Maybe Text) () (Maybe Text) Source #

A parsed primitive does not contain pointers to filesystem files anymore, but holds uncompiled `BlackBoxTemplate`s and `BlackBoxFunction`s.

type ResolvedPrimMap = PrimMap GuardedResolvedPrimitive Source #

type CompiledPrimitive = Primitive BlackBoxTemplate BlackBox () (Int, BlackBoxFunction) Source #

A compiled primitive has compiled all templates and functions from its `ResolvedPrimitive` counterpart. The Int in the tuple is a hash of the (uncompiled) BlackBoxFunction.

type CompiledPrimMap = PrimMap GuardedCompiledPrimitive Source #