clash-shockwaves
Copyright(C) 2025-2026 QBayLogic B.V.
LicenseBSD2 (see the file LICENSE)
MaintainerQBayLogic B.V. <devops@qbaylogic.com>
Safe HaskellNone
LanguageHaskell2010

Clash.Shockwaves

Description

Shockwaves is a system for typed waveforms in Clash. Clash.Shockwaves exports the minimum requirements for using Shockwaves.

For more options, see Clash.Shockwaves.Waveform, Clash.Shockwaves.Style, Clash.Shockwaves.LUT and Clash.Shockwaves.Trace.

For the HOWTO guides on using Shockwaves, check out the documentation in the GitHub repository.

Note: this exports the Clash.Shockwaves.Trace module, which creates name space collisions with Clash.Signal.Trace. Import qualified or selectively.

Synopsis

Waveform

class (Typeable a, BitPack a) => Waveform a where Source #

Waveform is the main class for making types displayable in the waveform viewer. The class is responsible for defining an appropriate translator and subsignal structure, as well as registering types.

To make a LUT approache possible, the class must also be able to translate values, and to register individual values.

By default, Generic is used to automatically derive this behaviour. Extra classes are provided to help implement lookup tables or common types, like numerical translators. Custom implementations are also very possible.

Minimal complete definition

Nothing

Methods

constructorStyles :: [WaveStyle] Source #

List of styles used for constructors.

Since assigning different constructors different colors is a very common usecase of the waveform style, this list can be overridden to provides styles for the constructors, in order. To not change a style, use WSDefault.

Instances

Instances details
Waveform Bit Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform ClockWave Source #

Control the styles of the clock wave through style variables clk_pre, clk_a and clk_b.

Instance details

Defined in Clash.Shockwaves.Internal.Trace.CRE

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform EnableWave Source #

Control the styles of the enable wave through style variables enable_on and enable_off.

Instance details

Defined in Clash.Shockwaves.Internal.Trace.CRE

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Int16 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Int32 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Int64 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Int8 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Word16 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Word32 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Word64 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Word8 Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Ordering Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform () Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Bool Source #

Configure styles through style variables bool_false and bool_true.

Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

BitPack Char => Waveform Char Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Double Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Float Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Int Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform Word Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

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

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform a => Waveform (Erroring a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform a => Waveform (Overflowing a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform a => Waveform (Saturating a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform a => Waveform (Wrapping a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform a => Waveform (Zeroing a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(KnownNat n, BitPack (SNat n)) => Waveform (SNat n) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

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

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(1 <= n, KnownNat n) => Waveform (Index n) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

KnownNat n => Waveform (Signed n) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

KnownNat n => Waveform (Unsigned n) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

KnownDomain dom => Waveform (CREWave dom) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Trace.CRE

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

KnownDomain dom => Waveform (ResetWave dom) Source #

Control the styles of the reset wave through style variables reset_on and reset_off.

Instance details

Defined in Clash.Shockwaves.Internal.Trace.CRE

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(WaveformConst a, BitPack a, Typeable a) => Waveform (WaveformForConst a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(Waveform a, WaveformLUT a, BitPack a, Typeable a) => Waveform (WaveformForLut a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform a => Waveform (Identity a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

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

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

Waveform a => Waveform (Maybe a) Source #

Configure styles through style variables maybe_nothing and maybe_just.

Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(Waveform a, KnownNat d, WaveformRTree (RTreeIsLeaf d) d a) => Waveform (RTree d a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

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

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(Waveform a, Waveform b) => Waveform (Either a b) Source #

Configure styles through style variables either_left and either_right.

Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(Waveform a1, Waveform a2) => Waveform (a1, a2) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(BitPack (Fixed r i f), KnownNat i, KnownNat f, Show (Fixed r i f), Typeable r) => Waveform (Fixed r i f) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(BitPack a, Typeable a, Typeable f, Typeable s, KnownNFormat f, KnownNSpacer s) => Waveform (WaveformForNumber f s a) Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

(Waveform a1, Waveform a2, Waveform a3) => Waveform (a1, a2, a3) Source #

NB: 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.Shockwaves.Internal.Waveform

Methods

typeName :: TypeName Source #

translator :: Translator Source #

constructorStyles :: [WaveStyle] Source #

width :: Int Source #

data WaveStyle Source #

The style in which a signal should be displayed.

Constructors

WSDefault

The default waveform style. It is rendered as WSNormal. This is the only style overwritten by TStyled.

WSError

An error value. Errors are propagated by translators.

WSHidden

Do not display any value, even if it exists.

WSInherit Natural

Copy the style of the nth subsignal.

WSNormal

A normal value.

WSWarn

A warning value.

WSUndef

An undefined value.

WSHighImp

A high impedance value.

WSDontCare

A value that does not matter.

WSWeak

A weakly defined value.

WSColor Color

A custom color. See Clash.Shockwaves.Style for more information.

WSVar String WaveStyle

A variable in a style configuration file, with a default.

Instances

Instances details
ToJSON WaveStyle Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Types

Methods

toJSON :: WaveStyle -> Value #

toEncoding :: WaveStyle -> Encoding #

toJSONList :: [WaveStyle] -> Value #

toEncodingList :: [WaveStyle] -> Encoding #

omitField :: WaveStyle -> Bool #

NFData WaveStyle Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Types

Methods

rnf :: WaveStyle -> () #

IsString WaveStyle Source #

A WaveStyle may be constructed from a value in various ways. Values starting with $ are treated as WSVar with WSDefault as fallback value. Hexadecimals and color names are used to create WSColor (see readColourName).

Instance details

Defined in Clash.Shockwaves.Internal.Types

Methods

fromString :: String -> WaveStyle #

Generic WaveStyle Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Types

Associated Types

type Rep WaveStyle 
Instance details

Defined in Clash.Shockwaves.Internal.Types

type Rep WaveStyle = D1 ('MetaData "WaveStyle" "Clash.Shockwaves.Internal.Types" "clash-shockwaves-1.1.0-inplace" 'False) (((C1 ('MetaCons "WSDefault" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "WSError" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WSHidden" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "WSInherit" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Natural)) :+: (C1 ('MetaCons "WSNormal" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WSWarn" 'PrefixI 'False) (U1 :: Type -> Type)))) :+: ((C1 ('MetaCons "WSUndef" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "WSHighImp" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WSDontCare" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "WSWeak" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "WSColor" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Color)) :+: C1 ('MetaCons "WSVar" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 WaveStyle))))))

Methods

from :: WaveStyle -> Rep WaveStyle x #

to :: Rep WaveStyle x -> WaveStyle #

Show WaveStyle Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Types

Methods

showsPrec :: Int -> WaveStyle -> ShowS #

show :: WaveStyle -> String #

showList :: [WaveStyle] -> ShowS #

Eq WaveStyle Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Types

Methods

(==) :: WaveStyle -> WaveStyle -> Bool #

(/=) :: WaveStyle -> WaveStyle -> Bool #

type Rep WaveStyle Source # 
Instance details

Defined in Clash.Shockwaves.Internal.Types

type Rep WaveStyle = D1 ('MetaData "WaveStyle" "Clash.Shockwaves.Internal.Types" "clash-shockwaves-1.1.0-inplace" 'False) (((C1 ('MetaCons "WSDefault" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "WSError" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WSHidden" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "WSInherit" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Natural)) :+: (C1 ('MetaCons "WSNormal" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WSWarn" 'PrefixI 'False) (U1 :: Type -> Type)))) :+: ((C1 ('MetaCons "WSUndef" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "WSHighImp" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WSDontCare" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "WSWeak" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "WSColor" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Color)) :+: C1 ('MetaCons "WSVar" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 WaveStyle))))))

Tracing

module Clash.Shockwaves.Trace

writeFileJSON :: ToJSON a => FilePath -> a -> IO () Source #

Re-export of encodeFile for cleaner naming in tracing functions.