diff options
| -rw-r--r-- | doc/ghw/index.rst | 37 | ||||
| -rw-r--r-- | doc/index.rst | 1 | ||||
| -rw-r--r-- | ghw/README.md | 12 |
3 files changed, 38 insertions, 12 deletions
diff --git a/doc/ghw/index.rst b/doc/ghw/index.rst new file mode 100644 index 000000000..af8a12384 --- /dev/null +++ b/doc/ghw/index.rst @@ -0,0 +1,37 @@ +.. program:: ghdl +.. _GHW: + +GHDL Waveform (GHW) +################### + +The most widespread format for dumping waveforms is Value Change Dump (VCD), defined in the Verilog language (IEEE Std +1364-1995) and extended six years later as Extended VCD (EVCD), defined in IEEE Std 1364-2001. +VCD is simple and compact, which allowed it to be used in fields other than Verilog simulation tools. +For instance, GHDL supports dumping VCD files. + +However, VCD/EVCD cannot handle certain signal types from the VHDL language. +There is neither any equivalent in the VHDL LRM. +So, the author of GHDL, Tristan Gingold, implemented an alternative format named GHW, for allowing all VHDL types to be +dumped. +He also contributed a reader to GTKWave based on ghwlib (see `gtkwave/gtkwave/search?q=ghwlib <https://github.com/gtkwave/gtkwave/search?q=ghwlib>`__ and `gtkwave/gtkwave: gtkwave3/src/ghw.c <https://github.com/gtkwave/gtkwave/blob/master/gtkwave3/src/ghw.c>`__), +which allows visualizing GHW waves . + +The GHW format is not completely fixed, and it might change slightly as new language features are implemented in GHDL +or as a result of internal tweaks. +Nevertheless, the GHDL codebase (:ghdlsrc:`grt/grt-waves.adb <grt/grt-waves.adb>`) is kept in sync with the utilities in subdir :ghdlsrc:`ghw <../ghw>`. + +.. TIP:: + In `nturley/ghw-notes <https://github.com/nturley/ghw-notes>`__, there is some work for defining the GHW format as a + Kaitai Struct (see `kaitai.io <https://kaitai.io/>`__). + +ghwlib +====== + +GHW reading features are provided as a shared library, which is built and installed with GHDL by default. + +ghwdump +======= + +For debugging and learning purposes, ghwdump uses ghdlib for dumping the content of GHW waves into text files. +ghwdump is also built and installed with GHDL by default. +It's used in the GHDL test suite for catching regressions. diff --git a/doc/index.rst b/doc/index.rst index a7a728a06..9b82d52ad 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -160,6 +160,7 @@ GHDL development/Directories Building GHDL <development/building/index> Python Interfaces <pyGHDL/pyGHDL> + ghw/index development/Debugging development/CodingStyle development/Scripts diff --git a/ghw/README.md b/ghw/README.md deleted file mode 100644 index 300e10a74..000000000 --- a/ghw/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# GHDL Wavefile helpers - -This subdir contains C helpers for managing GHDL Wavefiles (GHW). -These sources are used in GTKWave for reading GHW waves (see [gtkwave/gtkwave/search?q=ghwlib](https://github.com/gtkwave/gtkwave/search?q=ghwlib)). - -- `ghwlib.c` and `ghwlib.h` provide the reader library. -- `ghwdump.c` uses the library for dumping the content of GHW files in text, for debugging purposes. - -A shared library named `ghwlib.[so|dll]` and `ghwdump` are built and installed with GHDL by default. -Furthermore, `ghwdump` is used in the test suite. - -These helpers are independent from GHDL's codebase. However, the GHW format is not specified, so it might change as a result of internal tweaks in GHDL. Hence, it is strongly suggested to use the helpers provided in the GHDL installation. |