Troubleshooting and known limits

Last updated:

Installation and start-up

The command is not found

jhdl: command not found (Linux) or The term 'jhdl' is not recognized (Windows) means the bin folder is not on your PATH, or the terminal was opened before you changed it. Check the folder (Putting JanusHDL on the PATH) and open a new terminal. On Windows, an editor's built-in terminal may need the editor itself restarted to see the change.

The window does not start

• On Linux, a missing system library. jhdlw names the library and the command that installs it (Linux). The command line, jhdl, does not need it.
• No graphics card, or a remote session. The window draws with the graphics card when there is one, and in software otherwise. If it fails to start, or draws wrongly, choose the renderer yourself: jhdlw --renderer software (or set JHDL_RENDERER=software). --renderer gpu insists on a graphics card.
• Linux without a desktop. The window needs an X11 or Wayland session. On a build server, use jhdl, record with --wave, and open the recording on a desktop machine.
• A strange layout or a window off-screen. View → Reset the layout puts the tabs back; View → Bring every tab back into the main window gathers tab windows from monitors that are gone. To start from scratch, close the window and delete the settings file (Where JanusHDL keeps your settings).

Analysis

A name is not declared, or a library is empty

error[undeclared]: `my_pkg` is not declared in `work`
  = help: library `work` has no design units yet: analyze its sources into it first, before the files that use it

• The order of the files. A unit must be analyzed before the units that use it. Put the package first, or let jhdl-lsp --order FILES.f sort a file list (Analysis order).
• A library you did not analyze. UVVM, OSVVM, VUnit and vendor libraries are not built in: list their sources before yours (Libraries).
• The wrong library. A file analyzed into work is not in util. Check the library lines of your file list or project, and --work on the command line.

When a unit fails to analyze, each unit that needs it says so (p ... its analysis failed) and names the file with the errors to fix (Fix the first error first).

Code that other tools accepted is an error

JanusHDL reports what the VHDL standard forbids as an error. Read the message's help line: it says how to make the code legal and, where compatibility mode accepts the code, that --compat runs it as written (Compatibility mode). The usual cases:

Fix the code, or run with --compat, which makes each of these a warning. Warnings can then be hidden with --allow RULE.

UVVM stops with errors about shared variables

error[unprotected-shared-variable]: a shared variable must be of a protected type, not T_LOG_DESTINATION

UVVM needs compatibility mode: add --compat (or compat on in a project, or tick Compatibility mode in the Run dialog). Without it, the packages with such variables fail to analyze and every unit that uses them reports errors as well, so the output is long; the first error is the one that matters (UVVM).

A file uses VHDL-2019 directives

error[syntax]: tool directives are VHDL-2019; this file is analyzed as VHDL-2008

Run with --std 19, or give that file or its library VHDL-2019 in a project (VHDL versions).

A word is reserved

A name such as context, force, release, parameter, view or private is reserved in later VHDL versions. Code that uses one as a name analyzes as an older version: give that library its own version in a project (library legacy std=1993).

Running

The simulation never ends

A free-running clock always has something to do, so a testbench with one runs until it stops itself or reaches a stop time. End the testbench with std.env.finish (or stop), or give --stop-time. In the window, Pause (F6) or Stop (Shift+F5) it.

The exit code is 1, though the testbench says it passed

The exit code is 1 when any report or assertion of severity error or failure came up, also one the testbench made on purpose to check that an error is caught. Raise the level for such a testbench: --exit-level failure (Severity levels).

A generic is refused

error: generic period: `20` is not a value of type TIME: give a number and a unit, such as 20 ns, 20ns or 1.5 us (the units: fs, ps, ns, us, ms, sec, min, hr)

The message says which forms the generic's type takes; Generics lists them all. The usual causes: a time without its unit, a lower-case x for 'X' (character literals keep their case), a vector of the wrong length, or shell quoting that ate the quotes of x"A5" (write '-gINIT=x"A5"').

The run stops with a memory error

error: the simulation uses 4100 MiB, over the --max-memory limit of 4096 MiB; stopped (--max-memory 0 turns the limit off)

Each run stops at 4 GiB by default. If the design needs more, raise the limit (--max-memory 16G) or turn it off (--max-memory 0). A run that grows without end is often a testbench that keeps allocating (queues, scoreboards, line variables) without freeing.

The verdict changes with the process order

A testbench that passes under one --order-seed and fails under another has a race between processes: see Finding races.

Native code

Native code gives the same results as the interpreter, messages included. If a run with native code behaves differently from the same run with --jit off, that is a defect: please report it with the design.

A typed file cannot be opened

cannot open file "data.bin": it holds values of type INTEGER, not REAL (the element type of REAL_FILE). ...

A file of a type other than text and character holds a header that says what it holds (Files the design reads and writes). Read it with a file type of the element type it was written with. A typed file written by an earlier version of JanusHDL, or by another program, has no such header and is not opened: write it again with this version, or, for another program's binary data, read it as a file of character.

Waveforms

The insight panels say the recording has no structure

The panels need a waveform database written by this version: run in the window, or record with jhdl --wave. A VCD file, or a recording made by an earlier version, holds values only (What the panels need).

A signal in a wave setup shows as missing

The waveform has no signal with that path: it was renamed, or the setup is for another design. The row stays, so that the setup still serves other designs; fix the path, or remove the row.

The front ends and VUnit

• "not supported yet". The command, option or script command is not handled yet; the message names it. Verilog commands answer the same way.
• A script stops at if, foreach, proc or [...]. The front ends understand a small part of Tcl (Limits of the front ends). Move the control logic into the shell script that calls the simulator, or call jhdl with a file list or project.
• The wrong command runs. Another tool with the same command name comes first on the PATH. Put the JanusHDL compat folder first, and only one family's folder.

The editor and the language server

• The editor marks names from other files as undeclared. The editor analyzes a file as the current run does: the open project, else the last simulation run (Diagnostics). With no run, or for a file that is not among the run's files, names from other files are not known. Open the project, or run the file list, that the file belongs to.
• The language server does not see the design. It looks for the project or file list projectFile names, then a .jhdlproj in the workspace's top folder, then jhdl.f there (How the server finds your design). A project with an error is reported in the server's log. Check what it sees with jhdl-lsp --check FOLDER.

Known limits

What JanusHDL does not do yet. Where one of these is met, the message says so, by name.

Language

• A signal assignment, inside a procedure, to a signal that is not one of the procedure's parameters (for example, a procedure declared in a process that assigns a signal of the architecture). The run stops at it with assignments through procedures are not supported yet. Pass the signal as a parameter of class signal.
• A generic map in a package declaration (VHDL-2019).
• PSL fairness and strong directives are read but not checked.
• An attribute specification of a configuration is recorded, but the attribute cannot be read yet.
• A port with a resolution function of its own is not resolved on its own, and reading an out port gives its actual's value rather than the port's driving value.
• VHDL-2019 has the implementation reclaim objects no access value designates, deallocate only setting its parameter to null. JanusHDL keeps such objects, so a long VHDL-2019 run that allocates a lot grows in memory. (VHDL-2008 code frees objects at deallocate, as before.)
• Protected (IEEE 1735 encrypted) code is not decrypted.
• Verilog and SystemVerilog are not supported yet.

Command line

• --top names an entity or a configuration; to choose an architecture, use a configuration.
• On the command line, --std applies to every file; a VHDL version per library or file needs a project.

Files

• Typed files written by earlier versions of JanusHDL are not read; write them again. Text files and files of character are not affected.

The window

• A file list or VHDL file run from the window takes a VHDL version, generics and compatibility mode from the Run dialog; per-library versions, rule levels and the other options need a project.
• The window records each run into a temporary file; keep recordings with jhdl --wave.
• Extended VCD files ($dumpports) cannot be opened.

Language server and front ends

• Without a project, the language server analyzes every file as one VHDL version (its std option).
• The front ends' scripts understand a small part of Tcl; a design they open in the window does not run its scripts there.
• VUnit's --gui option is not supported.

Reporting a problem

A good report lets the problem be reproduced and fixed quickly. Please include:

1. The version: jhdl --version.
2. Your system: Windows or Linux, and which processor.
3. The exact command line, or the project file.
4. What jhdl printed, in full.
5. The smallest design that shows the problem. The determinism of JanusHDL means that a design that fails once fails every time, on any machine.

For a difference between native code and the interpreter, say whether it goes away with --jit off. For a race, give the seed (--order-seed N) that shows it.