Clash.Rewrite.Util

Utilities for rewriting: e.g. inlining, specialisation, etc.

Documentation

zoomExtra :: State extra a -> RewriteMonad extra a

Lift an action working in the _extra state to the RewriteMonad

findAccidentialShadows :: Term -> [[Id]]

Some transformations might erroneously introduce shadowing. For example, a transformation might result in:

let a = ... b = ... a = ...

where the last a, shadows the first, while Clash assumes that this can't happen. This function finds those constructs and a list of found duplicates.

apply

Arguments

:: String

Name of the transformation

-> Rewrite extra

Transformation to be applied

-> Rewrite extra

Record if a transformation is successfully applied

applyDebug

Arguments

:: DebugLevel

The current debugging level

-> Set String

Transformations to debug

-> Maybe (Int, Int)

Only print debug information for transformations [n, n+limit]. See flag documentation of "-fclash-debug-transformations-from" and "-fclash-debug-transformations-limit"

-> String

Name of the transformation

-> Term

Original expression

-> Bool

Whether the rewrite indicated change

-> Term

New expression

-> RewriteMonad extra Term

runRewrite

Arguments

:: String

Name of the transformation

-> InScopeSet

-> Rewrite extra

Transformation to perform

-> Term

Term to transform

-> RewriteMonad extra Term

Perform a transformation on a Term

runRewriteSession :: RewriteEnv -> RewriteState extra -> RewriteMonad extra a -> a

Evaluate a RewriteSession to its inner monad.

setChanged :: RewriteMonad extra ()

Notify that a transformation has changed the expression

changed :: a -> RewriteMonad extra a

Identity function that additionally notifies that a transformation has changed the expression

closestLetBinder :: Context -> Maybe Id

mkDerivedName :: TransformContext -> OccName -> TmName

mkTmBinderFor

Arguments

:: (MonadUnique m, MonadFail m)

=> InScopeSet

-> TyConMap

TyCon cache

-> Name a

Name of the new binder

-> Term

Term to bind

-> m Id

Make a new binder and variable reference for a term

mkBinderFor

Arguments

:: (MonadUnique m, MonadFail m)

=> InScopeSet

-> TyConMap

TyCon cache

-> Name a

Name of the new binder

-> Either Term Type

Type or Term to bind

-> m (Either Id TyVar)

Make a new binder and variable reference for either a term or a type

inlineBinders

Arguments

:: (Term -> LetBinding -> RewriteMonad extra Bool)

Property test

-> Rewrite extra

Inline the binders in a let-binding that have a certain property

isJoinPointIn

Arguments

:: Id

Id of the local binder

-> Term

Expression in which the binder is bound

-> Bool

Determine whether a binder is a join-point created for a complex case expression.

A join-point is when a local function only occurs in tail-call positions, and when it does, more than once.

tailCalls

Arguments

:: Id

Function to check

-> Term

Expression to check it in

-> Maybe Int

Count the number of (only) tail calls of a function in an expression. Nothing indicates that the function was used in a non-tail call position.

isVoidWrapper :: Term -> Bool

Determines whether a function has the following shape:

\(w :: Void) -> f a b c

i.e. is a wrapper around a (partially) applied function f, where the introduced argument w is not used by f

substituteBinders

Arguments

:: InScopeSet

-> [LetBinding]

Let-binders to substitute

-> [LetBinding]

Let-binders where substitution takes place

-> Term

Body where substitution takes place

-> ([LetBinding], ([LetBinding], Term))

1. Let-bindings that we wanted to substitute, but turned out to be recursive
2. 1 Let-binders where substitution took place
3. 2 Body where substitution took place

Inline the first set of binder into the second set of binders and into the body of the original let expression.

liftAndSubsituteBinders

Arguments

:: InScopeSet

-> [LetBinding]

Let-binders to lift, and substitute the lifted result

-> [LetBinding]

Lef-binders where substitution takes place

-> Term

Body where substitution takes place

-> RewriteMonad extra ([LetBinding], Term)

Lift the first set of binders to the level of global bindings, and substitute these lifted bindings into the second set of binders and the body of the original let expression.

isFromInt :: Text -> Bool

inlineOrLiftBinders

Arguments

:: (LetBinding -> RewriteMonad extra Bool)

Property test

-> (Term -> LetBinding -> Bool)

Test whether to lift or inline

• True: inline
• False: lift

-> Rewrite extra

liftBinding :: LetBinding -> RewriteMonad extra LetBinding

Create a global function for a Let-binding and return a Let-binding where the RHS is a reference to the new global function applied to the free variables of the original RHS

uniqAwayBinder :: BindingMap -> Name a -> Name a

Ensure that the Unique of a variable does not occur in the BindingMap

mkFunction

Arguments

:: TmName

Name of the function

-> SrcSpan

-> InlineSpec

-> Term

Term bound to the function

-> RewriteMonad extra Id

Name with a proper unique and the type of the function

Make a global function for a name-term tuple

addGlobalBind :: TmName -> Type -> SrcSpan -> InlineSpec -> Term -> RewriteMonad extra ()

Add a function to the set of global binders

cloneNameWithInScopeSet :: MonadUnique m => InScopeSet -> Name a -> m (Name a)

Create a new name out of the given name, but with another unique. Resulting unique is guaranteed to not be in the given InScopeSet.

cloneNameWithBindingMap :: MonadUnique m => BindingMap -> Name a -> m (Name a)

Create a new name out of the given name, but with another unique. Resulting unique is guaranteed to not be in the given BindingMap.

isUntranslatable

Arguments

:: Bool

String representable

-> Term

-> RewriteMonad extra Bool

Determine if a term cannot be represented in hardware

isUntranslatableType

Arguments

:: Bool

String representable

-> Type

-> RewriteMonad extra Bool

Determine if a type cannot be represented in hardware

specialise

Arguments

:: Lens' extra (Map (Id, Int, Either Term Type) Id)

Lens into previous specialisations

-> Lens' extra (VarEnv Int)

Lens into the specialisation history

-> Lens' extra Int

Lens into the specialisation limit

-> Rewrite extra

Specialise an application on its argument

specialise'

Arguments

:: Lens' extra (Map (Id, Int, Either Term Type) Id)

Lens into previous specialisations

-> Lens' extra (VarEnv Int)

Lens into specialisation history

-> Lens' extra Int

Lens into the specialisation limit

-> TransformContext

-> Term

Original term

-> (Term, [Either Term Type], [TickInfo])

Function part of the term, split into root and applied arguments

-> Either Term Type

Argument to specialize on

-> RewriteMonad extra Term

Specialise an application on its argument

normalizeTermTypes :: TyConMap -> Term -> Term

normalizeId :: TyConMap -> Id -> Id

specArgBndrsAndVars :: Either Term Type -> ([Either Id TyVar], [Either Term Type])

Create binders and variable references for free variables in specArg

whnfRW

Arguments

:: Bool

Whether the expression we're reducing to WHNF is the subject of a case expression.

-> TransformContext

-> Term

-> Rewrite extra

-> RewriteMonad extra Term

Evaluate an expression to weak-head normal form (WHNF), and apply a transformation on the expression in WHNF.

bindPureHeap :: TyConMap -> PureHeap -> Rewrite extra -> Rewrite extra

Binds variables on the PureHeap over the result of the rewrite

To prevent unnecessary rewrites only do this when rewrite changed something.

removeUnusedBinders :: [LetBinding] -> Term -> Maybe Term

Remove unused binders in given let-binding. Returns Nothing if no unused binders were found.

module Clash.Rewrite.WorkFree