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.
TIMEOUT, in order. Arrows show where the search goes next when a place has no such name.- Step
- Neutral
- Result
- Control
- Local names first
A name declared in the module wins at once. An explicit import such as
import spi_pkg::TIMEOUT;counts as a declaration in the module. - Then wildcard imports
import uart_pkg::*;only offers the names of the package. A name is taken from the package when the module uses it and has no declaration of its own. - Two candidates
If two wildcard imports offer the name, the compiler refuses to choose. The use is an error.
- Then outward
With no candidate, the search leaves the module. It tries
$unit, the scope outside every module, and then the built-instdpackage. - Nothing anywhere
A name that no scope declares is a compile error.
Read the diagram as text
- A use of TIMEOUT: inside a module
- Declared in the module: local names, explicit imports
- Wildcard imports: candidates from pkg::*
- $unit: declarations at file scope
- std package: built-in, imported into $unit
- Compile error: two candidates, or no declaration
- A use of TIMEOUT → Declared in the module: first
- Declared in the module → Wildcard imports: not found
- Wildcard imports → $unit: not found
- $unit → std package: not found
- Wildcard imports → Compile error: two packages offer it
- std package → Compile error: not found
A closer declaration always wins, and nothing warns you that a farther one was hidden.
| Written in one module | Result on Icarus 12 |
|---|---|
import p1::*; and a local int x | the local x |
import p1::*; import p2::x; | p2::x: the explicit import wins |
import p1::*; import p2::*; and x is used | error: ambiguous use of x |
import p1::x; and a local int x | error: x is already imported |
import p1::x; import p2::x; | error: x is already imported |
import p1::*;, x is used, then int x is declared | error: 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.
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 std | What it is |
|---|---|
process | class: a handle on a running process |
semaphore | class: a set of keys that processes take and return |
mailbox | class: 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.
BAUD_DIV=8 uart TIMEOUT=64, spi TIMEOUT=16 CS_GAP=5, spi_pkg::CS_GAP=2 spi_wait=32 errors=1, $unit::errors=1Check Yourself
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.
import spi_pkg::*;
import uart_pkg::*; // still ambiguous
wait_for = TIMEOUT;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, thenstd. - 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. stdholdsprocess,semaphore,mailboxandrandomize();std::reaches them when a closer name hides them.