Hydra functional computer hardware description language

Hydra is a functional computer hardware description language for specifying the structure and behavior of synchronous 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 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) 2024 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.

Install 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/. This is the recommended way to install Haskell.

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.4.8
cabal --version
cabal-install version 3.10.3.0
compiled using version 3.10.3.0 of the Cabal library 

In case of difficulty

If you have a previous installation of ghc, and a new installation fails, try uninstalling the older version.

If you installed using chocolatey, the following might work:

choco upgrade ghc cabal -y

Install 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.7.zip). Put the file somewhere in your user workspace and unpack it, using the correct version number:

• On Linux: tar -xzf Hydra-i.j.k.tar.gz
• On Windows, right click and extract, or use zip, 7zip or tar

This will create a directory named Hydra-i.j.k 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-i.j.k
cabal install --lib

In a directory where you are running circuits, create a file named .ghci containing the following lines:

:set -package mtl
:set -package parsec
:set -package filepath
:set -package containers

Hydra installation problems

If you have a previous installation of Hydra, you are likely to get errors either on the cabal install –lib command, or when you run a circuit using a ghc command.

(See RemoveOldHydra in makefile.)

Open the installed package list in a text editor.

• On Windows, the file may have a path like this:

c:/Users/LOGINNAME/AppData/Roaming/ghc/x86_64-mingw32-9.2.3/environments/default/

• On Linux…
• On Macintosh…

Look for a line that looks like this:

package-id hydra-3.6.0-d409d1bd27eed5f13043a9ceb4699ee79e9625c3

There might be several similar lines. Delete those lines, and save the file. Now try again

• (In Hydra directory) cabal install –lib command
• (In Circuits directory) ghc -e main M1/M1run

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.

Hidden package

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

:set -package mtl
:set -package parsec
:set -package filepath
:set -package containers

Missing library

On some versions of Linux, the cabal install –lib command may fail with an error message like this:

/usr/bin/ld.gold: error: cannot find -lgmp
collect2: error: ld returned 1 exit status
`gcc' failed in phase `Linker'. (Exit code: 1)
Error: cabal: Failed to build hydra-3.5.7.

This means the linker was unable to find a library, which you can install:

sudo apt-get install libgmp3-dev

Conflict with previous installation

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-9.4.8/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

The normal way to run a circuit, say Add4Run, is to enter ghc -e main Add4Run. (It is conventional for the name of a circuit’s simulation driver to end in Run, so the circuit Add4 has a driver Add4Run.)

An alternative is to use ghci instead; this is 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.