| Copyright | (C) 2025-2026 QBayLogic B.V. |
|---|---|
| License | BSD2 (see the file LICENSE) |
| Maintainer | QBayLogic B.V. <devops@qbaylogic.com> |
| Safe Haskell | None |
| Language | Haskell2010 |
Clash.Shockwaves.Waveform
Description
Everything needed to create custom implementations of Waveform.
Synopsis
- class (Typeable a, BitPack a) => Waveform a where
- translate :: (Waveform a, BitPack a) => a -> Translation
- translateBin :: Waveform a => BitList -> Translation
- hasGeneratedLut :: Waveform a => Bool
- translateBinT :: Translator -> BitList -> Translation
- hasGeneratedLutT :: Translator -> Bool
- data Translation = Translation Render [(SubSignal, Translation)]
- type Render = Maybe (Value, WaveStyle, Prec)
- data WaveStyle
- type Value = String
- type Prec = Integer
- type SubSignal = String
- data Translator = Translator Int TranslatorVariant
- data TranslatorVariant
- = TRef TypeName TypeRef
- | TLut LUTName (Maybe LUT) TypeRef
- | TSum [Translator]
- | TAdvancedSum {
- index :: Slice
- defTrans :: Translator
- rangeTrans :: [(ISlice, Translator)]
- | TProduct { }
- | TArray { }
- | TAdvancedProduct {
- sliceTrans :: [(Slice, Translator)]
- hierarchy :: [(SubSignal, Int)]
- valueParts :: [ValuePart]
- preco :: Prec
- | TDuplicate SubSignal Translator
- | TStyled WaveStyle Translator
- | TChangeBits {
- bits :: BitPart
- sub :: Translator
- | TNumber {
- format :: NumberFormat
- spacer :: NumberSpacer
- prefix :: String
- warn :: Bool
- | TConst Translation
- newtype Structure = Structure [(SubSignal, Structure)]
- structure :: Waveform a => Structure
- structureT :: Translator -> Structure
- data NumberFormat
- type DecSpacer = 'Just '(3, "_")
- type HexSpacer = 'Just '(2, "_")
- type OctSpacer = 'Just '(4, "_")
- type BinSpacer = 'Just '(8, "_")
- type NoSpacer = 'Nothing :: Maybe NSPair
- type SpacerEvery (n :: k) = 'Just '(n, "_")
- data ValuePart
- data BitPart
- bitSize :: BitPack a => Int
- pprintT :: Translator -> String
- defaultTranslator :: (Waveform a, WaveformG (Rep a ())) => Translator
- withConstructorStyles :: [WaveStyle] -> Translator -> Translator
- inheritSingleFieldStyle :: Translator -> Translator
- noConstructorSubsignals :: Bool -> Translator -> Translator
- renameFields :: [[String]] -> Translator -> Translator
- defaultTypeName :: forall {k} (a :: k). Typeable a => TypeName
- tRef :: Waveform a => Translator
- tDup :: SubSignal -> Translator -> Translator
- tStyled :: WaveStyle -> Translator -> Translator
- tConst :: Render -> Translator
- class (BitPack a, Typeable a) => WaveformConst a where
- data WaveformForConst a
- newtype WaveformForNumber (f :: NumberFormat) (s :: Maybe NSPair) a = WaveformForNumber a
The Waveform class
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
translator :: Translator Source #
The translator used for the data type. Must match the structure value.
default translator :: WaveformG (Rep a ()) => Translator Source #
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
translate :: (Waveform a, BitPack a) => a -> Translation Source #
Function to translate values. This function creates a translation from the binary representation of the data using translateBin, and the translator.
translateBin :: Waveform a => BitList -> Translation Source #
Translate binary data. Normally, this simply translates the value according to the translator. For LUTs, this involves translating the value back to the original type and translating it using a specially defined translation function.
hasGeneratedLut :: Waveform a => Bool Source #
Check if the type requires values to be added to LUTs.
translateBinT :: Translator -> BitList -> Translation Source #
Translate a BitList using the provided translator.
hasGeneratedLutT :: Translator -> Bool Source #
Test if there is a LUT translator in a translator (following references).
Translations
data Translation Source #
Translation of a value.
The translation consists of a Render value (the representation of the value itself)
and a list of subsignal translations.
Constructors
| Translation Render [(SubSignal, Translation)] |
Instances
type Render = Maybe (Value, WaveStyle, Prec) Source #
Rendered value. This can be Nothing is the value does not exists,
or a tuple of the text representation, style, and precedence.
The style in which a signal should be displayed.
Constructors
| WSDefault | The default waveform style. It is rendered as |
| 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
| ToJSON WaveStyle Source # | |||||
| NFData WaveStyle Source # | |||||
Defined in Clash.Shockwaves.Internal.Types | |||||
| IsString WaveStyle Source # | A | ||||
Defined in Clash.Shockwaves.Internal.Types Methods fromString :: String -> WaveStyle # | |||||
| Generic WaveStyle Source # | |||||
Defined in Clash.Shockwaves.Internal.Types Associated Types
| |||||
| Show WaveStyle Source # | |||||
| Eq WaveStyle Source # | |||||
| type Rep WaveStyle Source # | |||||
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)))))) | |||||
Translators
data Translator Source #
A translator. The translator has a width, indicating the number of bits it
translates, as well as a TranslatorVariant that determines the translation algorithm.
Constructors
| Translator Int TranslatorVariant |
Instances
| ToJSON Translator Source # | |
Defined in Clash.Shockwaves.Internal.Types Methods toJSON :: Translator -> Value # toEncoding :: Translator -> Encoding # toJSONList :: [Translator] -> Value # toEncodingList :: [Translator] -> Encoding # omitField :: Translator -> Bool # | |
| Show Translator Source # | |
Defined in Clash.Shockwaves.Internal.Types Methods showsPrec :: Int -> Translator -> ShowS # show :: Translator -> String # showList :: [Translator] -> ShowS # | |
data TranslatorVariant Source #
The translation algorithm used. Translator variants determine how the bits are interpreted, split, manipulated, and in the end, translatated and displayed in the waveform viewer.
Constructors
| TRef TypeName TypeRef | Use the translator of a different type. Note that the width value of the
|
| TLut LUTName (Maybe LUT) TypeRef | A reference to a lookup table. Implement |
| TSum [Translator] | Select one translator to be used based on the first bits of the binary representation. Translate the rest of the bits using the selected translator. To be exact, if k translators are provided, ceil(log2(k)) bits will be consumed to select the translator. No subsignals for the translators are created. Keep in mind that problems may occur if two translators specify subsignals with identical names. |
| TAdvancedSum | Use The selected translator is passed the full binary.
|
Fields
| |
| TProduct | Split the binary data into separate fields, translate each of these, and join together the values. Specifically, for each of the listed translators, consume as many bits as specified by the translator, then pass on the rest of the bits to the other translators. The value is constructed from the values of the subtranslators. A start, stop and separator string can be specified, as well as optional labels to put in front of the different values. Example: data T = T{a::Bool,b::Bool}
translatorVariantT = TProduct
{ subs = [("a",Bool,"b",Bool)],
, start = "T{"
, sep = ","
, stop = "}"
, labels = ["a=","b="]
, preci = -1
, preco = 11
}
|
Fields
| |
| TArray | An array value. This behaves much like |
Fields
| |
| TAdvancedProduct | Advance product type. First, a number of slices of the binary are translated. Then, the subsignals are picked from these translations, and the value is constructed from fixed strings and values from the translators.
|
Fields
| |
| TDuplicate SubSignal Translator | Translate the binary data using the translator specified, and duplicate
the value into a subsignal of the provided name. This duplication applies
the |
| TStyled WaveStyle Translator | Apply a style to a translation, replacing only |
| TChangeBits | Modify the binary input of the contained translator
The binary data is modified using |
Fields
| |
| TNumber | Translate the binary data as an integer. |
Fields
| |
| TConst Translation | A constant translation value. The binary value provided is completely ignored. |
Instances
| Show TranslatorVariant Source # | |
Defined in Clash.Shockwaves.Internal.Types Methods showsPrec :: Int -> TranslatorVariant -> ShowS # show :: TranslatorVariant -> String # showList :: [TranslatorVariant] -> ShowS # | |
Signal structure
A structure value that shows what subsignals are present.
Instances
structureT :: Translator -> Structure Source #
Return the Structure implied by a Translator. Useful for determining
the structure of a constant translation.
Translator-specific types
data NumberFormat Source #
Different number formats.
Constructors
| NFSig | A signed decimal value. |
| NFUns | An unsigned decimal value. |
| NFHex | A hexadecimal value. Supports partially undefined values. |
| NFOct | An octal value. Supports partially undefined values. |
| NFBin | A binary value. Supports partially undefined values. |
Instances
| ToJSON NumberFormat Source # | |||||
Defined in Clash.Shockwaves.Internal.Types Methods toJSON :: NumberFormat -> Value # toEncoding :: NumberFormat -> Encoding # toJSONList :: [NumberFormat] -> Value # toEncodingList :: [NumberFormat] -> Encoding # omitField :: NumberFormat -> Bool # | |||||
| NFData NumberFormat Source # | |||||
Defined in Clash.Shockwaves.Internal.Types Methods rnf :: NumberFormat -> () # | |||||
| Generic NumberFormat Source # | |||||
Defined in Clash.Shockwaves.Internal.Types Associated Types
| |||||
| Show NumberFormat Source # | |||||
Defined in Clash.Shockwaves.Internal.Types Methods showsPrec :: Int -> NumberFormat -> ShowS # show :: NumberFormat -> String # showList :: [NumberFormat] -> ShowS # | |||||
| type Rep NumberFormat Source # | |||||
Defined in Clash.Shockwaves.Internal.Types type Rep NumberFormat = D1 ('MetaData "NumberFormat" "Clash.Shockwaves.Internal.Types" "clash-shockwaves-1.1.0-inplace" 'False) ((C1 ('MetaCons "NFSig" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "NFUns" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "NFHex" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "NFOct" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "NFBin" 'PrefixI 'False) (U1 :: Type -> Type)))) | |||||
type SpacerEvery (n :: k) = 'Just '(n, "_") Source #
Add _ every n digits.
Parts of the value of TAdvancedProduct.
Constructors
| VPLit String | A literal string. |
| VPRef Int Prec | The value of a subtranslation parsed with outer precedence. |
Parts of the binary output of TChangeBits.
Each constructor modifies bits in a certain way.
More may be added later.
Constructors
| BPIn | Return the input binary. |
| BPLit BitList | Return the |
| BPSlice Slice BitPart | Return a slice of the input. **Important**: slice indices start to the left, i.e. with the MSB! |
| BPConcat [BitPart] | Pass the binary data onto multiple |
| BPHasUndefined BitPart | Return `1` if there are undefined bits in the binary. |
| BPReverse BitPart | Return bits in reverse order. |
| BPInvert BitPart | Invert 0 and 1. |
| BPAnd [BitPart] | Bitwise and. If values of different lengths are provided, values are zero-padded on the left.
Short-cirtuits ( |
| BPOr [BitPart] | Bitwise or. If values of different lengths are provided, values are zero-padded on the left.
Short-cirtuits ( |
| BPXor [BitPart] | Bitwise xor. If multiple values of different lengths are provided, values are zero-padded on the left. |
| BPOneHot Slice BitPart | Turn a binary value into a one-hot signal based on the provided range. This essentially loops over all values in the range, creating a 1 iff the input BitPart's result is equal to that value. I.e. BPOneHot (0,3) "10" results in "001". |
| BPNHot Slice BitPart | Turn a binary value into a n-hot signal based on the provided range. This essentially loops over all values in the range, creating a 1 iff the input BitPart's result is less than or equal to that value. |
| BPIf BitPart BitPart BitPart BitPart | Switch bitparts based on the first bit in the condition bitpart: `BPIf (true) (false) (undef) (cond)` |
Creating Translators
pprintT :: Translator -> String Source #
Debug function for pretty printing Translators.
The output of this function may change. It is merely intended as a debug tool
when creating and modifying translators.
defaultTranslator :: (Waveform a, WaveformG (Rep a ())) => Translator Source #
Return the default translator that is derived for a data type. This default can be modified to obtain a slightly different translator.
withConstructorStyles :: [WaveStyle] -> Translator -> Translator Source #
inheritSingleFieldStyle :: Translator -> Translator Source #
Wrap constructors with a single field in the WSInherit 0 style.
Ignores any structures that are wrapped in a TStyled translator.
noConstructorSubsignals :: Bool -> Translator -> Translator Source #
Remove constructor subsignals from a (generated) translator.
This results in all constructor field subsignals becoming direct subsignals of the toplevel signal.
Set rename to True to add the constructor's name as a prefix to the signal name.
Essentially, this function searches through TStyled and TSum for any TDuplicate translators to remove.
If renaming subsignals, it then searches through TStyled to rename subsignals in TProduct.
renameFields :: [[String]] -> Translator -> Translator Source #
Rename constructor fields. This is particularly useful for non-record types.
The input is a list of a list of field names, per constructor.
Errors if the number of constructors/fields does not match the structure of the Translator.
For translators other than TProduct, use an empty list of fieldnames.
defaultTypeName :: forall {k} (a :: k). Typeable a => TypeName Source #
Obtain the default name of a type. The name consists of a unique fingerprint (which is safe to use) and a human readable representation of the type (which may not be unique if multiple sources define the same types).
tRef :: Waveform a => Translator Source #
Generate a translator reference for a type.
Also checks whether the translator width matches the value of bitSize for
the type: if not, the function errors.
tDup :: SubSignal -> Translator -> Translator Source #
Wrap a Translator in a TDuplicate variant translator with the
provided subsignal name.
tStyled :: WaveStyle -> Translator -> Translator Source #
Wrap a Translator in a TStyled variant translator with the
provided style.
tConst :: Render -> Translator Source #
Create a constant translator that consumes 0 bits and has no subsignals.
Special Waveform instances
class (BitPack a, Typeable a) => WaveformConst a where Source #
Helper class for defining a constant translation value. To use this, derive Waveform via WaveformForConst.
Minimal complete definition
Methods
constTrans :: Translation Source #
The constant translation value. Overwrite this if the translation has subsignals.
Constant render value. Overwrite this if the constant value has no subsignals.
Instances
| WaveformConst () Source # | |
Defined in Clash.Shockwaves.Internal.Waveform | |
| (KnownNat n, BitPack (SNat n)) => WaveformConst (SNat n) Source # | |
Defined in Clash.Shockwaves.Internal.Waveform | |
data WaveformForConst a Source #
Helper class for deriving Waveform for types implementing WaveformConst.
Instances
| BitPack a => BitPack (WaveformForConst a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform Associated Types
Methods pack :: WaveformForConst a -> BitVector (BitSize (WaveformForConst a)) # unpack :: BitVector (BitSize (WaveformForConst a)) -> WaveformForConst a # | |||||
| (WaveformConst a, BitPack a, Typeable a) => Waveform (WaveformForConst a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform | |||||
| Generic (WaveformForConst a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform Associated Types
Methods from :: WaveformForConst a -> Rep (WaveformForConst a) x # to :: Rep (WaveformForConst a) x -> WaveformForConst a # | |||||
| type BitSize (WaveformForConst a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform type BitSize (WaveformForConst a) = CLog 2 (GConstructorCount (Rep (WaveformForConst a))) + GFieldSize (Rep (WaveformForConst a)) | |||||
| type Rep (WaveformForConst a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform type Rep (WaveformForConst a) = D1 ('MetaData "WaveformForConst" "Clash.Shockwaves.Internal.Waveform" "clash-shockwaves-1.1.0-inplace" 'True) (C1 ('MetaCons "WfConst" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a))) | |||||
newtype WaveformForNumber (f :: NumberFormat) (s :: Maybe NSPair) a Source #
Helper class for deriving Waveform for numerical types.
Options are provided at the type level (signed, format).
Example:
deriving via WaveformForNumber NFSig ('Just '(3,"_")) instance Waveform (Signed 3)
Constructors
| WaveformForNumber a |
Instances
| BitPack a => BitPack (WaveformForNumber f s a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform Associated Types
Methods pack :: WaveformForNumber f s a -> BitVector (BitSize (WaveformForNumber f s a)) # unpack :: BitVector (BitSize (WaveformForNumber f s a)) -> WaveformForNumber f s a # | |||||
| (BitPack a, Typeable a, Typeable f, Typeable s, KnownNFormat f, KnownNSpacer s) => Waveform (WaveformForNumber f s a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform | |||||
| Generic (WaveformForNumber f s a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform Associated Types
Methods from :: WaveformForNumber f s a -> Rep (WaveformForNumber f s a) x # to :: Rep (WaveformForNumber f s a) x -> WaveformForNumber f s a # | |||||
| type BitSize (WaveformForNumber f s a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform type BitSize (WaveformForNumber f s a) = CLog 2 (GConstructorCount (Rep (WaveformForNumber f s a))) + GFieldSize (Rep (WaveformForNumber f s a)) | |||||
| type Rep (WaveformForNumber f s a) Source # | |||||
Defined in Clash.Shockwaves.Internal.Waveform type Rep (WaveformForNumber f s a) = D1 ('MetaData "WaveformForNumber" "Clash.Shockwaves.Internal.Waveform" "clash-shockwaves-1.1.0-inplace" 'True) (C1 ('MetaCons "WaveformForNumber" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a))) | |||||