Name Conflicts, $unit and the std Package

Predict which declaration a name refers to when a module, two packages and the file scope all offer one. Fix an ambiguous import, and reach the built-in std package when a closer name hides it.

You Will Be Able To

  • Resolve a name through local declarations, explicit imports, wildcard imports and $unit.
  • Fix a name that two wildcard imports both offer.
  • Explain why a declaration at file scope is fragile.
  • Reach a built-in class with std:: when another declaration hides it.
Lesson
8.2
Time
25 min
Runs on
Your browser
Check
5 questions

A UART test passed on a design that hung for 300 cycles. The checker waited TIMEOUT cycles before it reported a hang, and the package set that to 64. A localparam TIMEOUT = 1000, left in the module after an old experiment, had replaced it without a warning.

What the author read

// uart_pkg: TIMEOUT = 64
import uart_pkg::*;
repeat (TIMEOUT) @(posedge clk);
$error("no response");

The hang is reported after 64 cycles.

What the compiler read

import uart_pkg::*;
localparam int TIMEOUT = 1000;
repeat (TIMEOUT) @(posedge clk);
$error("no response");

The local name wins. The test ends before cycle 1000, so nothing is reported.

Where the Compiler Looks for a Name

Every use of a plain name starts a search. The compiler looks in the scope that contains the use, and it moves outward only when that scope has nothing to offer.

Written in one moduleResult on Icarus 12
import p1::*; and a local int xthe local x
import p1::*; import p2::x;p2::x: the explicit import wins
import p1::*; import p2::*; and x is usederror: ambiguous use of x
import p1::x; and a local int xerror: x is already imported
import p1::x; import p2::x;error: x is already imported
import p1::*;, x is used, then int x is declarederror: x is already imported

Both packages declare x. Six measured cases; each result is what IEEE 1800-2023 26.3 requires.

Read the table as three rules. A local declaration and an explicit import are both real declarations, so two different ones for one name always clash. A wildcard import is weaker and gives way to either one without a message. Once a wildcard name has been used, the choice is fixed, and a later declaration of that name is an error.

An import is local to the scope it is written in. A function can import a package for its own body, and that import hides the module's candidates inside the function only. A module instantiated below sees none of its parent's imports.

Two Wildcard Imports of One Name

Two packages often share a name such as TIMEOUT or ADDR_W. Importing both with ::* is legal, and it stays legal for as long as nobody uses the shared name. The error appears at the first use, perhaps months later and in a line that looks innocent.

Icarus 12, measured: the lesson example with one extra line.
import uart_pkg::*;   // offers TIMEOUT = 64
import spi_pkg::*;    // offers TIMEOUT = 16
...
$display("TIMEOUT=%0d", TIMEOUT);

main.sv:25: error: Ambiguous use of 'TIMEOUT'. It is exported by both 'uart_pkg' and by 'spi_pkg'.

There are two fixes, and both say which package you mean. Write the package name at the use, as in uart_pkg::TIMEOUT. Or add import uart_pkg::TIMEOUT;, which turns that name into a declaration of the module.

A safe habit is to import by name what you use from a second package. Each import line then records where a shared name comes from. A later clash is then a compile error, never a silent change.

Changing the order of the two wildcard imports fixes nothing, because the order carries no meaning. Declaring a local TIMEOUT removes the error too, but it hides both packages, which is the bug in the opening story.

$unit: The Scope Outside Every Module

A declaration written outside every module, package and interface lives in the compilation-unit scope, named $unit. Code inside a module can use such a name directly. The search reaches $unit last, after the module's own names and imports.

If a closer name hides it, $unit::name still reaches the file-scope declaration, just as pkg::name reaches a package.

File-scope declarations are fragile for two reasons. First, the standard lets a tool decide which files form one compilation unit. One tool compiles all files together, another compiles each file as its own unit. A name that every file saw on the first tool is missing on the second.

Second, every file in the unit can add names to $unit. One new line in a distant file can then change what a name in your module means. A package has neither problem: it has a name, one definition, and users that import it on purpose.

The std Package

The language itself ships one package, called std. It is wildcard imported into every $unit without any line of yours. That is why mailbox and process work in every file with no import.

In stdWhat it is
processclass: a handle on a running process
semaphoreclass: a set of keys that processes take and return
mailboxclass: a queue that passes items between processes
randomize()function: randomize variables that are not class members

Four members of the built-in package (IEEE 1800-2023 Annex G).

The built-in function is the one you call as std::randomize(a, b) to randomize plain variables. Inside a class, a plain randomize() means the object's own method, so the prefix matters there too.

Because std is found last, any closer declaration hides it. If a package you import declares its own semaphore, a plain semaphore in your module means that class. Write std::semaphore to get the built-in one.

Try It

Only uart_pkg offers BAUD_DIV, so the plain name works. Both packages offer TIMEOUT, so the module names the package each time. The local CS_GAP hides the package's value of 2. Inside spi_wait, an explicit import settles TIMEOUT for that function alone. errors is found in $unit.

Add $display("TIMEOUT=%0d", TIMEOUT); as the second line of the initial block and run it. Icarus stops with the ambiguous-use error on line 25. Then fix it in both ways from the lesson.

Last, add int errors = 9; inside the module, above the initial block. Predict both numbers of the last line before you run it.

RUNIcarus Verilog · in your browser
Edit the code, then run it
Expected: BAUD_DIV=8 uart TIMEOUT=64, spi TIMEOUT=16 CS_GAP=5, spi_pkg::CS_GAP=2 spi_wait=32 errors=1, $unit::errors=1

Check Yourself

Predict the outputPredict the exact output.
package a_pkg; int gap = 3; endpackage
package b_pkg; int gap = 7; endpackage

module tb;
  import a_pkg::*;
  function automatic int f();
    import b_pkg::*;
    return gap;
  endfunction
  initial $display("gap=%0d f=%0d", gap, f());
endmodule
Spot the bugEach option is the import section of a UART checker. It must wait uart_pkg::TIMEOUT cycles, which is 64. Every option compiles. Which one waits the wrong number of cycles?
ConceptA testbench has import axi_pkg::*; and import apb_pkg::*;. Both packages declare ADDR_W, and the testbench never uses that name. What does the compiler do?
ConceptA module contains import cfg_pkg::DEPTH; and, two lines later, localparam int DEPTH = 8;. What happens?
ConceptA team package declares class mailbox for its own queue, and a test imports the package with ::*. How does the test create the built-in mailbox?

Common Mistakes

Wrong Fix an ambiguous name by changing the order of the two wildcard imports.

The order of wildcard imports has no meaning, so both packages still offer the name.

Fix Name the package at the use, or add one explicit import.

Before
import spi_pkg::*;
import uart_pkg::*;    // still ambiguous
wait_for = TIMEOUT;
After
import uart_pkg::*;
import spi_pkg::*;
wait_for = uart_pkg::TIMEOUT;

Wrong Share a type or a counter between source files by declaring it at file scope.

A tool may compile each file as its own unit, and then the other files cannot see it.

Fix Put shared declarations in a package and import the package where it is used.

Wrong Expect an import in a parent module to reach the modules it instantiates.

An import belongs to the scope it is written in, and an instance is not inside that scope.

Fix Import the package in every module that uses its names, or in the module header.

Wrong Name your own class mailbox, semaphore or process.

A closer declaration hides the built-in class for every scope that imports yours.

Fix Choose another name, and write std::mailbox where you mean the built-in class.

Remember

  • A name is searched from the inside out: local names and explicit imports, wildcard imports, $unit, then std.
  • A wildcard import only offers names; a local declaration or an explicit import silently wins over it.
  • Two wildcard imports of one name are legal until the name is used; then name the package.
  • File-scope declarations live in $unit, whose contents depend on how the tool groups files. Prefer a package.
  • std holds process, semaphore, mailbox and randomize(); std:: reaches them when a closer name hides them.

Practice

Report a problem with this page