Packages, Typedefs and $unit in a Design
Share one type, one constant and one function between RTL modules through a package. Know what each tool does with file order.
You Will Be Able To
- Write a package that holds the types, constants and functions several modules share.
- Choose between
pkg::name, an explicit import and a wildcard import, and place the import. - Predict which name wins when a local declaration and an import collide.
- Explain why a declaration outside any module depends on how the tool reads the files.
- Lesson
- R9.3
- Time
- 30 min
- Runs on
- Verilator
- Check
- 5 questions
A calculator block ran AND when the command said subtract. The decoder and the ALU each had a private copy of the opcode type. Someone had sorted one copy by name. Every tool was silent.
- I/O
- Control / FSM
- Datapath
- Result
- Neutral
- Data
- Control
- Structure
- The decoder
For "-" the decoder sends
OP_SUB. In its copy of the enum that label is the number 1. - The ALU
The ALU receives 1. In its copy, sorted by name, 1 is
OP_AND. It runsa & b. - One copy
A package holds the type once. Both modules import it, so a label has one number everywhere.
Read the diagram as text
- ch = "-": the command character
- cmd_dec: its copy: ADD SUB AND XOR
- op = 1: two plain bits
- alu: its copy: ADD AND SUB XOR
- y = a & b: the wrong operation
- calc_pkg: one copy for both
- ch = "-" → cmd_dec: decode
- cmd_dec → op = 1: OP_SUB is 1
- op = 1 → alu: 1 is OP_AND
- alu → y = a & b: runs
- calc_pkg → cmd_dec: import
Two typedefs with the same name in two modules are two types. Nothing compares them.
A Package: One Declaration, Many Users
A typedef gives a type a name. Declared inside a module, the name is private to that module. A package is a named box of declarations that any module can use.
lim_pkg and calls clamp builds 13 cells on this flow. The package itself builds nothing.package lim_pkg;
typedef logic [7:0] level_t; // a type
localparam level_t TOP = 8'd200; // a constant
function automatic level_t clamp(input level_t v);
return (v > TOP) ? TOP : v; // a function: logic, copied at each call
endfunction
endpackageA package describes no hardware of its own. Synthesis copies what each module uses into that module. That decides what a package may hold.
| In the package | This flow | Measured |
|---|---|---|
typedef, enum, struct | builds | the lab: 122 cells |
localparam or parameter constant | builds | a constant, folded into the logic |
function automatic | builds | a copy of the logic at each call (lesson R11.3) |
a variable, such as logic [3:0] hits;, that a module writes | refused | Yosys stops with Internal frontend error; Lint is silent; Verilator simulates it as shared state |
const logic [7:0] MAGIC = 8'ha5; | refused | the same Yosys error: a const is still a variable |
a function with no automatic | do not use | Lint: IMPLICITSTATIC; its variables are shared between calls in simulation |
A package variable would be a wire between modules with no port. Use localparam for a constant in a package.
Three Ways to Reach an Item
| Form | Example | What it makes visible |
|---|---|---|
| Scope operator | calc_pkg::op_t | that one use; nothing is imported |
| Explicit import | import calc_pkg::op_t; | the name op_t only |
| Wildcard import | import calc_pkg::*; | every name in the package, each one only when the code uses it |
Place the import between the module name and the port list. Then the ports can use the types, as the lab fix does.
Imports can collide with each other and with local names. The tools do not agree on every case.
| Case | Icarus 12 | Verilator 5.052 | Yosys (slang) |
|---|---|---|---|
A local LIMIT and a wildcard import that has LIMIT | the local one wins | the local one wins; Lint warns VARHIDDEN | the local one wins |
A local LIMIT and import lim_pkg::LIMIT; | 'LIMIT' has already been imported into this scope | accepted, the local one wins | redefinition of 'LIMIT' |
Two wildcard imports that both have data_t, and the code uses it | Ambiguous use of 'data_t' | accepted: it took the first package, 32 bits | multiple imports found for identifier 'data_t' |
The same two imports, data_t never used bare | runs | runs | builds |
import st_pkg::state_t; and then the label RUN | Unable to bind wire/reg/memory 'RUN' | Can't find definition of variable: 'RUN' | use of undeclared identifier 'RUN' |
Row 3 is the dangerous one. Verilator 5.052 picked a type without a message, and Lint is the same tool. The other two refused.
export: Passing a Package On
A package can import another package. Its own importers do not see those names unless it exports them.
q=5a for d=a5. With the export line removed it stops: Can't find typedef/interface: 'byte_t', and Yosys says use of undeclared identifier 'byte_t'.package base_pkg;
typedef logic [7:0] byte_t;
endpackage
package soc_pkg;
import base_pkg::*;
export base_pkg::byte_t; // pass byte_t on to whoever imports soc_pkg
function automatic byte_t swap(input byte_t b);
return {b[3:0], b[7:4]};
endfunction
endpackage
module m
import soc_pkg::*; // one import; byte_t arrives through the chain
(
input byte_t d,
output byte_t q
);
assign q = swap(d);
endmoduleCompile Order
A package must be read before the code that uses it. With one file per package and per module, the order of the file list matters.
- File
- Structure
- Packages first
Both modules name types from
calc_pkgin their port lists. The tool must know those types when it reads the ports. - Modules in any order
An instance is resolved after all files are read.
calc.svcan come before or after the modules it instantiates.
Read the diagram as text
- calc_pkg.sv: types and constants
- cmd_dec.sv: imports calc_pkg
- alu.sv: imports calc_pkg
- calc.sv: instantiates both
- calc_pkg.sv → cmd_dec.sv: before
- calc_pkg.sv → alu.sv: before
- cmd_dec.sv → calc.sv: any order
- alu.sv → calc.sv: any order
Only declarations need an order. Module instances do not.
| Tool | Package file first | Module file first |
|---|---|---|
| Icarus 12 | runs | alu.sv:2: syntax error then I give up. |
| Verilator 5.052 (Run and Lint) | runs | Reference to 'op_t' before declaration |
| Yosys 0.70 with slang (Synthesize) | 133 cells | 133 cells: it reads every file before it resolves names |
A recorded run: an 8-bit ALU in alu.sv and its package in alu_pkg.sv, given to each tool in both orders.
On this site, Run reads the bench first and then main.sv. Lint and Synthesize read main.sv alone. So the lab keeps its package at the top of main.sv.
$unit: Declarations Outside Any Module
A typedef written outside every module and package lands in a space called $unit. It looks global. What it reaches depends on how the tool was started.
| Files | Icarus 12 | Verilator 5.052 | Yosys (slang) |
|---|---|---|---|
a.sv declares data_t outside its module; b.sv uses it; order a, b | runs | runs | use of undeclared identifier 'data_t' |
| the same two files; order b, a | syntax error | Reference to 'data_t' before declaration | use of undeclared identifier 'data_t' |
a.sv and b.sv each declare their own data_t, 8 and 4 bits | Type identifier 'data_t' has already been declared in this scope | Duplicate declaration of TYPEDEF 'data_t' | builds: 14 cells, each file with its own type |
The two simulators put all files in one $unit. Yosys gives each file its own. The same source means three different things.
A package has none of this. Its name says where a declaration lives, and every tool agrees on it. Keep nothing in $unit.
define, parameter or a Package Constant
| A macro (the define directive) | parameter int WIDTH = 8 | package localparam int WIDTH = 8 | |
|---|---|---|---|
| What it is | text, pasted where it is used | a typed constant of one module | a typed constant with one home |
| Who sees it | every line read after it, in every later file | that module | whoever names or imports the package |
| Can differ per instance | no | yes: #(.WIDTH(12)) | no |
| Depends on file order | yes | no | only that the package comes first |
| Use it for | conditional compilation, such as the SYNTHESIS guard of lesson R7.2 | a size that each instance chooses | a value that the whole design shares |
One more kind of constant exists. const makes a variable that is assigned once. It is useful inside a function, where a parameter cannot be declared. On this flow a function with a local const built 13 cells.
The Lab: One Copy of the Opcode Type
| Port | Direction | Width | Meaning |
|---|---|---|---|
| ch | input | [7:0] | the command: +, -, & or ^ |
| a, b | input | [7:0] | the operands |
| y | output | [7:0] | the result of the command |
- Latency
- combinational
- Corner cases
- the two opcodes that sit in the middle of the list. Done when: Run prints
12 - 10 = 2and12 & 10 = 8, and both modules takeop_tfrom one package
Run as shipped
The
+and^lines are right. The-line prints 8 and the&line prints 2. Lint prints nothing.Find the two copies
Each module has its own
op_t. The decoder lists ADD, SUB, AND, XOR. The ALU lists ADD, AND, SUB, XOR. The port between them is two plain bits.Make one package
Add
calc_pkgat the top ofmain.svwith the type. Delete both local typedefs. Import the package in each module header and type theopports asop_t.Run and Synthesize
Run prints 22, 2, 8 and 6. Synthesize reports 122 cells and 21 levels. The shipped file was 121 cells: the package costs nothing.
The fix: calc_pkg and three headers
package calc_pkg;
typedef enum logic [1:0] { OP_ADD, OP_SUB, OP_AND, OP_XOR } op_t; // the one copy
typedef logic [7:0] word_t;
endpackage
module cmd_dec
import calc_pkg::*; // in the header, so the ports can use op_t
(
input logic [7:0] ch,
output op_t op
);
// the same case statement
endmodule
module alu
import calc_pkg::*;
(
input op_t op,
input word_t a, b,
output word_t y
);
// the same case statement
endmodule
module calc
import calc_pkg::*;
(
input logic [7:0] ch,
input word_t a, b,
output word_t y
);
op_t op;
cmd_dec u_dec (.ch(ch), .op(op));
alu u_alu (.op(op), .a(a), .b(b), .y(y));
endmoduleAsked in interviews
Why use a package and not a header file of macros?
A package item has a type and one home. A macro is text that reaches every file read after it. It depends on file order and can be redefined without a message.
What may a synthesizable package contain?
Types,
localparamconstants and automatic functions. Synthesis copies them into each module that uses them. It does not build package variables, because they would connect modules without ports.What is
$unit, and why avoid it?It is the space for declarations outside any module or package. Tools that compile all files together share one. Tools that compile files separately have one per file. The same source can mean different things.
Try It
The bench sends four command characters with a at 12 and b at 10. Subtract should give 2 and AND should give 8. The shipped design swaps them.
The decoder sends 1 for -. The ALU reads 1 with its own copy of the enum, where 1 means AND.
Synthesize reports 121 cells, 0 flops, 0 latches and 21 levels. With one package the count is 122 cells and the same 21 levels.
Synthesize the design to measure its cells and inspect the mapped gates.
12 + 10 = 22 12 - 10 = 8 12 & 10 = 2 12 ^ 10 = 6Original design · 121 cells · 0 flip-flops · 0 latches · 21 logic levels. Synthesis uses Yosys; counts depend on the toolchain.
Read included file: tb.sv
// The bench uses plain vectors. It compiles before main.sv, so it cannot import a package from it.
module tb;
logic [7:0] ch, a = 8'd12, b = 8'd10, y;
calc dut (.*);
task automatic show(input logic [7:0] c);
ch = c; #1;
$display("12 %s 10 = %0d", ch, y);
endtask
initial begin
show("+"); show("-"); show("&"); show("^");
$finish(0);
end
endmodule
Check Yourself
Common Mistakes
Wrong Import the package inside the module body and then use its types in the port list.
The port list is read before the body, so the type names are not known there yet.
Fix Put the import between the module name and the port list.
module alu (
input op_t op, // op_t is not known yet
output word_t y
);
import calc_pkg::*;module alu
import calc_pkg::*;
(
input op_t op,
output word_t y
);Wrong Keep a counter or a flag as a variable in a package so that two modules can share it.
A package variable is a hidden wire between modules with no port, and synthesis does not build it.
Fix Pass shared state through ports. Keep only types, localparam constants and automatic functions in a package.
Wrong Import only the enum type, as import st_pkg::state_t;, and then write its labels.
An explicit import brings one name, and the labels of an enum are names of their own.
Fix Use a wildcard import, or write st_pkg::RUN, or import each label you use.
Wrong Trust a build that passes in simulation to pass in synthesis with the same file list.
The tools read file lists differently: here the simulators needed the package first, and Yosys did not care.
Fix List packages first in every file list, so that the strictest tool is satisfied.
Remember
- Two typedefs with one name in two modules are two types. A package holds the one copy.
- A synthesizable package holds types,
localparamconstants and automatic functions. It holds no variables. - Import in the module header. A local name wins over a wildcard import, and an enum type does not bring its labels.
- Read packages before their users. The simulators here require it; list them first for every tool.
- Keep nothing in
$unit: the simulators here share one across files, and Yosys gives each file its own.
Practice
Quick reference: typedef enum and Its Methods