clash-prelude-1.5.0: Clash: a functional hardware description language - Prelude library
Copyright(C) 2016 University of Twente
2017 QBayLogic Google Inc.
2017-2019 Myrtle Software Ltd
2021 QBayLogic B.V.
LicenseBSD2 (see the file LICENSE)
MaintainerQBayLogic B.V. <devops@qbaylogic.com>
Safe HaskellTrustworthy
LanguageHaskell2010

Clash.XException

Description

XException: An exception for uninitialized values

>>> show (errorX "undefined" :: Integer, 4 :: Int)
"(*** Exception: X: undefined
CallStack (from HasCallStack):
...
>>> showX (errorX "undefined" :: Integer, 4 :: Int)
"(undefined,4)"
Synopsis

XException: An exception for uninitialized values

newtype XException Source #

An exception representing an "uninitialized" value.

Constructors

XException String 

errorX :: HasCallStack => String -> a Source #

Like error, but throwing an XException instead of an ErrorCall

The ShowX methods print these error-values as undefined; instead of error'ing out with an exception.

isX :: a -> Either String a Source #

Evaluate a value to WHNF, returning Left msg if is a XException.

isX 42                  = Right 42
isX (XException msg)    = Left msg
isX (3, XException msg) = Right (3, XException msg)
isX (3, _|_)            = (3, _|_)
isX _|_                 = _|_

hasX :: NFData a => a -> Either String a Source #

Fully evaluate a value, returning Left msg if it throws XException. If you want to determine if a value contains undefined parts, use hasUndefined instead.

hasX 42                  = Right 42
hasX (XException msg)    = Left msg
hasX (3, XException msg) = Left msg
hasX (3, _|_)            = _|_
hasX _|_                 = _|_

If a data structure contains multiple XExceptions, the "first" message is picked according to the implementation of rnf.

maybeIsX :: a -> Maybe a Source #

Evaluate a value to WHNF, returning Nothing if it throws XException.

maybeIsX 42                  = Just 42
maybeIsX (XException msg)    = Nothing
maybeIsX (3, XException msg) = Just (3, XException msg)
maybeIsX (3, _|_)            = Just (3, _|_)
maybeIsX _|_                 = _|_

maybeHasX :: NFData a => a -> Maybe a Source #

Fully evaluate a value, returning Nothing if it throws XException.

maybeX 42                  = Just 42
maybeX (XException msg)    = Nothing
maybeX (3, XException msg) = Nothing
maybeX (3, _|_)            = _|_
maybeX _|_                 = _|_

fromJustX :: HasCallStack => Maybe a -> a Source #

Same as fromJust, but returns a bottom/undefined value that other Clash constructs are aware of.

undefined :: HasCallStack => a Source #

Call to errorX with default string

xToErrorCtx :: String -> a -> a Source #

Convert XException to ErrorCall

This is useful when tracking the source of XException that gets eaten up by pack inside of your circuit; since pack translates XException into undefined bits.

So for example if you have some large function f:

f a b = ... pack a ... pack b ...

Where it is basically an error if either a or b ever throws an XException, and so you want that to be reported the moment a or b is used, instead of it being thrown when evaluating the result of f, then do:

{-# LANGUAGE ViewPatterns #-}
f (xToErrorCtx "a is X" -> a) (xToErrorCtx "b is X" -> b) = ...

Where we pass an extra string, for context, to know which argument evaluated to an XException. We can also use BangPatterns to report the potential XException being thrown by a or b even earlier, i.e. when f is applied:

{-# LANGUAGE ViewPatterns, BangPatterns #-}
f (xToErrorCtx "a is X" -> !a) (xToErrorCtx "b is X" -> !b) = ...

NB: Fully synthesizable, so doesn't have to be removed before synthesis

Example

Expand
>>> :set -XViewPatterns -XDataKinds
>>> import Clash.Sized.BitVector
>>> import GHC.Stack
>>> :{
let h, h' :: Bit -> BitVector 8 -> BitVector 8
    h (xToErrorCtx "a is X" -> a) (xToErrorCtx "b is X" -> b) = slice d7 d0 (pack a ++# b)
    h' a b = slice d7 d0 (pack a ++# b)
:}
>>> h' (errorX "QQ") 3
0b0000_0011
>>> h (errorX "QQ") 3
*** Exception: a is X
X: QQ
CallStack (from HasCallStack):
  errorX, called at ...

xToError :: HasCallStack => a -> a Source #

Convert XException to ErrorCall

This is useful when tracking the source of XException that gets eaten up by pack inside of your circuit; since pack translates XException into undefined bits.

So for example if you have some large function f:

f a b = ... pack a ... pack b ...

Where it is basically an error if either a or b ever throws an XException, and so you want that to be reported the moment a or b is used, instead of it being thrown when evaluating the result of f, then do:

{-# LANGUAGE ViewPatterns #-}
f (xToError -> a) (xToError -> b) = ...

Unlike xToErrorCtx, where we have an extra String argument to distinguish one call to xToError to the other, xToError will use the CallStack mechanism to aid the user in distinguishing different call to xToError. We can also use BangPatterns to report the potential XException being thrown by a or b even earlier, i.e. when f is applied:

{-# LANGUAGE ViewPatterns, BangPatterns #-}
f (xToError -> !a) (xToError -> !b) = ...

NB: Fully synthesizable, so doesn't have to be removed before synthesis

Example

Expand
>>> :set -XViewPatterns -XDataKinds
>>> import Clash.Sized.BitVector
>>> import GHC.Stack
>>> :{
let f, g, h, h' :: HasCallStack => Bit -> BitVector 8 -> BitVector 8
    f = g
    g = h
    h (xToError -> a) (xToError -> b) = slice d7 d0 (pack a ++# b)
    h' a b = slice d7 d0 (pack a ++# b)
:}
>>> h' (errorX "QQ") 3
0b0000_0011
>>> f (errorX "QQ") 3
*** Exception: CallStack (from HasCallStack):
  xToError, called at ...
  h, called at ...
  g, called at ...
  f, called at ...
X: QQ
CallStack (from HasCallStack):
  errorX, called at ...

Printing XExceptions as undefined

class ShowX a where Source #

Like the Show class, but values that normally throw an XException are converted to undefined, instead of error'ing out with an exception.

>>> show (errorX "undefined" :: Integer, 4 :: Int)
"(*** Exception: X: undefined
CallStack (from HasCallStack):
...
>>> showX (errorX "undefined" :: Integer, 4 :: Int)
"(undefined,4)"

Can be derived using Generics:

{-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}

import Clash.Prelude
import GHC.Generics

data T = MkTA Int | MkTB Bool
  deriving (Show,Generic,ShowX)

Minimal complete definition

Nothing

Methods

showsPrecX :: Int -> a -> ShowS Source #

Like showsPrec, but values that normally throw an XException are converted to undefined, instead of error'ing out with an exception.

default showsPrecX :: (Generic a, GShowX (Rep a)) => Int -> a -> ShowS Source #

showX :: a -> String Source #

Like show, but values that normally throw an XException are converted to undefined, instead of error'ing out with an exception.

showListX :: [a] -> ShowS Source #

Like showList, but values that normally throw an XException are converted to undefined, instead of error'ing out with an exception.

Instances

Instances details
ShowX Bool Source # 
Instance details

Defined in Clash.XException

ShowX Char Source # 
Instance details

Defined in Clash.XException

ShowX Double Source # 
Instance details

Defined in Clash.XException

ShowX Float Source # 
Instance details

Defined in Clash.XException

ShowX Int Source # 
Instance details

Defined in Clash.XException

ShowX Int8 Source # 
Instance details

Defined in Clash.XException

ShowX Int16 Source # 
Instance details

Defined in Clash.XException

ShowX Int32 Source # 
Instance details

Defined in Clash.XException

ShowX Int64 Source # 
Instance details

Defined in Clash.XException

ShowX Integer Source # 
Instance details

Defined in Clash.XException

ShowX Natural Source # 
Instance details

Defined in Clash.XException

ShowX Word Source # 
Instance details

Defined in Clash.XException

ShowX Word8 Source # 
Instance details

Defined in Clash.XException

ShowX Word16 Source # 
Instance details

Defined in Clash.XException

ShowX Word32 Source # 
Instance details

Defined in Clash.XException

ShowX Word64 Source # 
Instance details

Defined in Clash.XException

ShowX () Source # 
Instance details

Defined in Clash.XException

Methods

showsPrecX :: Int -> () -> ShowS Source #

showX :: () -> String Source #

showListX :: [()] -> ShowS Source #

ShowX String Source # 
Instance details

Defined in Clash.XException

ShowX Bit Source # 
Instance details

Defined in Clash.Sized.Internal.BitVector

ShowX a => ShowX [a] Source # 
Instance details

Defined in Clash.XException

Methods

showsPrecX :: Int -> [a] -> ShowS Source #

showX :: [a] -> String Source #

showListX :: [[a]] -> ShowS Source #

ShowX a => ShowX (Maybe a) Source # 
Instance details

Defined in Clash.XException

ShowX a => ShowX (Ratio a) Source # 
Instance details

Defined in Clash.XException

ShowX a => ShowX (Complex a) Source # 
Instance details

Defined in Clash.XException

ShowX a => ShowX (Down a) Source # 
Instance details

Defined in Clash.XException

ShowX a => ShowX (Seq a) Source # 
Instance details

Defined in Clash.XException

Methods

showsPrecX :: Int -> Seq a -> ShowS Source #

showX :: Seq a -> String Source #

showListX :: [Seq a] -> ShowS Source #

KnownNat n => ShowX (BitVector n) Source # 
Instance details

Defined in Clash.Sized.Internal.BitVector

ShowX (Index n) Source # 
Instance details

Defined in Clash.Sized.Internal.Index

KnownNat n => ShowX (BNat n) Source # 
Instance details

Defined in Clash.Promoted.Nat

KnownNat n => ShowX (UNat n) Source # 
Instance details

Defined in Clash.Promoted.Nat

ShowX (SNat n) Source # 
Instance details

Defined in Clash.Promoted.Nat

ShowX (Unsigned n) Source # 
Instance details

Defined in Clash.Sized.Internal.Unsigned

ShowX (Signed n) Source # 
Instance details

Defined in Clash.Sized.Internal.Signed

(ShowX a, ShowX b) => ShowX (Either a b) Source # 
Instance details

Defined in Clash.XException

Methods

showsPrecX :: Int -> Either a b -> ShowS Source #

showX :: Either a b -> String Source #

showListX :: [Either a b] -> ShowS Source #

(ShowX a0, ShowX a1) => ShowX (a0, a1) Source # 
Instance details

Defined in Clash.XException

Methods

showsPrecX :: Int -> (a0, a1) -> ShowS Source #

showX :: (a0, a1) -> String Source #

showListX :: [(a0, a1)] -> ShowS Source #

ShowX a => ShowX (Vec n a) Source # 
Instance details

Defined in Clash.Sized.Vector

Methods

showsPrecX :: Int -> Vec n a -> ShowS Source #

showX :: Vec n a -> String Source #

showListX :: [Vec n a] -> ShowS Source #

ShowX a => ShowX (RTree n a) Source # 
Instance details

Defined in Clash.Sized.RTree

Methods

showsPrecX :: Int -> RTree n a -> ShowS Source #

showX :: RTree n a -> String Source #

showListX :: [RTree n a] -> ShowS Source #

(ShowX a0, ShowX a1, ShowX a2) => ShowX (a0, a1, a2) Source #

N.B.: The documentation only shows instances up to 3-tuples. By default, instances up to and including 12-tuples will exist. If the flag large-tuples is set instances up to the GHC imposed limit will exist. The GHC imposed limit is either 62 or 64 depending on the GHC version.

Instance details

Defined in Clash.XException

Methods

showsPrecX :: Int -> (a0, a1, a2) -> ShowS Source #

showX :: (a0, a1, a2) -> String Source #

showListX :: [(a0, a1, a2)] -> ShowS Source #

(size ~ (int + frac), KnownNat frac, Integral (rep size)) => ShowX (Fixed rep int frac) Source # 
Instance details

Defined in Clash.Sized.Fixed

Methods

showsPrecX :: Int -> Fixed rep int frac -> ShowS Source #

showX :: Fixed rep int frac -> String Source #

showListX :: [Fixed rep int frac] -> ShowS Source #

showsX :: ShowX a => a -> ShowS Source #

Like shows, but values that normally throw an XException are converted to undefined, instead of error'ing out with an exception.

printX :: ShowX a => a -> IO () Source #

Like print, but values that normally throw an XException are converted to undefined, instead of error'ing out with an exception

showsPrecXWith :: (Int -> a -> ShowS) -> Int -> a -> ShowS Source #

Use when you want to create a ShowX instance where:

  • There is no Generic instance for your data type
  • The Generic derived ShowX method would traverse into the (hidden) implementation details of your data type, and you just want to show the entire value as undefined.

Can be used like:

data T = ...

instance Show T where ...

instance ShowX T where
  showsPrecX = showsPrecXWith showsPrec

Strict evaluation

seqX :: a -> b -> b infixr 0 Source #

Like seq, however, whereas seq will always do:

seq  _|_              b = _|_

seqX will do:

seqX (XException msg) b = b
seqX _|_              b = _|_

seqErrorX :: a -> b -> b infixr 0 Source #

Like seqX, but will also catch ErrorCall exceptions which are thrown. This should be used with care.

seqErrorX (ErrorCall msg)  b = b
seqErrorX (XException msg) b = b
seqErrorX _|_              b = _|_

forceX :: NFDataX a => a -> a Source #

a variant of deepseqX that is useful in some circumstances:

forceX x = x `deepseqX` x

deepseqX :: NFDataX a => a -> b -> b infixr 0 Source #

deepseqX: fully evaluates the first argument, before returning the second. Does not propagate XExceptions.

rwhnfX :: a -> () Source #

Reduce to weak head normal form

Equivalent to \x -> seqX x ().

Useful for defining rnfX for types for which NF=WHNF holds.

defaultSeqX :: NFDataX a => a -> b -> b infixr 0 Source #

Either seqX or deepseqX depending on the value of the cabal flag '-fsuper-strict'. If enabled, defaultSeqX will be deepseqX, otherwise seqX. Flag defaults to false and thus seqX.

hwSeqX :: a -> b -> b infixr 0 Source #

Like seqX in simulation, but will force its first argument to be rendered in HDL. This is useful for components that need to be rendered in hardware, but otherwise have no meaning in simulation. An example of such a component would be an ILA: a component monitoring an internal signal of a design. The output of such a component (typically a unit) can be passed as the first argument to hwSeqX to ensure the ILA ends up in the generated HDL.

NB: the result of hwSeqX must (indirectly) be used at the very top of a design. If it's not, Clash will remove it like it does for any other unused circuit parts.

NB: Make sure the blackbox for the component with zero-width results uses RenderVoid

Structured undefined / deep evaluation with undefined values

class NFDataX a where Source #

Class that houses functions dealing with undefined values in Clash. See deepErrorX and rnfX.

Minimal complete definition

Nothing

Methods

deepErrorX :: HasCallStack => String -> a Source #

Create a value where all the elements have an errorX, but the spine is defined.

hasUndefined :: a -> Bool Source #

Determines whether any of parts of a given construct contain undefined parts. Note that a negative answer does not mean its bit representation is fully defined. For example:

>>> m = Nothing :: Maybe Bool
>>> hasUndefined m
False
>>> pack m
0b0.
>>> hasUndefined (pack m)
True

default hasUndefined :: (Generic a, GHasUndefined (Rep a)) => a -> Bool Source #

ensureSpine :: a -> a Source #

Create a value where at the very least the spine is defined. For example:

>>> spined = ensureSpine (errorX "?" :: (Int, Int))
>>> case spined of (_, _) -> 'a'
'a'
>>> fmap (const 'b') (ensureSpine undefined :: Vec 3 Int)
'b' :> 'b' :> 'b' :> Nil
>>> fmap (const 'c') (ensureSpine undefined :: RTree 2 Int)
<<'c','c'>,<'c','c'>>

For users familiar with lazyV: this is the generalized version of it.

default ensureSpine :: (Generic a, GEnsureSpine (Rep a)) => a -> a Source #

rnfX :: a -> () Source #

Evaluate a value to NF. As opposed to NFDatas rnf, it does not bubble up XExceptions.

default rnfX :: (Generic a, GNFDataX Zero (Rep a)) => a -> () Source #

Instances

Instances details
NFDataX Bool Source # 
Instance details

Defined in Clash.XException

NFDataX Char Source # 
Instance details

Defined in Clash.XException

NFDataX Double Source # 
Instance details

Defined in Clash.XException

NFDataX Float Source # 
Instance details

Defined in Clash.XException

NFDataX Int Source # 
Instance details

Defined in Clash.XException

NFDataX Int8 Source # 
Instance details

Defined in Clash.XException

NFDataX Int16 Source # 
Instance details

Defined in Clash.XException

NFDataX Int32 Source # 
Instance details

Defined in Clash.XException

NFDataX Int64 Source # 
Instance details

Defined in Clash.XException

NFDataX Integer Source # 
Instance details

Defined in Clash.XException

NFDataX Natural Source # 
Instance details

Defined in Clash.XException

NFDataX Word Source # 
Instance details

Defined in Clash.XException

NFDataX Word8 Source # 
Instance details

Defined in Clash.XException

NFDataX Word16 Source # 
Instance details

Defined in Clash.XException

NFDataX Word32 Source # 
Instance details

Defined in Clash.XException

NFDataX Word64 Source # 
Instance details

Defined in Clash.XException

NFDataX () Source # 
Instance details

Defined in Clash.XException

Methods

deepErrorX :: String -> () Source #

hasUndefined :: () -> Bool Source #

ensureSpine :: () -> () Source #

rnfX :: () -> () Source #

NFDataX All Source # 
Instance details

Defined in Clash.XException

NFDataX Any Source # 
Instance details

Defined in Clash.XException

NFDataX CUShort Source # 
Instance details

Defined in Clash.XException

NFDataX Half Source # 
Instance details

Defined in Clash.XException

NFDataX Bit Source # 
Instance details

Defined in Clash.Sized.Internal.BitVector

NFDataX a => NFDataX [a] Source # 
Instance details

Defined in Clash.XException

Methods

deepErrorX :: String -> [a] Source #

hasUndefined :: [a] -> Bool Source #

ensureSpine :: [a] -> [a] Source #

rnfX :: [a] -> () Source #

NFDataX a => NFDataX (Maybe a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Ratio a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Complex a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Min a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Max a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (First a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Last a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Option a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (First a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Last a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Dual a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Endo a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Sum a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Product a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Down a) Source # 
Instance details

Defined in Clash.XException

NFDataX a => NFDataX (Seq a) Source # 
Instance details

Defined in Clash.XException

KnownNat n => NFDataX (BitVector n) Source # 
Instance details

Defined in Clash.Sized.Internal.BitVector

NFDataX (Index n) Source # 
Instance details

Defined in Clash.Sized.Internal.Index

NFDataX (Unsigned n) Source # 
Instance details

Defined in Clash.Sized.Internal.Unsigned

NFDataX (Signed n) Source # 
Instance details

Defined in Clash.Sized.Internal.Signed

NFDataX b => NFDataX (a -> b) Source # 
Instance details

Defined in Clash.XException

Methods

deepErrorX :: String -> a -> b Source #

hasUndefined :: (a -> b) -> Bool Source #

ensureSpine :: (a -> b) -> a -> b Source #

rnfX :: (a -> b) -> () Source #

(NFDataX a, NFDataX b) => NFDataX (Either a b) Source # 
Instance details

Defined in Clash.XException

(NFDataX a0, NFDataX a1) => NFDataX (a0, a1) Source # 
Instance details

Defined in Clash.XException

Methods

deepErrorX :: String -> (a0, a1) Source #

hasUndefined :: (a0, a1) -> Bool Source #

ensureSpine :: (a0, a1) -> (a0, a1) Source #

rnfX :: (a0, a1) -> () Source #

(NFDataX a, NFDataX b) => NFDataX (Arg a b) Source # 
Instance details

Defined in Clash.XException

Methods

deepErrorX :: String -> Arg a b Source #

hasUndefined :: Arg a b -> Bool Source #

ensureSpine :: Arg a b -> Arg a b Source #

rnfX :: Arg a b -> () Source #

(NFDataX a, KnownNat n) => NFDataX (Vec n a) Source # 
Instance details

Defined in Clash.Sized.Vector

Methods

deepErrorX :: String -> Vec n a Source #

hasUndefined :: Vec n a -> Bool Source #

ensureSpine :: Vec n a -> Vec n a Source #

rnfX :: Vec n a -> () Source #

NFDataX a => NFDataX (Signal domain a) Source # 
Instance details

Defined in Clash.Signal.Internal

Methods

deepErrorX :: String -> Signal domain a Source #

hasUndefined :: Signal domain a -> Bool Source #

ensureSpine :: Signal domain a -> Signal domain a Source #

rnfX :: Signal domain a -> () Source #

(KnownNat d, NFDataX a) => NFDataX (RTree d a) Source # 
Instance details

Defined in Clash.Sized.RTree

Methods

deepErrorX :: String -> RTree d a Source #

hasUndefined :: RTree d a -> Bool Source #

ensureSpine :: RTree d a -> RTree d a Source #

rnfX :: RTree d a -> () Source #

(NFDataX a0, NFDataX a1, NFDataX a2) => NFDataX (a0, a1, a2) Source #

N.B.: The documentation only shows instances up to 3-tuples. By default, instances up to and including 12-tuples will exist. If the flag large-tuples is set instances up to the GHC imposed limit will exist. The GHC imposed limit is either 62 or 64 depending on the GHC version.

Instance details

Defined in Clash.XException

Methods

deepErrorX :: String -> (a0, a1, a2) Source #

hasUndefined :: (a0, a1, a2) -> Bool Source #

ensureSpine :: (a0, a1, a2) -> (a0, a1, a2) Source #

rnfX :: (a0, a1, a2) -> () Source #

NFDataX (rep (int + frac)) => NFDataX (Fixed rep int frac) Source # 
Instance details

Defined in Clash.Sized.Fixed

Methods

deepErrorX :: String -> Fixed rep int frac Source #

hasUndefined :: Fixed rep int frac -> Bool Source #

ensureSpine :: Fixed rep int frac -> Fixed rep int frac Source #

rnfX :: Fixed rep int frac -> () Source #