Three ways sharing breaks

Two-package benches never collide. Forty-package SoC benches with three vendors fail in three escalating ways: ambiguity errors the compiler reports, silent shadowing it does not, and latent breakage that arrives with a vendor next release.

Enum members make all three worse. Every member name lands in the importing namespace beside the type, and every protocol package on earth defines an IDLE. Unprefixed members are a guaranteed future clash.

1
2
3
4
5
6
7
8
9
10
11
12

// bad-example: two wildcards, one shared name
package axi_pkg;
  typedef enum logic [1:0] { AXI_IDLE, AXI_MOVE, AXI_DONE, AXI_ERR } status_e;
endpackage
package pcie_pkg;
  typedef enum logic [1:0] { PCIE_IDLE, PCIE_MOVE, PCIE_DONE, PCIE_ERR } status_e;
endpackage
module tb_clash;
  import axi_pkg::*;
  import pcie_pkg::*;
  status_e s;   // ambiguous: both packages define status_e
endmodule

The leaf-only wildcard rule

Mature codebases converge on one import discipline. Package headers and shared files never wildcard-import: they use explicit imports or fully qualified references, because anything a package imports shapes resolution for everything compiled inside it.

Leaf scopes may wildcard-import: one test class, one testbench top, the inside of one module. The blast radius ends at the scope closing keyword. Where two packages both provide a needed name, qualify at the use site instead of importing either.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

package axi_pkg;
  typedef enum logic [1:0] { AXI_IDLE, AXI_MOVE, AXI_DONE, AXI_ERR } axi_status_e;
  typedef struct packed {
    logic [31:0]   addr;
    axi_status_e   st;
  } axi_txn_t;
  function automatic bit axi_ok(axi_status_e s);
    return (s == AXI_DONE);
  endfunction
endpackage

package pcie_pkg;
  typedef enum logic [1:0] { PCIE_IDLE, PCIE_MOVE, PCIE_DONE, PCIE_ERR } pcie_status_e;
  typedef struct packed {
    logic [31:0]    addr;
    pcie_status_e   st;
  } pcie_txn_t;
  function automatic bit pcie_ok(pcie_status_e s);
    return (s == PCIE_DONE);
  endfunction
endpackage

// Shared code: explicit imports only, qualified rare references.
package soc_env_pkg;
  import axi_pkg::axi_txn_t;
  import pcie_pkg::pcie_txn_t;
  function automatic bit pair_ok(axi_pkg::axi_status_e a, pcie_pkg::pcie_status_e p);
    return (axi_pkg::axi_ok(a) && pcie_pkg::pcie_ok(p));
  endfunction
endpackage

module tb_hygiene;

  timeunit 1ns; timeprecision 1ps;
  import soc_env_pkg::*;   // leaf scope: the blast radius ends here
  axi_pkg::axi_txn_t at;
  pcie_pkg::pcie_txn_t pt;
  int errors = 0;
  initial begin
    at.addr = 32'h1000; at.st = axi_pkg::AXI_DONE;
    pt.addr = 32'h2000; pt.st = pcie_pkg::PCIE_DONE; #1;
    if (pair_ok(at.st, pt.st) !== 1'b1) errors++;
    pt.st = pcie_pkg::PCIE_MOVE; #1;
    if (pair_ok(at.st, pt.st) !== 1'b0) errors++;
    if (at.addr !== 32'h1000) errors++;
    if (pt.addr !== 32'h2000) errors++;
    if (errors != 0) $fatal(1, "FAIL: protocol names collided or crossed in the shared environment");
    $display("PASS: explicit imports and prefixed names keep two protocols side by side");
    $finish;
  end
endmodule

PASS: explicit imports and prefixed names keep two protocols side by side

Prefixes and constant containers

Every name a package exports earns a short package tag: axi_txn_t, AXI_IDLE, pcie_cfg_t. Collisions turn from likely into improbable, and readers can place each name instantly.

Related constants can also hide inside a class scope as static members (classes come in the OOP part), referenced as axi_consts::IDLE. Class members never leak into importer namespaces, which makes the class an airtight constant container. Either habit works; mixing bare global names does not.

Vendor IP package patterns

Commercial VIP shows the pattern to copy. Each VIP ships exactly one public package with prefixed names, one guarded macro header, and one filelist stub that solves compile order for the integrator.

The contract runs both ways. The vendor adds names but never repurposes published ones, since it cannot fix the importing code it would break. Your in-house VIP deserves the same courtesy the moment a second team imports it: public names are an API.

Common mistakes

Related topics

• Next topic: Interfaces, Modports & Clocking Blocks