| 
   Copyright    :   ( C ) 2018 , Google Inc. 
   License      :   BSD2 ( see the file LICENSE ) 
   Maintainer   :     <  > 

   API for synthesis attributes ( sometimes refered 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 
   ( < github.com/clash-lang/clash-compiler/issues > ) . 

  Copyright   :  (C) 2018, Google Inc.
  License     :  BSD2 (see the file LICENSE)
  Maintainer  :  Christiaan Baaij <>

  API for synthesis attributes (sometimes refered 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
  (<github.com/clash-lang/clash-compiler/issues>).
-}
{-# LANGUAGE DeriveAnyClass #-}
# LANGUAGE DeriveGeneric #
# LANGUAGE PolyKinds      #
# LANGUAGE TypeOperators #
{-# LANGUAGE Safe #-}

module Clash.Annotations.SynthesisAttributes
  ( Attr(..)
  , Annotate
  ) where

import GHC.TypeLits (Symbol)

type Annotate a (attrs :: k) = a

-- | Synthesis attributes are directives passed to sythesis tools, such as
  Quartus . An example of such an attribute in  :
--
-- @
--   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 , /Attr / s
-- 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  argument can be specified by using a list .
-- For example:
--
-- @
-- Signal System Bool `Annotate`
--   [ StringAttr "chip_pin" "C4"
    ,  " direct_enable " True
    , IntegerAttr " max_depth " 512
--   , Attr "keep"
--   ]
-- @
--
  For Verilog see :
--     <>
--
  For  , see :
--     <>
--
-- Warning: This is an experimental feature, please report any unexpected or broken
  behavior to Clash 's GitHub page ( < github.com/clash-lang/clash-compiler/issues > ) .
data Attr
  = BoolAttr Symbol Bool
  -- ^ Attribute which argument is rendered as a bool. Example:
  -- <>
  | IntegerAttr Symbol Integer
  -- ^ Attribute which argument is rendered as a integer. Example:
  -- <>
  | StringAttr Symbol Symbol
  -- ^ Attribute which argument is rendered as a string. Example:
  -- <>
  | Attr Symbol
  -- ^ Attribute rendered as constant. Example:
  -- <>

# LANGUAGE DeriveAnyClass #
# LANGUAGE Safe #
 | Synthesis attributes are directives passed to sythesis tools, such as

 @
   attribute chip_pin : string;
   attribute chip_pin of sel : signal is "C4";
 @

 This would instruct the synthesis tool to map the wire /sel/ to pin /C4/, and
 are used. An example of the same annotation:

 @

 myFunc
     :: (Signal System Bool `Annotate` StringAttr "chip_pin" "C4")
     -> ...
 myFunc sel data = ...
 @

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

 For example:

 @
 Signal System Bool `Annotate`
   [ StringAttr "chip_pin" "C4"
   , Attr "keep"
   ]
 @

     <>

     <>

 Warning: This is an experimental feature, please report any unexpected or broken
 ^ Attribute which argument is rendered as a bool. Example:
 <>
 ^ Attribute which argument is rendered as a integer. Example:
 <>
 ^ Attribute which argument is rendered as a string. Example:
 <>
 ^ Attribute rendered as constant. Example:
 <>
| 
   Copyright    :   ( C ) 2018 , Google Inc. 
   License      :   BSD2 ( see the file LICENSE ) 
   Maintainer   :     <  > 

   API for synthesis attributes ( sometimes refered 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 
   ( < github.com/clash-lang/clash-compiler/issues > ) . 

  Copyright   :  (C) 2018, Google Inc.
  License     :  BSD2 (see the file LICENSE)
  Maintainer  :  Christiaan Baaij <>

  API for synthesis attributes (sometimes refered 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
  (<github.com/clash-lang/clash-compiler/issues>).
-}
# LANGUAGE DeriveGeneric #
# LANGUAGE PolyKinds      #
# LANGUAGE TypeOperators #

module Clash.Annotations.SynthesisAttributes
  ( Attr(..)
  , Annotate
  ) where

import GHC.TypeLits (Symbol)

type Annotate a (attrs :: k) = a

  Quartus . An example of such an attribute in  :
    attribute chip_pin of data : signal is " D1 , D2 , D3 , D4 " ;
  wire /data/ to pins /D1/ , /D2/ , /D3/ , and /D4/. To achieve this in Clash , /Attr / s
  import Clash . Annotations . SynthesisAttributes ( Attr ( .. ) , Annotate )
      - > ( Signal System Int4 ` Annotate ` StringAttr " chip_pin " " D1 , D2 , D3 , D4 " )
  { - # NOINLINE myFunc # - }
  NOINLINE pragma .
  Multiple attributes for the  argument can be specified by using a list .
    ,  " direct_enable " True
    , IntegerAttr " max_depth " 512
  For Verilog see :
  For  , see :
  behavior to Clash 's GitHub page ( < github.com/clash-lang/clash-compiler/issues > ) .
data Attr
  = BoolAttr Symbol Bool
  | IntegerAttr Symbol Integer
  | StringAttr Symbol Symbol
  | Attr Symbol
