clash-prelude-1.8.4: Clash: a functional hardware description language - Prelude library

Copyright | (C) 2018 Google Inc. 2021-2023 QBayLogic B.V.
License | BSD2 (see the file LICENSE)
Maintainer | QBayLogic B.V. <devops@qbaylogic.com>
Safe Haskell | None
Language | Haskell2010

Clash.Annotations.SynthesisAttributes

Description

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 (https://github.com/clash-lang/clash-compiler/issues).

Synopsis

- data Attr a
  - = BoolAttr a Bool
  - | IntegerAttr a Integer
  - | StringAttr a a
  - | Attr a
- type Annotate a (attrs :: k) = a
- annotate :: forall (n :: Nat) (dom :: Domain) a. Vec n (Attr String) -> Signal dom a -> Signal dom a
- markDebug :: forall (dom :: Domain) a. Signal dom a -> Signal dom a

# Documentation

data Attr a Source #

Synthesis attributes are directives passed to synthesis tools, such as Quartus. An example of such an attribute in VHDL:

    attribute chip_pin : string;
    attribute chip_pin of sel : signal is "C4";
    attribute chip_pin of data : signal is "D1, D2, D3, D4";

This would instruct the synthesis tool to map the wire sel to pin C4, and wire data to pins D1, D2, D3, and D4. To achieve this in Clash, Attrs are used. An example of the same annotation:

    import Clash.Annotations.SynthesisAttributes (Attr (..), Annotate )

    myFunc
        :: (Signal System Bool `Annotate` 'StringAttr "chip_pin" "C4")
        -> (Signal System Int4 `Annotate` 'StringAttr "chip_pin" "D1, D2, D3, D4")
        -> ...
    myFunc sel data = ...
    {-# NOINLINE myFunc #-}

To ensure this function will be rendered as its own module, do not forget a NOINLINE pragma.

Multiple attributes for the same argument can be specified by using a list. For example:

    Signal System Bool `Annotate`
      [ 'StringAttr "chip_pin" "C4"
      , 'BoolAttr "direct_enable" 'True
      , 'IntegerAttr "max_depth" 512
      , 'Attr "keep"
      ]

For Verilog see: https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir.htm

For VHDL, see: https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vhdl/vhdl_file_dir.htm

# Warnings

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

    f :: Signal System Bool `Annotate` 'StringAttr "chip_pin" "C4"
      -> Signal System Bool
    f x = id x -- Using a lambda, i.e. f = \x -> id x also works

will reliably show the annotation in the generated HDL, but

    g :: Signal System Bool `Annotate` 'StringAttr "chip_pin" "C4"
      -> Signal System Bool
    g = id

will not work.

This is an experimental feature, please report any unexpected or broken behavior to Clash's GitHub page (https://github.com/clash-lang/clash-compiler/issues).

Use `annotate` if you wish to annotate an intermediate signal. Its use is preferred over type level annotations.

Constructors

BoolAttr a Bool | Attribute which argument is rendered as a bool. Example: https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_direct_enable.htm
IntegerAttr a Integer | Attribute which argument is rendered as a integer. Example: https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_max_depth.htm
StringAttr a a | Attribute which argument is rendered as a string. Example: https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_chip.htm
Attr a | Attribute rendered as constant. Example: https://www.intel.com/content/www/us/en/programmable/quartushelp/current/index.htm#hdl/vlog/vlog_file_dir_keep.htm

#### Instances

Instances details

Functor Attr Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods fmap :: (a -> b) -> Attr a -> Attr b Source # (<$) :: a -> Attr b -> Attr a Source #
Lift a => Lift (Attr a :: Type) Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods lift :: Quote m => Attr a -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => Attr a -> Code m (Attr a) Source #
Binary a => Binary (Attr a) Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods put :: Attr a -> Put Source # get :: Get (Attr a) Source # putList :: [Attr a] -> Put Source #
NFData a => NFData (Attr a) Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods rnf :: Attr a -> () Source #
Generic (Attr a) Source # |

Instance details

Defined in Clash.Annotations.SynthesisAttributes

Associated Types

type Rep (Attr a) |

Instance details

Defined in Clash.Annotations.SynthesisAttributes

type Rep (Attr a) = D1 ('MetaData "Attr" "Clash.Annotations.SynthesisAttributes" "clash-prelude-1.8.4-1CKHk9HHRNIGPqhYHQsmcW" 'False) ((C1 ('MetaCons "BoolAttr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)) :+: C1 ('MetaCons "IntegerAttr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Integer))) :+: (C1 ('MetaCons "StringAttr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: C1 ('MetaCons "Attr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a))))

Methods

from :: Attr a -> Rep (Attr a) x Source #

to :: Rep (Attr a) x -> Attr a Source #

Show a => Show (Attr a) Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods showsPrec :: Int -> Attr a -> ShowS Source # show :: Attr a -> String Source # showList :: [Attr a] -> ShowS Source #
Eq a => Eq (Attr a) Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods (==) :: Attr a -> Attr a -> Bool Source # (/=) :: Attr a -> Attr a -> Bool Source #
Ord a => Ord (Attr a) Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods compare :: Attr a -> Attr a -> Ordering Source # (<) :: Attr a -> Attr a -> Bool Source # (<=) :: Attr a -> Attr a -> Bool Source # (>) :: Attr a -> Attr a -> Bool Source # (>=) :: Attr a -> Attr a -> Bool Source # max :: Attr a -> Attr a -> Attr a Source # min :: Attr a -> Attr a -> Attr a Source #
Hashable a => Hashable (Attr a) Source # |
Instance details Defined in Clash.Annotations.SynthesisAttributes Methods hashWithSalt :: Int -> Attr a -> Int Source # hash :: Attr a -> Int Source #
type Rep (Attr a) Source # |

Instance details

Defined in Clash.Annotations.SynthesisAttributes

type Rep (Attr a) = D1 ('MetaData "Attr" "Clash.Annotations.SynthesisAttributes" "clash-prelude-1.8.4-1CKHk9HHRNIGPqhYHQsmcW" 'False) ((C1 ('MetaCons "BoolAttr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)) :+: C1 ('MetaCons "IntegerAttr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Integer))) :+: (C1 ('MetaCons "StringAttr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: C1 ('MetaCons "Attr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a))))

type Annotate a (attrs :: k) = a Source #

annotate :: forall (n :: Nat) (dom :: Domain) a. Vec n (Attr String) -> Signal dom a -> Signal dom a Source #

Create a new identifier in HDL and inserts given synthesis attributes. The name of the intermediate signal can be influenced using naming functions in Clash.Magic.

markDebug :: forall (dom :: Domain) a. Signal dom a -> Signal dom a Source #

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: `keep`, `mark_debug`, `noprune`, and `preserve`.