clash-lib-1.8.4: Clash: a functional hardware description language - As a library

Copyright | (C) 2021-2023 QBayLogic B.V.
License | BSD2 (see the file LICENSE)
Maintainer | QBayLogic B.V. <devops@qbaylogic.com>
Safe Haskell | None
Language | Haskell2010

Clash.Driver.Manifest

Description

Functions to read, write, and handle manifest files.

Synopsis

- data PortDirection
  - = In
  - | Out
  - | InOut
- data ManifestPort = ManifestPort {
  - mpName :: Text
  - mpTypeName :: Text
  - mpDirection :: PortDirection
  - mpWidth :: Int
  - mpIsClock :: Bool
  - mpDomain :: Maybe Text
  }
- newtype FilesManifest = FilesManifest [(FilePath, ByteString)]
- data Manifest = Manifest {
  - manifestHash :: ByteString
  - successFlags :: (Int, Int)
  - ports :: [ManifestPort]
  - componentNames :: [Text]
  - topComponent :: Text
  - fileNames :: [(FilePath, ByteString)]
  - domains :: HashMap Text VDomainConfiguration
  - transitiveDependencies :: [Text]
  }
- unsafeFromHexDigest :: Text -> ByteString
- toHexDigest :: ByteString -> Text
- parseFiles :: Object -> Parser [(FilePath, ByteString)]
- data UnexpectedModification
  - = Modified FilePath
  - | Added FilePath
  - | Removed FilePath
- mkManifestPort :: Backend backend => backend -> Identifier -> HWType -> PortDirection -> ManifestPort
- manifestFilename :: IsString a => a
- mkManifest :: Backend backend => backend -> HashMap Text VDomainConfiguration -> ClashOpts -> Component -> [Component] -> [Id] -> [(FilePath, ByteString)] -> ByteString -> Manifest
- pprintUnexpectedModification :: UnexpectedModification -> String
- pprintUnexpectedModifications :: Int -> [UnexpectedModification] -> String
- readFreshManifest :: [TopEntityT] -> (BindingMap, Id) -> CompiledPrimMap -> ClashOpts -> UTCTime -> FilePath -> IO (Maybe [UnexpectedModification], Maybe Manifest, ByteString)
- isUserModified :: FilePath -> FilesManifest -> IO [UnexpectedModification]
- readManifest :: FromJSON a => FilePath -> IO (Maybe a)
- writeManifest :: FilePath -> Manifest -> IO ()
- serializeManifest :: Manifest -> Text

# Documentation

data PortDirection Source #

Constructors

In |
Out |
InOut |

#### Instances

Instances details

FromJSON PortDirection Source # |
Instance details Defined in Clash.Driver.Manifest Methods parseJSON :: Value -> Parser PortDirection Source # parseJSONList :: Value -> Parser [PortDirection] Source # omittedField :: Maybe PortDirection Source #
ToJSON PortDirection Source # |
Instance details Defined in Clash.Driver.Manifest Methods toJSON :: PortDirection -> Value Source # toEncoding :: PortDirection -> Encoding Source # toJSONList :: [PortDirection] -> Value Source # toEncodingList :: [PortDirection] -> Encoding Source # omitField :: PortDirection -> Bool Source #
Generic PortDirection Source # |

Instance details

Defined in Clash.Driver.Manifest

Associated Types

type Rep PortDirection |
Instance details Defined in Clash.Driver.Manifest type Rep PortDirection = D1 ('MetaData "PortDirection" "Clash.Driver.Manifest" "clash-lib-1.8.4-CsViYhmcYd4KTpfwGN07cn" 'False) (C1 ('MetaCons "In" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "Out" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InOut" 'PrefixI 'False) (U1 :: Type -> Type)))

Methods

from :: PortDirection -> Rep PortDirection x Source #

to :: Rep PortDirection x -> PortDirection Source #

Read PortDirection Source # |
Instance details Defined in Clash.Driver.Manifest Methods readsPrec :: Int -> ReadS PortDirection Source # readList :: ReadS [PortDirection] Source # readPrec :: ReadPrec PortDirection Source # readListPrec :: ReadPrec [PortDirection] Source #
Show PortDirection Source # |
Instance details Defined in Clash.Driver.Manifest Methods showsPrec :: Int -> PortDirection -> ShowS Source # show :: PortDirection -> String Source # showList :: [PortDirection] -> ShowS Source #
Eq PortDirection Source # |
Instance details Defined in Clash.Driver.Manifest Methods (==) :: PortDirection -> PortDirection -> Bool Source # (/=) :: PortDirection -> PortDirection -> Bool Source #
type Rep PortDirection Source # |
Instance details Defined in Clash.Driver.Manifest type Rep PortDirection = D1 ('MetaData "PortDirection" "Clash.Driver.Manifest" "clash-lib-1.8.4-CsViYhmcYd4KTpfwGN07cn" 'False) (C1 ('MetaCons "In" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "Out" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InOut" 'PrefixI 'False) (U1 :: Type -> Type)))

data ManifestPort Source #

Constructors

ManifestPort |

Fields

- mpName :: Text

  Port name (as rendered in HDL)

- mpTypeName :: Text

  Type name (as rendered in HDL)

- mpDirection :: PortDirection

  Port direction (in out inout)

- mpWidth :: Int

  Port width in bits

- mpIsClock :: Bool

  Is this port a clock?

- mpDomain :: Maybe Text

  Domain this port belongs to. This is currently only included for clock, reset, and enable ports. TODO: add to all ports originally defined as a `Signal` too.

#### Instances

Instances details

FromJSON ManifestPort Source # |
Instance details Defined in Clash.Driver.Manifest Methods parseJSON :: Value -> Parser ManifestPort Source # parseJSONList :: Value -> Parser [ManifestPort] Source # omittedField :: Maybe ManifestPort Source #
ToJSON ManifestPort Source # |
Instance details Defined in Clash.Driver.Manifest Methods toJSON :: ManifestPort -> Value Source # toEncoding :: ManifestPort -> Encoding Source # toJSONList :: [ManifestPort] -> Value Source # toEncodingList :: [ManifestPort] -> Encoding Source # omitField :: ManifestPort -> Bool Source #
Read ManifestPort Source # |
Instance details Defined in Clash.Driver.Manifest Methods readsPrec :: Int -> ReadS ManifestPort Source # readList :: ReadS [ManifestPort] Source # readPrec :: ReadPrec ManifestPort Source # readListPrec :: ReadPrec [ManifestPort] Source #
Show ManifestPort Source # |
Instance details Defined in Clash.Driver.Manifest Methods showsPrec :: Int -> ManifestPort -> ShowS Source # show :: ManifestPort -> String Source # showList :: [ManifestPort] -> ShowS Source #
Eq ManifestPort Source # |
Instance details Defined in Clash.Driver.Manifest Methods (==) :: ManifestPort -> ManifestPort -> Bool Source # (/=) :: ManifestPort -> ManifestPort -> Bool Source #

newtype FilesManifest Source #

Just the `fileNames` part of `Manifest`

Constructors

FilesManifest [(FilePath, ByteString)] |

#### Instances

Instances details

FromJSON FilesManifest Source # |
Instance details Defined in Clash.Driver.Manifest Methods parseJSON :: Value -> Parser FilesManifest Source # parseJSONList :: Value -> Parser [FilesManifest] Source # omittedField :: Maybe FilesManifest Source #

data Manifest Source #

Information about the generated HDL between (sub)runs of the compiler

Constructors

Manifest |

Fields

- manifestHash :: ByteString

  Hash digest of the TopEntity and all its dependencies.

- successFlags :: (Int, Int)

  Compiler flags used to achieve successful compilation:

  - opt_inlineLimit
  - opt_specLimit
- ports :: [ManifestPort]

  Ports in the generated `TopEntity`.

- componentNames :: [Text]

  Names of all the generated components for the `TopEntity` (does not include the names of the components of the `TestBench` accompanying the `TopEntity`).

  This list is reverse topologically sorted. I.e., a component might depend on any component listed before it, but not after it.

- topComponent :: Text

  Design entry point. This is usually the component annotated with a `TopEntity` annotation.

- fileNames :: [(FilePath, ByteString)]

  Names and hashes of all the generated files for the `TopEntity`. Hashes are SHA256.

  This list is reverse topologically sorted. I.e., a component might depend on any component listed before it, but not after it.

- domains :: HashMap Text VDomainConfiguration

  Domains encountered in design

- transitiveDependencies :: [Text]

  Dependencies of this design (fully qualified binder names). Is a transitive closure of all dependencies.

  This list is reverse topologically sorted. I.e., a component might depend on any component listed before it, but not after it.

#### Instances

Instances details

FromJSON Manifest Source # |
Instance details Defined in Clash.Driver.Manifest Methods parseJSON :: Value -> Parser Manifest Source # parseJSONList :: Value -> Parser [Manifest] Source # omittedField :: Maybe Manifest Source #
ToJSON Manifest Source # |
Instance details Defined in Clash.Driver.Manifest Methods toJSON :: Manifest -> Value Source # toEncoding :: Manifest -> Encoding Source # toJSONList :: [Manifest] -> Value Source # toEncodingList :: [Manifest] -> Encoding Source # omitField :: Manifest -> Bool Source #
Read Manifest Source # |
Instance details Defined in Clash.Driver.Manifest Methods readsPrec :: Int -> ReadS Manifest Source # readList :: ReadS [Manifest] Source # readPrec :: ReadPrec Manifest Source # readListPrec :: ReadPrec [Manifest] Source #
Show Manifest Source # |
Instance details Defined in Clash.Driver.Manifest Methods showsPrec :: Int -> Manifest -> ShowS Source # show :: Manifest -> String Source # showList :: [Manifest] -> ShowS Source #
Eq Manifest Source # |
Instance details Defined in Clash.Driver.Manifest Methods (==) :: Manifest -> Manifest -> Bool Source # (/=) :: Manifest -> Manifest -> Bool Source #

unsafeFromHexDigest :: Text -> ByteString Source #

Decode a hex digest to a ByteString. Returns a broken digest if the decode fails - hence it being marked as unsafe.

toHexDigest :: ByteString -> Text Source #

Encode a ByteString to a hex digest.

parseFiles :: Object -> Parser [(FilePath, ByteString)] Source #

Parse `files` part of a Manifest file

data UnexpectedModification Source #

Constructors

Modified FilePath | Clash generated file was modified
Added FilePath | Non-clash generated file was added
Removed FilePath | Clash generated file was removed

#### Instances

Instances details

Show UnexpectedModification Source # |
Instance details Defined in Clash.Driver.Manifest Methods showsPrec :: Int -> UnexpectedModification -> ShowS Source # show :: UnexpectedModification -> String Source # showList :: [UnexpectedModification] -> ShowS Source #

mkManifestPort Source #

Arguments

:: Backend backend |
=> backend | Backend used to lookup port type names
-> Identifier | Port name
-> HWType | Port type
-> PortDirection |
-> ManifestPort |

manifestFilename :: IsString a => a Source #

Filename manifest file should be written to and read from

mkManifest Source #

Arguments

:: Backend backend |
=> backend | Backend used to lookup port type names
-> HashMap Text VDomainConfiguration | Domains encountered in design
-> ClashOpts | Options Clash was run with
-> Component | Component of top entity
-> [Component] | All other entities
-> [Id] | Names of dependencies (transitive closure)
-> [(FilePath, ByteString)] | Files and their hashes
-> ByteString | Hash returned by `readFreshManifest`
-> Manifest | New manifest

pprintUnexpectedModification :: UnexpectedModification -> String Source #

Pretty print an unexpected modification as a list item.

pprintUnexpectedModifications :: Int -> [UnexpectedModification] -> String Source #

Pretty print a list of unexpected modifications. Print a maximum of n modifications.

readFreshManifest Source #

Arguments

:: [TopEntityT] | This top entity plus all that depend on it.
-> (BindingMap, Id) | Core expressions and entry point. Any changes in the call graph will trigger a recompile.
-> CompiledPrimMap | Any changes in any primitive will trigger a recompile.
-> ClashOpts | Certain options will trigger recompiles if changed
-> UTCTime | Clash modification date
-> FilePath | Path to manifest file.
-> IO (Maybe [UnexpectedModification], Maybe Manifest, ByteString) | ( Nothing if no manifest file was found , Nothing on stale cache, disabled cache, or not manifest file found )

Reads a manifest file. Does not return manifest file if:

- Caching is disabled through `-fclash-no-cache`.
- Manifest could not be found.
- Cache is stale. This could be triggered by any of the given arguments.

Raises an exception if the manifest file or any of the files it is referring to was inaccessible.

isUserModified :: FilePath -> FilesManifest -> IO [UnexpectedModification] Source #

Determines whether the HDL directory the given `LocatedManifest` was found in contains any user made modifications. This is used by Clash to protect the user against lost work.

readManifest :: FromJSON a => FilePath -> IO (Maybe a) Source #

Read a manifest file from disk. Returns `Nothing` if file does not exist. Any other IO exception is re-raised.

writeManifest :: FilePath -> Manifest -> IO () Source #

Write manifest file to disk

serializeManifest :: Manifest -> Text Source #

Serialize a manifest.

TODO: This should really yield a `ByteString`.