Verilator Module `ref` Ports Issue Without Inlining Explained

Hey guys! Today, we're diving deep into a tricky issue with Verilator and its handling of ref ports, specifically when module inlining is disabled. It's a bit of a rabbit hole, but stick with me, and we'll get through it together. We'll explore the problem, the test case that exposes it, and potential solutions.

The Core Issue: ref Ports and Module Inlining

The heart of the matter is that ref ports in Verilog seem to rely on module inlining to function correctly. If a module with a ref port isn't inlined, things can go sideways. Now, you might be asking, "What's a ref port?" Well, in SystemVerilog, a ref port allows a module to directly access and modify a variable in another module. It's like giving a module a direct line to a variable, which can be super handy for certain designs. However, the current implementation in Verilator appears to have a limitation: these ref ports don't play nice when the module containing them isn't inlined.

This limitation can be a real headache because, in many scenarios, we can't just inline modules willy-nilly. Sometimes, inlining isn't feasible or desirable due to design complexity, performance considerations, or other constraints. So, if ref ports only work with inlining, we're in a bind. Moreover, the lack of clear documentation about this limitation is a recipe for unexpected bugs and wasted debugging time. Imagine spending hours trying to figure out why your ref ports aren't behaving as expected, only to discover that it's because you disabled inlining! This can be a huge time-sink, especially in large and complex designs where module interactions are intricate. The issue arises from how Verilator handles the connection between the ref port and the actual variable it's referencing. When inlining is enabled, Verilator essentially merges the code of the submodule into the parent module, making the ref port behave as if it were a direct assignment within the same module. This direct assignment ensures that updates to the variable are immediately visible in both the parent and submodule. However, when inlining is disabled, Verilator creates a separate module instance, and the connection between the ref port and the variable becomes more complex. In this case, Verilator creates a pin assignment, which acts like a wire connecting the ref port to the variable. The problem is that this pin assignment is unidirectional, meaning that updates from the submodule are visible to the parent module, but updates from the parent module are not propagated back to the submodule. This unidirectional behavior leads to the inconsistency observed in the test case, where the check in the submodule fails because it doesn't see the update from the top module. To make matters worse, the issue can manifest in subtle and hard-to-debug ways, especially in complex designs with multiple modules and intricate interactions. The behavior of ref ports can also be affected by other Verilator settings and optimizations, making it even more challenging to diagnose the problem. Therefore, it's crucial to have a clear understanding of this limitation and to carefully consider the implications before using ref ports in designs where module inlining is disabled.

The Test Case: Exposing the Issue

To really nail down the problem, let's look at a specific test case. This test, written in SystemVerilog, sets up a scenario where a ref port is used between two modules, top and sub. The top module contains an integer variable x, and the sub module has a ref port y that's connected to x. The test then carefully orchestrates updates to x from both modules and uses checks (check macro) to verify that the updates are correctly propagated. Specifically, the top module updates x in one cycle, and the sub module is expected to see this updated value in the subsequent cycle. However, when the test is run with the -fno-inline flag, which disables module inlining, the check in the sub module fails. This failure clearly demonstrates that the update from top to sub via the ref port is not working as expected when inlining is disabled. The test case is designed to be as simple as possible while still capturing the essence of the problem. It uses a clock signal (clk) and a cycle counter (cyc) to synchronize the updates and checks. The check macro provides a clear and concise way to verify the expected values at different points in the simulation. By using this test case, we can reliably reproduce the issue and use it to validate any potential fixes. The test case also serves as a valuable tool for understanding the limitations of ref ports in Verilator and for developing best practices for their use. For example, the test highlights the importance of considering the inlining settings when using ref ports and the potential for unexpected behavior if inlining is disabled. Furthermore, the test case can be extended and modified to explore other aspects of ref port behavior, such as their interaction with different Verilator optimizations and their performance implications. By thoroughly testing and understanding the behavior of ref ports, we can ensure that they are used correctly and effectively in our designs. This proactive approach to testing and validation is crucial for building robust and reliable hardware systems.

Here's the code:

`define stop $stop
`define check(got ,exp) do if ((got) !== (exp)) begin $write("%%Error: %s:%0d: cyc=%0d got='%0d exp='%0d\n", `__FILE__,`__LINE__, cyc, (got), (exp)); `stop; end while(0)

module top;

 bit clk = 0;
 always #5 clk = ~clk;

 int cyc = 0;
 int x;

 sub s(clk, cyc, x);

 always @(posedge clk) begin
 cyc <= cyc + 1;
 if (cyc == 0) begin
 // Ignore
 end else if (cyc == 1) begin
 // 'x' updated by 'sub'
 end else if (cyc == 2) begin
 `check(x, 100);
 end else if (cyc == 3) begin
 x <= 200;
 end else if (cyc == 4) begin
 `check(x, 200);
 end else begin
 $write("*-* All Finished *-*\n");
 $finish;
 end
 end

endmodule

module sub(
 input bit clk,
 input int cyc,
 ref int y
);

 always @(posedge clk) begin
 if (cyc == 0) begin
 // Ignore
 end else if (cyc == 1) begin
 y <= 100;
 end else if (cyc == 2) begin
 `check(y, 100);
 end else if (cyc == 3) begin
 // 'y' updated by 'top'
 end else if (cyc == 4) begin
 `check(y, 200); // <-------------- Fails this check
 end
 end

endmodule

Key points in this code:

• We've got a top module and a sub module.
• The sub module takes a ref int y as a port, which is connected to x in the top module.
• The test sequence in the always @(posedge clk) blocks carefully updates and checks the values of x and y at different clock cycles.
• The failing check (check(y, 200)) in the sub module when cyc is 4 is the smoking gun.

The Command Line and the Error

To reproduce this issue, you can use the following Verilator command:

verilator --binary refport.sv -fno-inline -Wno-BLKANDNBLK

Here's the breakdown:

• verilator: This is the command to invoke the Verilator tool.
• --binary refport.sv: This tells Verilator to compile the refport.sv file and generate a binary executable.
• -fno-inline: This is the crucial flag that disables module inlining. This is what triggers the bug.
• -Wno-BLKANDNBLK: This suppresses a warning related to blocking and non-blocking assignments. It's a bit of a red herring in this case, but it often appears when inlining is disabled due to how Verilator handles assignments.

When you run this command and then execute the resulting binary, you'll see the following error:

%Error: refport.sv:56: cyc=4 got='100 exp='200
%Error: refport.sv:56: Verilog $stop
Aborting...

This error message confirms that the check in the sub module failed, meaning the value of y (which should be 200) is still 100. This is exactly what we expect when the update from the top module isn't being correctly propagated to the sub module via the ref port.

Root Cause Analysis: Why Does This Happen?

The reason this happens lies in how Verilator handles ref ports when inlining is disabled. Without inlining, Verilator creates separate instances of the top and sub modules. The connection between x in top and y in sub is then implemented using a pin assignment. Think of it like a wire connecting the two, but this wire, in this scenario, acts like a one-way street. The update from the sub module to the top module works fine, but the reverse doesn't. Specifically, the pin assignment created by Verilator in this case behaves as x = y. So, the update from the submodule (y <= 100) is visible to the top module (x), but the update from the top module (x <= 200) is not visible to the submodule (y). This unidirectional behavior is the core of the problem.

A Potential Solution: Treat ref Ports as Specialized Parameters

The author of the original bug report suggests an interesting alternative: treat ref ports as parameters and specialize the module using the hierarchical reference it's bound to. What does this mean in simpler terms? Imagine if, instead of creating a simple wire-like connection, Verilator could somehow create a special version of the sub module that's directly tied to the specific variable x in the top module. It's like creating a custom-built sub module that knows exactly where to find x. This approach could potentially solve the issue by ensuring that updates propagate correctly in both directions. However, this is just one potential solution, and it would likely require significant changes to Verilator's internal workings.

Implications and Workarounds

So, what are the implications of this issue, and what can we do about it? The biggest implication is that you need to be very careful when using ref ports in Verilator, especially if you're disabling module inlining. If you rely on ref ports and then disable inlining for performance or other reasons, you might encounter unexpected behavior and subtle bugs. As for workarounds, there aren't any perfect solutions. You could try to avoid using ref ports altogether and instead pass data between modules using regular input and output ports. This approach might require more explicit signaling and data transfer, but it can avoid the pitfalls of ref ports. Alternatively, if possible, you could try to ensure that the modules using ref ports are always inlined. However, this might not be feasible in all cases. Another workaround, although not ideal, could involve manually implementing the two-way update mechanism that's missing when inlining is disabled. This could involve adding extra logic to explicitly propagate updates in both directions, but it would add complexity and potentially impact performance. Ultimately, the best approach depends on the specific design and the constraints you're working under.

Conclusion

The issue with ref ports in Verilator when module inlining is disabled is a subtle but important one. It highlights the complexities of hardware simulation and the importance of understanding the limitations of the tools we use. While there aren't any easy fixes, being aware of the problem is the first step. By understanding the root cause and potential workarounds, we can make informed decisions about how to use ref ports in our designs and avoid unexpected surprises. Remember, always test your designs thoroughly, especially when using advanced features like ref ports, and be sure to consider the impact of different Verilator settings on your simulation results. Keep experimenting, keep learning, and keep building awesome hardware! I hope this deep dive into Verilator's ref port issue has been helpful for you guys. It's definitely a topic that requires careful consideration in the world of hardware design and simulation.