Structs and unions

A struct groups named fields

A struct bundles related fields under one name, so instead of slicing hdr[11:0] all over the testbench you write hdr.addr.

With typedef, the struct becomes a reusable type: typedef struct packed { logic [3:0] kind; logic [11:0] addr; } hdr_t;. You then declare hdr_t h; wherever the testbench needs a header.

A packed struct is stored as one vector whose width is the sum of its field widths, here 4 + 12 = 16 bits. You can assign it to a logic [15:0] bus, compare it with == and print it in hex.

The first field is the most significant

In a packed struct, the first declared field occupies the top bits, and each later field sits directly below the one before it. The last field always ends at bit 0.

Reverse the declaration and the same field values produce 16'h1232, yet both versions compile and look reasonable. Only the spec decides which one is right, so copy the field order from its bit table, top bit first.

typedef struct packed {
  logic [11:0] addr;   // bits 15:4
  logic [3:0]  kind;   // bits 3:0
} hdr_t;

typedef struct packed {
  logic [3:0]  kind;   // bits 15:12
  logic [11:0] addr;   // bits 11:0
} hdr_t;

Packed and unpacked structs

Every field of a packed struct must itself be packed: logic, bit, packed arrays, enums or other packed structs. A string, a real number or an unpacked array cannot go inside one.

A struct declared without packed is unpacked, which means it can hold fields of any type but is a record rather than a vector. Use unpacked structs for testbench bookkeeping, and packed structs for anything that travels on a wire.

A union is one set of bits with several names

A union gives several names to the same storage. In a packed union, every member must have the same width, so each member is a different view of the same bits.

typedef union packed { hdr_t f; logic [15:0] raw; } hdr_u; lets you write the bus into u.raw and then read u.f.kind and u.f.addr without any slicing.

Writing one member changes what every other member reads. After u.raw = 16'h5A10, for example, u.f.kind reads as 5 and u.f.addr reads as 12'hA10.

Unions suit fields that the spec defines in more than one way. A 32-bit word might be a header in one bus phase and raw data in the next, and the union gives each reading its own field names.

A union does not record which member was written last, so nothing stops you from reading bits as a header when they were meant as something else. Keep union reads close to the code that captures the bus.

Structs inside structs

A packed struct can contain another packed struct. A packet made of a header and a data word is typedef struct packed { hdr_t hdr; logic [31:0] data; } pkt_t;, which is 48 bits wide.

The same ordering rule applies at every level: hdr is declared first, so it fills bits 47 to 32, and data fills bits 31 to 0. Inside hdr, the kind field is still the top nibble.

You reach a nested field with a chain of names, such as p.hdr.addr. Because the whole packet is one vector, p == expected compares all 48 bits at once, and the error message can then name the field that differs.

Check the width

Assigning a wider value to a packed struct keeps only the low bits and reports no error. For example, assigning 20'hB7123 to a 16-bit hdr_t quietly stores 16'h7123.

$bits(hdr_t) returns the width of the struct, so compare it with the bus width once at the start of the test. A field added later then cannot shift the layout without causing a failure.

Try it

Setting the two fields builds 16'h2123, with kind on top. Writing u.raw and reading u.f shows the union sharing one set of bits, and writing u.f.addr changes u.raw.

The last line drops the top 4 bits of the 20-bit value without any message. Swap the two fields in hdr_t, predict every line, then run it.

Check yourself

module tb;
  typedef struct packed {
    logic [1:0] op;
    logic [5:0] len;
  } cmd_t;
  cmd_t c;
  initial begin
    c.op  = 2'b10;
    c.len = 6'd5;
    $display("%h", c);
  end
endmodule

return {addr, kind};

hdr_t h;
h.kind = kind;
h.addr = addr;
return h;

return {kind, addr};

return (kind << 12) | addr;

Practice

• Header field decoder Implement · Easy