# uvm_packer

The uvm_packer class provides a policy object for packing and unpacking uvm_objects. The policies determine how packing and unpacking should be done. Packing an object causes the object to be placed into a bit (byte or int) array. If the `uvm_field_* macro are used to implement pack and unpack, by default no metadata information is stored for the packing of dynamic objects (strings, arrays, class objects).

Summary

uvm_packer
The uvm_packer class provides a policy object for packing and unpacking uvm_objects.
Packing |
pack_field | Packs an integral value (less than or equal to 4096 bits) into the packed array.
pack_field_int | Packs the integral value (less than or equal to 64 bits) into the pack array.
pack_bits | Packs bits from upacked array of bits into the pack array.
pack_bytes | Packs bits from an upacked array of bytes into the pack array.
pack_ints | Packs bits from an unpacked array of ints into the pack array.
pack_string | Packs a string value into the pack array.
pack_time | Packs a time value as 64 bits into the pack array.
pack_real | Packs a real value as 64 bits into the pack array.
pack_object | Packs an object value into the pack array.
Unpacking |
is_null | This method is used during unpack operations to peek at the next 4-bit chunk of the pack data and determine if it is 0.
unpack_field | Unpacks bits from the pack array and returns the bit-stream that was unpacked.
unpack_field_int | Unpacks bits from the pack array and returns the bit-stream that was unpacked.
unpack_bits | Unpacks bits from the pack array into an unpacked array of bits.
unpack_bytes | Unpacks bits from the pack array into an unpacked array of bytes.
unpack_ints | Unpacks bits from the pack array into an unpacked array of ints.
unpack_string | Unpacks a string.
unpack_time | Unpacks the next 64 bits of the pack array and places them into a time variable.
unpack_real | Unpacks the next 64 bits of the pack array and places them into a real variable.
unpack_object | Unpacks an object and stores the result into value.
get_packed_size | Returns the number of bits that were packed.
Variables |
physical | This bit provides a filtering mechanism for fields.
abstract | This bit provides a filtering mechanism for fields.
use_metadata | This flag indicates whether to encode metadata when packing dynamic data, or to decode metadata when unpacking.
big_endian | This bit determines the order that integral data is packed (using pack_field, pack_field_int, pack_time, or pack_real) and how the data is unpacked from the pack array (using unpack_field, unpack_field_int, unpack_time, or unpack_real).

### Packing

### pack_field

> virtual function void pack_field (
> | uvm_bitstream_t | value,
> | int | size
> )

Packs an integral value (less than or equal to 4096 bits) into the packed array. size is the number of bits of value to pack.

### pack_field_int

> virtual function void pack_field_int (
> | uvm_integral_t | value,
> | int | size
> )

Packs the integral value (less than or equal to 64 bits) into the pack array. The size is the number of bits to pack, usually obtained by $bits. This optimized version of pack_field is useful for sizes up to 64 bits.

### pack_bits

> virtual function void pack_bits(
> | ref | bit | value[], |  |
> | input | int | size | = | -1
> )

Packs bits from upacked array of bits into the pack array.

See pack_ints for additional information.

### pack_bytes

> virtual function void pack_bytes(
> | ref | byte | value[], |  |
> | input | int | size | = | -1
> )

Packs bits from an upacked array of bytes into the pack array.

See pack_ints for additional information.

### pack_ints

> virtual function void pack_ints(
> | ref | int | value[], |  |
> | input | int | size | = | -1
> )

Packs bits from an unpacked array of ints into the pack array.

The bits are appended to the internal pack array. This method allows for fields of arbitrary length to be passed in, using the SystemVerilog stream operator.

For example

>     bit[511:0] my_field;
>     begin
>       int my_stream[];
>       { << int {my_stream}} = my_field;
>       packer.pack_ints(my_stream);
>     end

When appending the stream to the internal pack array, the packer will obey the value of big_endian (appending the array from MSB to LSB if set).

An optional size parameter is provided, which defaults to ‘-1’. If set to any value greater than ‘-1’ (including 0), then the packer will use the size as the number of bits to pack, otherwise the packer will simply pack the entire stream.

An error will be asserted if the size has been specified, and exceeds the size of the source array.

### pack_string

> virtual function void pack_string (
> | string | value
> )

Packs a string value into the pack array.

When the metadata flag is set, the packed string is terminated by a null character to mark the end of the string.

This is useful for mixed language communication where unpacking may occur outside of SystemVerilog UVM.

### pack_time

> virtual function void pack_time (
> | time | value
> )

Packs a time value as 64 bits into the pack array.

### pack_real

> virtual function void pack_real (
> | real | value
> )

Packs a real value as 64 bits into the pack array.

The real value is converted to a 6-bit scalar value using the function $real2bits before it is packed into the array.

### pack_object

> virtual function void pack_object (
> | uvm_object | value
> )

Packs an object value into the pack array.

A 4-bit header is inserted ahead of the string to indicate the number of bits that was packed. If a null object was packed, then this header will be 0.

This is useful for mixed-language communication where unpacking may occur outside of SystemVerilog UVM.

### Unpacking

### is_null

> virtual function bit is_null ()

This method is used during unpack operations to peek at the next 4-bit chunk of the pack data and determine if it is 0.

If the next four bits are all 0, then the return value is a 1; otherwise it is 0.

This is useful when unpacking objects, to decide whether a new object needs to be allocated or not.

### unpack_field

> virtual function uvm_bitstream_t unpack_field (
> | int | size
> )

Unpacks bits from the pack array and returns the bit-stream that was unpacked. size is the number of bits to unpack; the maximum is 4096 bits.

### unpack_field_int

> virtual function uvm_integral_t unpack_field_int (
> | int | size
> )

Unpacks bits from the pack array and returns the bit-stream that was unpacked.

size is the number of bits to unpack; the maximum is 64 bits. This is a more efficient variant than unpack_field when unpacking into smaller vectors.

### unpack_bits

> virtual function void unpack_bits(
> | ref | bit | value[], |  |
> | input | int | size | = | -1
> )

Unpacks bits from the pack array into an unpacked array of bits.

### unpack_bytes

> virtual function void unpack_bytes(
> | ref | byte | value[], |  |
> | input | int | size | = | -1
> )

Unpacks bits from the pack array into an unpacked array of bytes.

### unpack_ints

> virtual function void unpack_ints(
> | ref | int | value[], |  |
> | input | int | size | = | -1
> )

Unpacks bits from the pack array into an unpacked array of ints.

The unpacked array is unpacked from the internal pack array. This method allows for fields of arbitrary length to be passed in without expanding into a pre-defined integral type first.

For example

>     bit[511:0] my_field;
>     begin
>       int my_stream[] = new[16]; // 512/32 = 16
>       packer.unpack_ints(my_stream);
>       my_field = {<<{my_stream}};
>     end

When unpacking the stream from the internal pack array, the packer will obey the value of big_endian (unpacking the array from MSB to LSB if set).

An optional size parameter is provided, which defaults to ‘-1’. If set to any value greater than ‘-1’ (including 0), then the packer will use the size as the number of bits to unpack, otherwise the packer will simply unpack the entire stream.

An error will be asserted if the size has been specified, and exceeds the size of the target array.

### unpack_string

> virtual function string unpack_string (
> | int | num_chars | = | -1
> )

Unpacks a string.

num_chars bytes are unpacked into a string. If num_chars is -1 then unpacking stops on at the first null character that is encountered.

### unpack_time

> virtual function time unpack_time ()

Unpacks the next 64 bits of the pack array and places them into a time variable.

### unpack_real

> virtual function real unpack_real ()

Unpacks the next 64 bits of the pack array and places them into a real variable.

The 64 bits of packed data are converted to a real using the $bits2real system function.

### unpack_object

> virtual function void unpack_object (
> | uvm_object | value
> )

Unpacks an object and stores the result into value.

value must be an allocated object that has enough space for the data being unpacked. The first four bits of packed data are used to determine if a null object was packed into the array.

The is_null function can be used to peek at the next four bits in the pack array before calling this method.

### get_packed_size

> virtual function int get_packed_size()

Returns the number of bits that were packed.

### Variables

### physical

> bit physical = 1

This bit provides a filtering mechanism for fields.

The abstract and physical settings allow an object to distinguish between two different classes of fields. It is up to you, in the uvm_object::do_pack and uvm_object::do_unpack methods, to test the setting of this field if you want to use it as a filter.

### abstract

> bit abstract

This bit provides a filtering mechanism for fields.

The abstract and physical settings allow an object to distinguish between two different classes of fields. It is up to you, in the uvm_object::do_pack and uvm_object::do_unpack routines, to test the setting of this field if you want to use it as a filter.

### use_metadata

> bit use_metadata

This flag indicates whether to encode metadata when packing dynamic data, or to decode metadata when unpacking. Implementations of uvm_object::do_pack and uvm_object::do_unpack should regard this bit when performing their respective operation. When set, metadata should be encoded as follows:

- For strings, pack an additional null byte after the string is packed.
- For objects, pack 4 bits prior to packing the object itself. Use 4’b0000 to indicate the object being packed is null, otherwise pack 4’b0001 (the remaining 3 bits are reserved).
- For queues, dynamic arrays, and associative arrays, pack 32 bits indicating the size of the array prior to packing individual elements.

### big_endian

> bit big_endian = 1

This bit determines the order that integral data is packed (using pack_field, pack_field_int, pack_time, or pack_real) and how the data is unpacked from the pack array (using unpack_field, unpack_field_int, unpack_time, or unpack_real). When the bit is set, data is associated msb to lsb; otherwise, it is associated lsb to msb.

The following code illustrates how data can be associated msb to lsb and lsb to msb:

>     class mydata extends uvm_object;

>       logic[15:0] value = 'h1234;

>       function void do_pack (uvm_packer packer);
>         packer.pack_field_int(value, 16);
>       endfunction

>       function void do_unpack (uvm_packer packer);
>         value = packer.unpack_field_int(16);
>       endfunction
>     endclass

>     mydata d = new;
>     bit bits[];

>     initial begin
>       d.pack(bits);  // 'b0001001000110100
>       uvm_default_packer.big_endian = 0;
>       d.pack(bits);  // 'b0010110001001000
>     end

> virtual function void pack_field (
> | uvm_bitstream_t | value,
> | int | size
> )

Packs an integral value (less than or equal to 4096 bits) into the packed array.

> virtual function void pack_field_int (
> | uvm_integral_t | value,
> | int | size
> )

Packs the integral value (less than or equal to 64 bits) into the pack array.

> virtual function void pack_bits(
> | ref | bit | value[], |  |
> | input | int | size | = | -1
> )

Packs bits from upacked array of bits into the pack array.

> virtual function void pack_bytes(
> | ref | byte | value[], |  |
> | input | int | size | = | -1
> )

Packs bits from an upacked array of bytes into the pack array.

> virtual function void pack_ints(
> | ref | int | value[], |  |
> | input | int | size | = | -1
> )

Packs bits from an unpacked array of ints into the pack array.

> virtual function void pack_string (
> | string | value
> )

Packs a string value into the pack array.

> virtual function void pack_time (
> | time | value
> )

Packs a time value as 64 bits into the pack array.

> virtual function void pack_real (
> | real | value
> )

Packs a real value as 64 bits into the pack array.

> virtual function void pack_object (
> | uvm_object | value
> )

Packs an object value into the pack array.

> virtual function bit is_null ()

This method is used during unpack operations to peek at the next 4-bit chunk of the pack data and determine if it is 0.

> virtual function uvm_bitstream_t unpack_field (
> | int | size
> )

Unpacks bits from the pack array and returns the bit-stream that was unpacked.

> virtual function uvm_integral_t unpack_field_int (
> | int | size
> )

Unpacks bits from the pack array and returns the bit-stream that was unpacked.

> virtual function void unpack_bits(
> | ref | bit | value[], |  |
> | input | int | size | = | -1
> )

Unpacks bits from the pack array into an unpacked array of bits.

> virtual function void unpack_bytes(
> | ref | byte | value[], |  |
> | input | int | size | = | -1
> )

Unpacks bits from the pack array into an unpacked array of bytes.

> virtual function void unpack_ints(
> | ref | int | value[], |  |
> | input | int | size | = | -1
> )

Unpacks bits from the pack array into an unpacked array of ints.

> virtual function string unpack_string (
> | int | num_chars | = | -1
> )

Unpacks a string.

> virtual function time unpack_time ()

Unpacks the next 64 bits of the pack array and places them into a time variable.

> virtual function real unpack_real ()

Unpacks the next 64 bits of the pack array and places them into a real variable.

> virtual function void unpack_object (
> | uvm_object | value
> )

Unpacks an object and stores the result into value.

> virtual function int get_packed_size()

Returns the number of bits that were packed.

> bit physical = 1

This bit provides a filtering mechanism for fields.

> bit abstract

This bit provides a filtering mechanism for fields.

> bit use_metadata

This flag indicates whether to encode metadata when packing dynamic data, or to decode metadata when unpacking.

> bit big_endian = 1

This bit determines the order that integral data is packed (using pack_field, pack_field_int, pack_time, or pack_real) and how the data is unpacked from the pack array (using unpack_field, unpack_field_int, unpack_time, or unpack_real).

> virtual function void do_pack (
> | uvm_packer | packer
> )

The do_pack method is the user-definable hook called by the pack methods.

> virtual function void do_unpack (
> | uvm_packer | packer
> )

The do_unpack method is the user-definable hook called by the unpack method.