GHDL Bug: Generic Protected Type Undefined Symbol

Unraveling the Mystery: GHDL and Undefined Symbols with Generic Protected Types

Have you ever hit a perplexing error in your VHDL development that leaves you scratching your head, particularly when you're trying to leverage powerful features like generics and protected types? You're not alone! Many VHDL enthusiasts and professional engineers often encounter unexpected compilation issues, and one particularly tricky scenario arises when combining generic packages with protected types within the GHDL simulator. This discussion delves into a specific bug where an undefined symbol error pops up when a generic parameter is used to define the size of an array within a protected type's initialization. This is a crucial topic because both generic packages and protected types are fundamental to writing reusable, robust, and concurrent VHDL code. Generics allow you to create highly flexible components that can be customized without rewriting code, while protected types provide a safe mechanism for managing shared data and synchronization between concurrent processes, preventing common concurrency pitfalls like race conditions. The ability to combine these two powerful features should ideally lead to even more elegant and maintainable designs, making the discovery of such a bug incredibly frustrating. Understanding this issue is not just about fixing a specific error; it's about gaining a deeper insight into how VHDL compilers like GHDL handle complex language constructs, especially during the elaboration phase where generic parameters are resolved and memory is allocated. This article aims to break down the problem, explain its technical implications, and offer insights into potential workarounds, ultimately helping you navigate similar challenges in your VHDL journey and contributing to a better understanding of advanced VHDL design patterns. We'll explore why this specific combination can lead to a PROGRAM_ERROR and how to approach debugging such elusive issues in the world of hardware description languages.

Diving Deep into the Code: Understanding the MWE

To truly grasp the nature of this particular GHDL bug, we need to carefully examine the Minimal Working Example (MWE) that effectively reproduces the undefined symbol error. This small, self-contained piece of VHDL code is invaluable for debugging, as it strips away all non-essential elements to highlight the core problem. The MWE showcases a generic package named pt_generic_pkg, which is designed to be configurable. Generics, in VHDL, are like templates that allow you to pass parameters (such as NB_ELEMENTS in our case) to a package or entity at the time of its instantiation, making your code highly reusable and adaptable. Inside this generic package, we define a protected type called pt_t. Protected types are a modern VHDL feature enabling object-oriented-like encapsulation and providing controlled access to shared data through procedures and functions, preventing simultaneous modifications from multiple concurrent processes. The heart of the issue lies within the protected body of pt_t. Here, a variable named storage is declared as an integer_ptr_array_ptr, which is an access type pointing to an array of integer pointers. The critical line is its initialization: variable storage : integer_ptr_array_ptr := new integer_ptr_array_t(0 to NB_ELEMENTS-1);. This line attempts to dynamically allocate an array whose size (NB_ELEMENTS-1) is determined by the generic parameter NB_ELEMENTS passed to the parent pt_generic_pkg. On the surface, this seems like a perfectly legitimate use of generics and dynamic allocation, aiming to create a protected type that can manage a variable number of elements. However, when GHDL tries to elaborate and run this code, it fails spectacularly with an undefined symbol error. Contrast this with the commented-out line: -- variable storage : integer_ptr_array_ptr := new integer_ptr_array_t(0 to 9);. This line, which uses a fixed, hardcoded size (9) instead of the generic NB_ELEMENTS, compiles and runs without any issues. This stark difference immediately points to the generic parameter NB_ELEMENTS as the culprit, specifically when it's used within the context of dynamic memory allocation for an array inside a protected type that itself is part of a generic package. The entity mwe and its architecture test merely serve to instantiate pt_generic_pkg with NB_ELEMENTS => 10 and declare a shared variable of the generic protected type, which is enough to trigger the bug during the elaboration phase. Understanding this precise interaction is key to diagnosing and potentially mitigating such complex VHDL compilation errors.

The Heart of the Matter: Why Does NB_ELEMENTS Cause an Undefined Symbol?

When we observe the GHDL Bug occurred message, followed by symbol work__pt_generic_pkg__U0__STL is undefined and ultimately a PROGRAM_ERROR, it signals a deep-seated issue within the GHDL compiler's internal processes, specifically concerning how it handles generic parameters when combined with protected types and dynamic memory allocation. The error message itself, pointing to work__pt_generic_pkg__U0__STL, suggests that GHDL is trying to resolve or link a symbol (likely an internal representation of the storage variable or its initializer) that it cannot find in its symbol table during the elaboration phase. The elaboration phase in VHDL is where all generic parameters are resolved, components are interconnected, and a concrete hardware description is formed from the abstract VHDL code. For a simple integer_ptr_array_t(0 to 9) initialization, the size is statically known at compile time, allowing GHDL to allocate the necessary memory and set up the symbol correctly. However, when NB_ELEMENTS is introduced, it becomes a generic parameter whose value (10 in our MWE) is only provided at the time of package instantiation in the architecture. This means GHDL needs to dynamically determine the array size during elaboration. While GHDL is generally excellent at handling generics, the specific interaction of a generic-dependent size with the new keyword (for dynamic allocation) inside a protected type body within a generic package appears to expose a weakness or an edge case in its current implementation. The PROGRAM_ERROR raised from simul-vhdl_compile.adb:2213 explicit raise further suggests that GHDL's internal logic for compiling or simulating this particular construct has encountered a state it cannot properly handle, leading to an intentional abort rather than an undefined behavior. It's plausible that GHDL's mcode backend or its elaboration engine might not be correctly propagating the resolved generic value for NB_ELEMENTS down to the context where the protected type's internal variables are initialized, especially when that initialization involves dynamic memory allocation. This could lead to the size calculation for new integer_ptr_array_t(0 to NB_ELEMENTS-1) failing or resulting in an invalid memory access during the generation of internal simulation code, hence the undefined symbol as the compiler cannot produce a valid symbol for an improperly sized or allocated structure. The complexity of managing shared variables (like sv of type pt_pkg.pt_t) and their internal state further complicates this, as protected types have specific rules for concurrent access that GHDL must meticulously manage.

Navigating Around the Issue: Potential Workarounds and Best Practices

Facing an undefined symbol error like this, especially when it stems from a combination of advanced VHDL features, can be quite frustrating. However, in the absence of an immediate fix from the GHDL developers, there are several workarounds and best practices that VHDL engineers can employ to bypass or mitigate this generic protected type bug. The primary goal is to achieve the desired generic functionality without triggering the specific problematic interaction within GHDL. One approach is to avoid using the generic parameter directly in the protected type's variable initialization for dynamic arrays. Instead of new integer_ptr_array_t(0 to NB_ELEMENTS-1);, you might consider initializing the storage variable to null initially. Then, within one of the protected type's procedures (perhaps an init procedure that you call right after the protected type is created), you could perform the dynamic allocation using the NB_ELEMENTS generic. This separates the declaration from the allocation, giving GHDL more flexibility during elaboration. Another strategy involves rethinking your approach to generic protected types entirely. If the number of elements can fluctuate, perhaps a linked list implementation or a std.textio.integer_vector with dynamic resizing (if your VHDL version and tools support it more robustly) might be a more resilient alternative, though it adds complexity. Alternatively, if NB_ELEMENTS is truly fixed after instantiation, you might consider passing the resolved size to a constructor-like function of the protected type rather than directly using it in the variable declaration, allowing the protected type to manage its internal allocation based on a parameter it receives, not one it resolves internally from its generic package parent. Remember, the problem here is the direct use of the generic for dynamic array sizing during the protected type's internal variable initialization. If a fixed-size array is acceptable, you could declare a generously sized array and manage its logical usage within the protected type's methods, essentially creating a