SystemVerilog Package

Verilog has significant limitations around global declarations, especially functions and user-defined types:

• Local Scope — every object declared inside a Verilog module is local to that module, so any function or task needed elsewhere has to be re-declared in every module that uses it, leading to redundant code and extra maintenance.
• Hierarchical References — Verilog allows reaching into another module's objects hierarchically, but these references are for verification purposes only and don't represent real hardware, so they aren't synthesizable.
• User-Defined Types — a type needed in multiple modules has to be redefined in each one, without a mechanism for declaring it once, globally.

A SystemVerilog package solves all three: a way to store and share data, methods, properties, and parameters reusable across multiple modules, interfaces, or programs. A package's scope sits at the same level as a top-level module, and keeping definitions between package and endpackage prevents clutter in the global namespace.

16 min read | Intermediate Level

What You'll Learn

• The specific Verilog limitations packages solve
• Basic package syntax, and what's allowed to go inside one
• How wildcard imports differ from importing specific items
• The exact order SystemVerilog uses to resolve an identifier, and why local declarations always win
• Whether importing a package that itself imports another package gives you transitive access to both
• What parts of a package are synthesizable, and which uses are simulation-only

SystemVerilog Package Syntax

package ;
  // Typedef declarations
  // Function/Task definitions
  // ...
endpackage

A package is a separate namespace, not embedded inside any module.

A package cannot contain hierarchical references, except those created within the package itself or through an import.

A Basic Package Example

package my_pkg;

    // Create typedef declarations that can be reused in multiple modules
	typedef enum bit [1:0] { RED, YELLOW, GREEN, RSVD } e_signal;

	typedef struct { bit [3:0]   signal_id;
                     bit         active;
                     bit [1:0]   timeout;
                   } e_sig_param;

    // Create function and task defintions that can be reused
    // Note that it will be a 'static' method if the keyword 'automatic' is not used
	function int calc_parity ();
      $display ("Called from somewhere");
   	endfunction
  
endpackage

Importing a Package

A package is brought into the current scope with import and the scope resolution operator :::

import ::*; // Imports all items
import ::; // Imports specific item

Wildcard Import

A wildcard import makes a package's declarations visible — but only the ones actually referenced in the importing scope get pulled in; anything unused stays unimported:

// Import the package defined above to use e_signal
import my_pkg::*;

class myClass;
	e_signal 	m_signal;
endclass

module tb;
	myClass cls;

	initial begin
		cls          = new();
		cls.m_signal = GREEN;
		$display ("m_signal = %s", cls.m_signal.name());
		calc_parity();
	end
endmodule

Output

ncsim> run
m_signal = GREEN
Called from somewhere
ncsim: *W,RNQUIE: Simulation is complete.

Without the import statement, this same code fails to compile at all:

	e_signal 	m_signal;
	       |
ncvlog: *E,NOIPRT (testbench.sv,15|8): Unrecognized declaration 'e_signal' could be an unsupported keyword, a spelling mistake or missing instance port list '()' [SystemVerilog].
		cls.m_signal = GREEN;
		                 |
ncvlog: *E,UNDIDN (testbench.sv,23|19): 'GREEN': undeclared identifier [12.5(IEEE)].

Importing Specific Items

Instead of a wildcard, individual items can be imported one at a time — more explicit, but more overhead as more items are needed:

import my_pkg::GREEN;
import my_pkg::e_signal;
import my_pkg::common;

Omitting any one of these causes a compile error, since the compiler has no other way to know where that identifier comes from. Note that this applies per-label, not per-enum — importing the type doesn't automatically import every value that belongs to it:

// Although e_signal is made visible, enumerated labels will not be made visible
import my_pkg::e_signal;

// Import each enumerated label instead, if you are not importing using wildcard ::*
import my_pkg::RED;
import my_pkg::GREEN;
import my_pkg::YELLOW;
// etc

Search Order: Why Local Always Wins

Local definitions inside a module or interface always take priority over a wildcard import. An import naming a specific item also takes precedence over a wildcard import. A wildcard import just extends the search: the tool looks for local declarations first, then wildcard-imported packages, and finally $unit's own declaration space — matching the same local-shadows-import rule covered in SystemVerilog Scope Resolution Operator.

package my_pkg;
	typedef enum bit { READ, WRITE } e_rd_wr;
endpackage

import my_pkg::*;

module tb;
  typedef enum bit { WRITE, READ } e_wr_rd;

	initial begin
        e_wr_rd  	opc1 = READ;
        e_rd_wr  	opc2 = READ;
      $display ("READ1 = %0d READ2 = %0d ", opc1, opc2);
	end
endmodule

Output

ncsim> run
READ1 = 1 READ2 = 1
ncsim: *W,RNQUIE: Simulation is complete.

Even though opc2 is declared with the package's type (e_rd_wr), the unqualified READ assigned to it still resolves to the module's own locally-declared READ (value 1, from e_wr_rd's reversed order), not the package's READ (value 0). The variable's declared type doesn't change which READ gets resolved — that's still governed by the search order above.

Forcing the package's own value requires an explicit :::

module tb;
	initial begin
        e_wr_rd  	opc1 = READ;
        e_rd_wr  	opc2 = my_pkg::READ;
      $display ("READ1 = %0d READ2 = %0d ", opc1, opc2);
	end
endmodule

Output

ncsim> run
READ1 = 1 READ2 = 0
ncsim: *W,RNQUIE: Simulation is complete.

Nested Package References

Packages can import other packages. Here, package Y imports package X, and package Z imports package Y:

// Define a new package called X
package X;
  byte    lb     = 8'h10;
  int     word   = 32'hcafe_face;
  string  name = "X";

  function void display();
    $display("pkg=%s lb=0x%0h word=0x%0h", name, lb, word);
  endfunction
endpackage

// Define a new package called Y, use variable value inside X within Y
package Y;
  import X::*;

  byte    lb   = 8'h10 + X::lb;
  string  name = "Y";

  function void display();
    $display("pkg=%s lb=0x%0h word=0x%0h", name, lb, word);
  endfunction
endpackage

// Define a new package called Z, use variable value inside Y within Z
package Z;
  import Y::*;  

  byte    lb   = 8'h10 + Y::lb;
  string  name = "Z";
  
  function void display();
    // Note that 'word' exists in package X and not in Y, but X
    // is not directly imported here in Z, so the statement below
    // will result in a compilation error
    //$display("pkg=%s lb=0x%0h word=0x%0h", name, lb, word);  // ERROR !
  
    $display("pkg=%s lb=0x%0h", name, lb);
  endfunction
endpackage

module tb;
  // import only Z package
  import Z::*;
  
  initial begin
    X::display();   // Direct reference X package
    Y::display();   // Direct reference Y package
    display();      // Taken from Z package because of import
  end
endmodule

Output

	Top level design units:
		X
		Y
		Z
		tb
Loading snapshot worklib.tb:sv .................... Done
...
xcelium> run
pkg=X lb=0x10 word=0xcafeface
pkg=Y lb=0x20 word=0xcafeface
pkg=Z lb=0x30
xmsim: *W,RNQUIE: Simulation is complete.

Y::display() successfully prints word (0xcafeface) even though Y never declares its own word — it resolves through Y's own wildcard import of X. But Z::display() can't reach word at all, even though Z imports Y, which itself imports X. A wildcard import isn't transitive: importing Y::* gives Z access to what Y itself declares, not to whatever Y only sees because of its own separate import of X.

Design Notes: Packages and Synthesis

The synthesizable constructs a package can include are: parameters, local parameters, and constant variables; user-defined types via typedef; fully automatic task and function definitions; and import statements for other packages.

// Define the package for ALU instructions
package alu_pkg;

typedef enum logic [2:0] {
    ADD = 3'b000,
    SUB = 3'b001,
    AND = 3'b010,
    OR  = 3'b011,
    XOR = 3'b100
} alu_op_t;

endpackage

Using a wildcard import to bring everything in:

// Import everything inside the package containing ALU operations
import alu_pkg::*;

module alu (
    input logic [2:0]   opcode,  // ALU operation code
    input logic [31:0]  a,       // First operand
    input logic [31:0]  b,       // Second operand
    output logic [31:0] result   // Result of the operation
);

always_comb begin
    // Enumerations defined in 'alu_pkg' can be directly used here
    // because they have been imported
    case (opcode)
        ADD: result = a + b;   // Perform addition
        SUB: result = a - b;   // Perform subtraction
        AND: result = a & b;   // Perform bitwise AND
        OR:  result = a | b;   // Perform bitwise OR
        XOR: result = a ^ b;   // Perform bitwise XOR
        default: result = 32'b0; // Default case (optional)
    endcase
end
endmodule

Or referencing the package directly, with no import at all:

// Note that package import is not done here

module alu (
    input logic [2:0]   opcode,  // ALU operation code
    input logic [31:0]  a,       // First operand
    input logic [31:0]  b,       // Second operand
    output logic [31:0] result   // Result of the operation
);

always_comb begin
    // Enumerations defined in 'alu_pkg' is directly referenced using ::
    case (opcode)
        alu_pkg::ADD  : result = a + b;   // Perform addition
        alu_pkg::SUB  : result = a - b;   // Perform subtraction
        alu_pkg::AND  : result = a & b;   // Perform bitwise AND
        alu_pkg::OR   : result = a | b;   // Perform bitwise OR
        alu_pkg::XOR  : result = a ^ b;   // Perform bitwise XOR
        default       : result = 32'b0;   // Default case (optional)
    endcase
end

When a module calls a task or function defined in a package, synthesis replicates that functionality as if it were defined directly inside the module. For a package's tasks and functions to be synthesizable, they must be declared automatic and cannot include static variables.