GHDL Bug: Assertion Error With --keep-hierarchy=no

by Alex Johnson 51 views

Introduction

In this article, we will delve into a specific issue encountered while using GHDL, a versatile VHDL simulator. The problem arises when attempting to synthesize a design with the --keep-hierarchy=no option, which leads to an assertion error. This error can be disruptive, especially in complex projects where hierarchy flattening is desired for optimization or other reasons. We will explore the details of the issue, how to reproduce it, the context in which it occurs, and potential solutions or workarounds. Understanding this bug is crucial for developers and engineers who rely on GHDL for their VHDL projects, ensuring they can effectively use the tool and avoid unexpected errors.

The Problem: Assertion Error with --keep-hierarchy=no

When using GHDL with the --keep-hierarchy=no option, an assertion error can occur during the synthesis process. This command-line option is intended to flatten the design hierarchy, which can be useful for optimizing the synthesized output or for compatibility with certain tools and flows. However, in certain scenarios, this flattening process triggers an internal assertion within GHDL, causing the synthesis to fail. This issue can be particularly problematic in large and complex designs where hierarchical structures are prevalent. The error message, typically displayed in the console output, indicates that an ADA.ASSERTIONS.ASSERTION_ERROR has been raised, specifically within the synth-vhdl_decls.adb file at line 263. This suggests a problem in the part of GHDL's synthesis engine that handles VHDL declarations when hierarchy flattening is enabled. Understanding the root cause of such an error is essential for GHDL users to effectively troubleshoot and work around the issue, ensuring smooth progress in their VHDL projects. By carefully examining the circumstances under which the error occurs, developers can gain valuable insights into GHDL's behavior and potential limitations.

How to Reproduce the Issue

To reproduce this GHDL assertion error, follow these steps:

  1. Download the GRLIB library: Begin by downloading the GRLIB library from https://download.gaisler.com/products/GRLIB/bin/grlib-gpl-2025.2-b4298.tar.gz. GRLIB is a comprehensive set of IP cores and components commonly used in embedded system design, providing a suitable test case for triggering the GHDL bug.

  2. Navigate to the design directory: After downloading and extracting the GRLIB archive, change your current directory to grlib-gpl-2025.2-b4298/designs/noelv-generic. This directory contains the specific design files that exhibit the issue with GHDL.

  3. Run the make ghdl command: Execute the command make ghdl within the directory. This command initiates the build process using GHDL, which includes compiling and synthesizing the VHDL code. The make utility automates the build process, ensuring that all necessary steps are performed in the correct order.

  4. Execute the synthesis command: Run the following GHDL synthesis command:

     ghdl --synth --out=verilog -fexplicit --ieee=synopsys --mb-comments \
 --keep-hierarchy=no --warn-no-binding --workdir=gnu/work --work=work \
 -Pgnu/grlib -Pgnu/synplify -Pgnu/techmap -Pgnu/wizl -Pgnu/eth \
 -Pgnu/opencores -Pgnu/gaisler -Pgnu/work \
 work.noelvmp

    This command instructs GHDL to synthesize the work.noelvmp design while applying several options. The --synth flag enables synthesis mode, --out=verilog specifies Verilog as the output format, -fexplicit ensures explicit entity instantiation, --ieee=synopsys sets the IEEE library style to Synopsys, and --mb-comments includes comments in the generated output. The critical option here is --keep-hierarchy=no, which directs GHDL to flatten the design hierarchy during synthesis. The --warn-no-binding option enables warnings for unbound components, --workdir=gnu/work sets the working directory, and --work=work specifies the logical library name. The -P flags include various library paths required for the GRLIB design. This synthesis command is specifically crafted to trigger the assertion error, making it an effective means of reproducing the bug.

By following these steps, you should be able to consistently reproduce the assertion error in GHDL when using the --keep-hierarchy=no option. This reproducible scenario allows for further investigation and potential solutions to be explored.

Context of the Issue

To fully understand the issue, it's important to consider the context in which it occurs. Here's a breakdown of the relevant information:

  • Operating System (OS): The specific OS on which the error occurs is relevant, as it can sometimes be related to platform-specific issues or library dependencies. While the original report didn't explicitly mention the OS, it's crucial to note that the bug was reproduced on a Linux system. This suggests that the issue might be more prevalent or specific to Linux environments, although it could potentially occur on other operating systems as well. Further testing on different platforms (e.g., Windows, macOS) would be beneficial to determine the scope of the problem.

  • Origin of GHDL: The origin of the GHDL installation is another important factor. There are several ways to obtain GHDL, including package managers, pre-built binaries, and building from source. Each method can result in different versions, configurations, and dependencies, which might influence the behavior of the tool. In this particular case, the GHDL version was built from sources, specifically from the commit 3b69efeb2a218a51f027d148d8bd20b22a2deb9b. This information is crucial because it allows developers to pinpoint the exact version of GHDL that exhibits the bug, facilitating debugging and patching efforts. When reporting issues, always include the origin and version of GHDL to provide a clear understanding of the environment.

  • GHDL Bug Report: The GHDL bug report provides detailed information about the error encountered. It indicates that the GHDL release is 6.0.0-dev (5.1.1.r173.g3b69efeb2.dirty) [Dunoon edition], which is a development version. Development versions often contain the latest features and bug fixes but might also include new, undiscovered issues. The GHDL version was compiled with GNAT (GNU Ada Translator) version 15.0.1 20250404 (experimental) and targeted x86_64-linux-gnu. This detailed information about the compiler and target architecture is essential for understanding the build environment and potential compatibility issues. The command line used to trigger the bug is also provided, which is critical for reproducing the issue. The exception ADA.ASSERTIONS.ASSERTION_ERROR was raised, specifically at synth-vhdl_decls.adb:263, indicating the location of the error within GHDL's source code. This level of detail is invaluable for GHDL developers when investigating and resolving the bug.

By understanding these contextual details, we can better analyze the potential causes of the assertion error and work towards a solution.

Analyzing the GHDL Bug

The provided bug report includes a crucial section that helps in analyzing the GHDL bug:

******************** GHDL Bug occurred ***************************
Please report this bug on https://github.com/ghdl/ghdl/issues
GHDL release: 6.0.0-dev (5.1.1.r173.g3b69efeb2.dirty) [Dunoon edition]
Compiled with GNAT Version: 15.0.1 20250404 (experimental)
Target: x86_64-linux-gnu
/home/jonathan/Work/riscv-verification/noelv-verilator/grlib-gpl-2025.2-b4298/designs/noelv-generic/
Command line:
ghdl --synth --out=verilog -fexplicit --ieee=synopsys --mb-comments --keep-hierarchy=no --warn-no-binding --workdir=gnu/work --work=work -Pgnu/grlib -Pgnu/synplify -Pgnu/techmap -Pgnu/wizl -Pgnu/eth -Pgnu/opencores -Pgnu/gaisler -Pgnu/work work.noelvmp
Exception ADA.ASSERTIONS.ASSERTION_ERROR raised
Exception information:
raised ADA.ASSERTIONS.ASSERTION_ERROR : synth-vhdl_decls.adb:263
******************************************************************

This block provides a wealth of information for debugging the issue. Let's break it down:

  • GHDL Release: The GHDL version is 6.0.0-dev (5.1.1.r173.g3b69efeb2.dirty) [Dunoon edition]. This indicates that a development version of GHDL is being used. Development versions often contain the latest features and bug fixes but may also have undiscovered issues. The dirty suffix suggests that the build was made from a modified source tree, which could introduce additional variability.
  • Compiler: GHDL was compiled with GNAT Version 15.0.1 20250404 (experimental). GNAT is the GNU Ada Translator, and the version used is an experimental one. This might be a factor in the bug, as experimental compilers may have their own set of issues. Compatibility between GHDL and the GNAT compiler is crucial, and an experimental version might not be fully tested.
  • Target: The target architecture is x86_64-linux-gnu, indicating a 64-bit Linux system. This is important for understanding the environment in which the bug occurs. Platform-specific issues can arise due to differences in memory management, system calls, or library implementations. Knowing the target architecture helps narrow down potential causes.
  • Command Line: The command line used to invoke GHDL is provided, which is essential for reproducing the bug. It clearly shows that the --keep-hierarchy=no option was used, which is the key to triggering the assertion error. The other options provide context about the synthesis settings and library paths used in the project. By examining the command line, developers can ensure they are using the same settings when attempting to reproduce the bug.
  • Exception: The exception raised is ADA.ASSERTIONS.ASSERTION_ERROR, and it occurred in the file synth-vhdl_decls.adb at line 263. This is a critical piece of information, as it pinpoints the exact location in GHDL's source code where the assertion failed. The file name synth-vhdl_decls.adb suggests that the error is related to the synthesis process and, more specifically, to the handling of VHDL declarations. Assertions are used in software to check for conditions that should always be true, and an assertion failure indicates a violation of these conditions. In this case, the assertion failure in synth-vhdl_decls.adb likely means that some internal state or data structure is not in the expected state during synthesis with hierarchy flattening.

By carefully analyzing this information, developers can start to form hypotheses about the cause of the bug and develop potential solutions.

Potential Causes and Solutions

Based on the information gathered, here are some potential causes and solutions for the GHDL assertion error:

  1. Bug in Hierarchy Flattening Logic: The most likely cause is a bug in GHDL's hierarchy flattening logic. When --keep-hierarchy=no is used, GHDL attempts to remove the hierarchical structure of the design during synthesis. This process involves complex transformations and optimizations, and a bug in this code could lead to incorrect handling of VHDL declarations, triggering the assertion error. To address this, GHDL developers would need to examine the synth-vhdl_decls.adb file and the surrounding code to identify the specific condition that is causing the assertion to fail. This might involve stepping through the code with a debugger, analyzing data structures, and identifying edge cases that are not being handled correctly.

  2. Compiler Issue: The use of an experimental GNAT compiler could also be a contributing factor. Experimental compilers may have bugs or incomplete implementations that cause issues with GHDL's Ada code. While less likely, it's worth considering whether the GNAT compiler is correctly handling certain language constructs or optimizations used by GHDL. To rule this out, it might be necessary to try compiling GHDL with a stable version of GNAT and see if the issue persists.

  3. Specific VHDL Code Triggering the Bug: Certain VHDL code constructs or design patterns might be more likely to trigger the bug. The GRLIB library, used in the reproduction steps, is a complex design with a mix of VHDL code. It's possible that specific coding styles or hierarchical structures within GRLIB are exposing a weakness in GHDL's flattening process. Identifying the specific parts of the VHDL code that contribute to the error could help GHDL developers create targeted fixes. This might involve simplifying the GRLIB design or creating minimal test cases that reproduce the bug.

  4. Memory Corruption: While less likely, memory corruption could also cause assertion errors. If GHDL's memory management is flawed, it could lead to data structures being overwritten or corrupted, causing unexpected behavior and assertion failures. Debugging memory corruption issues can be challenging and often requires specialized tools and techniques. GHDL developers would need to carefully examine the memory allocation and deallocation patterns in the synthesis code to identify potential leaks or corruption.

Possible Solutions and Workarounds:

  • Avoid --keep-hierarchy=no: The most immediate workaround is to avoid using the --keep-hierarchy=no option. If hierarchy flattening is not essential, removing this option might allow the synthesis to proceed without errors. However, this might not be a viable solution if hierarchy flattening is required for optimization or compatibility reasons.
  • Use a Stable GHDL Version: If a development version of GHDL is being used, switching to a stable release might resolve the issue. Stable releases have undergone more testing and are less likely to contain bugs. Users can download stable releases from the GHDL website or package manager.
  • Simplify the Design: If the bug is triggered by specific VHDL code, simplifying the design or modifying the code might help. This could involve restructuring the hierarchy, simplifying complex logic, or using different coding styles. However, this approach might not be practical for large or complex designs.
  • Report the Bug to GHDL Developers: The most effective solution is to report the bug to the GHDL developers on the GHDL GitHub issues page. Providing detailed information, including the GHDL version, command line, VHDL code, and error message, will help developers reproduce and fix the bug. The GHDL community is active and responsive, and bug reports are typically addressed in a timely manner.

Conclusion

The assertion error encountered when using GHDL with --keep-hierarchy=no is a significant issue that can disrupt the synthesis process. By understanding the steps to reproduce the error, the context in which it occurs, and the potential causes, users can better troubleshoot and work around the problem. While the exact cause of the bug requires further investigation by GHDL developers, the information presented in this article provides a solid foundation for understanding and addressing the issue. Remember to report any bugs you encounter to the GHDL developers, as this helps improve the tool for everyone.

For further information on GHDL and its capabilities, please visit the official GHDL website at ghdl.github.io. This resource provides comprehensive documentation, tutorials, and examples to help you effectively use GHDL in your VHDL projects.