About Hydra

Hydra is a functional computer hardware description language for specifying the structure and behavior of digital circuits. It supports several levels of abstraction, including logic gates, register transfer level, datapath and control, and processors. There are tools for simulating circuits, generating netlists, and emulating instruction set architectures. It is an embedded domain specific language implemented using Haskell.

• The User Guide is available online at https://jtod.github.io/home/Hydra/UserGuide/HydraUserGuide.html. The Guide is in development, and this online link may give a newer version than the one in the installation directory.
• The User Guide is also available in the installation directory ./docs/UserGuide/HydraUserGuide.html
• The API reference gives types of the exported definitions. If you build using cabal, it will be in the the dist-newstyle directory. The path depends on software versions, but may be something like this: ./dist-newstyle/build/x86_64-windows/ghc-9.2.3/hydra-3.4.16/doc/html/hydra/index.html. If you install using cabal, it should also be placed in the standard location for Haskell API references.

This is free and open source software released under the GPL-3 license.

• Author: John T. O’Donnell, School of Computing Science, University of Glasgow
• Copyright (c) 2022 John T. O’Donnell
• Author’s home page: https://jtod.github.io/index.html
• License: This software is free and open source, released under the GPL-3 license. See LICENSE.txt.
• Source code repository: https://github.com/jtod/Hydra
• Version: see Hydra.cabal

Installation

Hydra runs in a shell using a command line interface. Any shell can be used; the examples use the bash shell.

Haskell

Hydra requires the ghc toolset for Haskell, including ghc and cabal. Haskell installers for Macintosh, Windows, and Linux are available at https://www.haskell.org/ghcup/.

For Windows, an alternative way to install Haskell is to use chocolatey; see https://hub.zhox.com/posts/introducing-haskell-dev/. If you have chocolatey installed, you can use it to install Haskell easily. Run these commands in Windows PowerShell with administrator privileges:

choco install ghc --force -y
choco install cabal --force -y

• -y tells choco to answer with y automatically when it needs permission to do something. Without the -y, it doesn’t actually ask permission and the whole installation fails.
• --force shouldn’t be necessary but seems to be needed if installing after a failed installation attempt.

Verify that Haskell is working

$ ghc --version
The Glorious Glasgow Haskell Compilation System, version 9.2.3
$ cabal --version
cabal-install version 3.6.2.0
compiled using version 3.6.2.0 of the Cabal library

In case of difficulty

If you have a previous installation of ghc, and a new installation fails, the following might work:

choco upgrade ghc cabal -y

Hydra

The Hydra source code is available at https://github.com/jtod/Hydra. See the Releases section on the right side of the page and click on the latest release. Download the source code file (in the Assets section), which is available in both zip and .tar.gz format. The installation file is Hydra-i.j.k.zip (or .tgz), where i.j.k is the version number (for example, Hydra-3.5.2.zip). Put the file somewhere in your user workspace and unpack it, using the correct version number:

• On Linux: tar -xzf Hydra-3.5.2.tar.gz
• On Windows use zip, 7zip or tar

This will create a directory named Hydra-3.5.2 that contains documentation (docs directory and examples directory), the source code (src directory), and build tools. Install using these commands (but use the right version number for Hydra):

cd Hydra-3.5.2
cabal install --lib
cabal haddock

Verify that Hydra is working

The following commands should simulate a 4-bit word adder for several clock cycles, with different inputs during each cycle.

$ cd examples/adder
$ ghc -e main Add4Run

In case of difficulty

See the user guides for ghc and cabal for more information. The ghc-pkg list command shows the installed packages.

Sometimes an installation may fail if there was a previous installation. If this happens, find the ghc environment default file, which is located at a path similar to the following (with your username and the right version numbers):

Linux:

~/.ghc/x86_64-linux-8.8.3/environments/default 

Windows:

C:/Users/username/AppData/Roaming/ghc/x86_64-mingw32-9.2.3/environments/default

Open this file in a text editor and find the line containing an entry for hydra, which should look something like this:

package-id hydra-3.4.5-VeryLongHashKey

Delete the lines for hydra, save the default file, and try the cabal install --lib command again.

Alternative: using ghci

Instead of using the batch command ghc -e main Add4Run (where Add4Run is the name of a simulation driver), an alternative is to use the interactive Haskell interpreter:

$ ghci
ghci> :load Add4Run
ghci> :main
ghci> :quit

The ghci interpreter offers a number of debugging and tracing tools. See the GHC User Guide for details.

If you get a message saying that there are “hidden packages”, copy the following into a file named .ghci

:set -package mtl
:set -package parsec
:set -package ansi-terminal

Alternative: using cabal

You can turn a directory with a circuit and simulation driver into a cabal package by defining some metadata files. Once this is done, you can then execute the driver using the command cabal run driver, where driver is replaced by the actual name of the simulation driver. One advantage of this method is that you can put command line arguments on the cabal run command, which you cannot do with the ghc -e main. See the M1 processor circuit directory for an example.