Copyright	(C) 2017-2019 Myrtle Software 2022 QBayLogic B.V.
License	BSD2 (see the file LICENSE)
Maintainer	QBayLogic B.V. <[email protected]>
Safe Haskell	Safe
Language	Haskell2010
Extensions	TemplateHaskellQuotes ScopedTypeVariables BangPatterns ViewPatterns DataKinds InstanceSigs StandaloneDeriving DeriveDataTypeable DeriveFunctor DeriveTraversable DeriveFoldable DeriveGeneric DefaultSignatures DeriveAnyClass DeriveLift DerivingStrategies MagicHash KindSignatures PostfixOperators TupleSections TypeOperators ExplicitNamespaces ExplicitForAll LambdaCase BinaryLiterals TypeApplications

Clash.Annotations.Primitive

Description

Instruct the Clash compiler to look for primitive HDL templates provided inline or in a specified directory. For distribution of new packages with primitive HDL templates. Primitive guards can be added to warn on instantiating primitives.

Synopsis

dontTranslate :: PrimitiveGuard ()
hasBlackBox :: PrimitiveGuard ()
warnNonSynthesizable :: String -> PrimitiveGuard ()
warnAlways :: String -> PrimitiveGuard ()
data Primitive
- = Primitive [HDL] FilePath
- | InlinePrimitive [HDL] String
- | InlineYamlPrimitive [HDL] String
data HDL
- = SystemVerilog
- | Verilog
- | VHDL
data PrimitiveGuard a
- = DontTranslate
- | HasBlackBox [PrimitiveWarning] a
data PrimitiveWarning
- = WarnNonSynthesizable String
- | WarnAlways String
extractPrim :: PrimitiveGuard a -> Maybe a
extractWarnings :: PrimitiveGuard a -> [PrimitiveWarning]

Documentation

dontTranslate :: PrimitiveGuard () Source #

Marks value as not translatable. Clash will error if it finds a blackbox definition for it, or when it is forced to translate it. You can annotate a variable or function f like:

{-# ANN f dontTranslate #-}

hasBlackBox :: PrimitiveGuard () Source #

Marks a value as having a blackbox. Clash will error if it hasn't found a blackbox. You can annotate a variable or function f like:

{-# ANN f hasBlackBox #-}

warnNonSynthesizable :: String -> PrimitiveGuard () Source #

Marks value as non-synthesizable. This will trigger a warning if instantiated in a non-testbench context. You can annotate a variable or function f like:

{-# ANN f (warnNonSynthesizable "Tread carefully, user!") #-}

Implies hasBlackBox.

warnAlways :: String -> PrimitiveGuard () Source #

Always emit warning upon primitive instantiation. You can annotate a variable or function f like:

{-# ANN f (warnAlways "Tread carefully, user!") #-}

Implies hasBlackBox.

data Primitive Source #

The Primitive constructor instructs the clash compiler to look for primitive HDL templates in the indicated directory. InlinePrimitive is equivalent but provides the HDL template inline. They are intended for the distribution of new packages with primitive HDL templates.

Example of `Primitive`

You have some existing IP written in one of HDLs supported by Clash, and you want to distribute some bindings so that the IP can be easily instantiated from Clash.

You create a package which has a myfancyip.cabal file with the following stanza:

data-files: path/to/MyFancyIP.primitives
cpp-options: -DCABAL

and a MyFancyIP.hs module with the simulation definition and primitive.

module MyFancyIP where

import Clash.Prelude

myFancyIP :: ...
myFancyIP = ...
{-# NOINLINE myFancyIP #-}

The NOINLINE pragma is needed so that GHC will never inline the definition.

Now you need to add the following imports and ANN pragma:

#ifdef CABAL
import           Clash.Annotations.Primitive
import           System.FilePath
import qualified Paths_myfancyip
import           System.IO.Unsafe

{-# ANN module (Primitive [VHDL] (unsafePerformIO Paths_myfancyip.getDataDir </> "path" </> "to")) #-}
#endif

Add more files to the data-files stanza in your .cabal files and more ANN pragma's if you want to add more primitive templates for other HDLs

Example of `InlineYamlPrimitive`

The following example shows off an inline HDL primitive template. It uses the string-interpolate package for nicer multiline strings.

{-# LANGUAGE QuasiQuotes #-}
module InlinePrimitive where

import           Clash.Annotations.Primitive
import           Clash.Prelude
import           Data.String.Interpolate      (__i)

{-# ANN example (InlineYamlPrimitive [VHDL] [__i|
  BlackBox:
    kind: Declaration
    name: InlinePrimitive.example
    template: |-
      -- begin InlinePrimitive example:
      ~GENSYM[example][0] : block
      ~RESULT <= 1 + ~ARG[0];
      end block;
      -- end InlinePrimitive example
  |]) #-}
{-# NOINLINE example #-}
example :: Signal System (BitVector 2) -> Signal System (BitVector 2)
example = fmap succ

Constructors

Primitive [HDL] FilePath	Description of a primitive for a given `HDL`s in a file at `FilePath`
InlinePrimitive [HDL] String	Description of a primitive for a given `HDL`s as an inline JSON `String`
InlineYamlPrimitive [HDL] String	Description of a primitive for a given `HDL`s as an inline YAML `String`

Instances

Instances details

NFData Primitive Source #

Instance details

DontTranslate	Marks value as not translatable. Clash will error if it finds a blackbox definition for it, or when it is forced to translate it.
HasBlackBox [PrimitiveWarning] a	Marks a value as having a blackbox. Clash will error if it hasn't found a blackbox.

WarnNonSynthesizable String	Marks value as non-synthesizable. This will trigger a warning if instantiated in a non-testbench context.
WarnAlways String	Always emit warning upon primitive instantiation.

Documentation

Example of Primitive

Example of InlineYamlPrimitive

Instances

Instances

Instances

Instances

Example of `Primitive`

Example of `InlineYamlPrimitive`