SystemVerilog $unit Compilation Scope

A typedef or a small utility function that several modules in the same file need doesn't always deserve a full package. SystemVerilog lets you declare things directly at the top of a file, outside any module or package, and every module compiled alongside them can use them with no import at all. That scope has a name: $unit.

7 min read | Intermediate Level

What You'll Learn

• What a compilation unit is, and why file grouping is tool-specific
• How to declare something in $unit scope, and use it from any module compiled alongside it
• Why $unit:: only disambiguates a name - it never grants forward visibility
• The concrete ways $unit scope is not just an unnamed package

What Is a Compilation Unit?

A compilation unit is one or more source files compiled together, and exactly how files get grouped into units is tool-specific. Every compliant tool has to support both extremes, though: all files on one compile command line can form a single unit, or each file can be treated as its own separate unit.

Anything declared outside every module, interface, program, package, and class - at the outermost level of a file - lands in that file's compilation-unit scope. A file pulled in with `include becomes part of the including file's own compilation unit, not a separate one.

Declaring Something in $unit Scope

A plain declaration at the top of a file, outside any module, is enough - no special keyword marks it as "$unit scope," it's simply wherever an item ends up when it isn't nested inside anything else:

// Outside any module - this typedef and function live in $unit scope
typedef enum logic [1:0] {OK, WARN, ERROR} status_t;

function automatic string status_str(status_t s);
  return s.name();
endfunction

module tb;
  initial begin
    status_t a = OK;
    status_t b = ERROR;

    $display("a = %s", status_str(a));
    $display("b = %s", status_str(b));
  end
endmodule

Output

a = OK
b = ERROR

tb uses status_t and status_str directly, with no import statement anywhere - they're simply visible, the same way a locally declared variable would be. Any other module compiled in the same unit as this file could use them exactly the same way.

Accessing It Explicitly with $unit::

Normally you never need to write $unit:: at all - a plain name already resolves to the compilation-unit-scope declaration when nothing closer shadows it. The prefix exists for the one case where something does shadow it:

int counter = 100;   // $unit-scope declaration

module tb;
  initial begin
    int counter = 5;   // this local declaration shadows the $unit-scope one

    $display("counter        = %0d", counter);
    $display("$unit::counter = %0d", $unit::counter);
  end
endmodule

Output

counter        = 5
$unit::counter = 100

Name lookup always checks the nearest enclosing scope first, so the plain counter inside initial begin finds the local variable before it ever considers the one declared at the top of the file. $unit::counter skips straight past that local declaration and reaches the compilation-unit-scope one directly.

$unit:: Doesn't Add Forward Visibility

An identifier still has to be declared earlier in the same compilation unit before it can be referenced - the $unit:: prefix only disambiguates a name that already resolves, it doesn't let you reach something declared later in the file:

int x;

module tb;
  initial begin
    x = 5 + limit;           // illegal: 'limit' isn't declared yet at this point
    x = 5 + $unit::limit;    // also illegal: $unit:: grants no forward visibility
  end
endmodule

int limit = 10;   // declared after the module that tried to use it

Moving limit's declaration above module tb is the only fix - there's no prefix or keyword that lets a reference reach forward to a declaration that hasn't happened yet in the source text.

$unit Is Not Just an Unnamed Package

$unit scope can hold anything a package can - types, parameters, functions, tasks, variables - but it isn't a package, and the differences matter:

That last row is the one most worth remembering. Whether two files end up sharing one compilation unit or each gets its own is a tool and build-script decision, not something the source code controls - so relying on one file's $unit declarations being visible in another file is only safe if you know for certain they're compiled together as a single unit.

Common Beginner Mistakes