How to Pack Data Using the SystemVerilog Streaming Operators (>>, <<)

5 min reading

The verification of digital circuits requires dealing with bits and bytes. It is not a trivial thing to pack or unpack bits, bytes, half words, words or user defined data structures.

This post is the first in a series of tutorials about packing and unpacking in SystemVerilog.

The article’s sections are:

Introduction
1. Pack bytes into an int
1.1 Byte variables to an int
1.2 Array of bytes to an int
2. Reverse the elements of a byte array and pack them into an int
3. Reverse the bits in a byte
4. Reverse the nibbles in a byte
5. Reverse the bits of an array and pack them into a shortint
6. Advanced packing
References

Introduction

When doing packing/unpacking operations in SystemVerilog, a simple bit-stream cast is often enough:

typedef struct {
  bit [7:0] address;
  bit [7:0] payload[2];
} packet;

typedef bit [7:0] data_stream[$];
// ...
packet      pkt;
data_stream stream;
// ...
stream = { stream, data_stream'(pkt) };

For extra flexibility, streaming operators can be used in the cases where the bit ordering is important or a simple bit-stream cast is not sufficient..

There are two streaming operators, {>>{}} and {<<{}}, which operate on data blocks (or slices). By default, slices have the size 1, but the slice size can be changed according to the needs. Using {>>{}} will cause the data blocks to be streamed from left to right, while {<<{}} will stream the data blocks from right to left.

Because an image is worth a thousand words, I’ll use graphics to show how to use the streaming operators and how the individual bits are affected by the stream operators.

1. Pack bytes into an int

1.1 Byte variables to an int

When we need to pack several variables into a single variable, we can use the left-to-right streaming operator ( {>>{}} ).

module example_1_1;
  initial begin
    static byte a     = 8'h8C;
    static byte b     = 8'h00;
    static byte c     = 8'hA4;
    static byte d     = 8'hFF;
    static int  value = {>>{a, b, c, d}};

    $display("value = 0x%h", value);
  end
endmodule

Specifying a slice size for left-to-right streaming operator ( {>>{}} ) has the same effect as using the default slice size of 1. This means that {>>{}} is the same as {>>4{}}, {>>8{}}, or any other value.

1.2 Array of bytes to an int

Packing an array of bytes into a single variable is just as easy:

module example_1_2;
  initial begin
    static bit [7:0] array[4] = '{ 8'h8C, 8'h00, 8'hA4, 8'hFF };
    static int       value    = {>>{array}};

    $display("value = 0x%h", value);
  end
endmodule

2. Reverse the elements of a byte array and pack them into an int

We can reverse the order of an array’s elements and then pack them into a single value in the following way:

module example_2;
  initial begin
    static bit [7:0] array[4] = '{ 8'h8C, 8'h00, 8'hA4, 8'hFF };
    static int       value    = {<<8{array}};

    $display("value = 0x%h", value);
  end
endmodule

If the slice size would be 16 instead of 8, the output value would be 0xA4FF_8C00.

3. Reverse the bits in a byte

Below is an easy way to reverse the order of the bits within a byte. The slice size defaults to 1 if it is not specified. The slice size is a resolution/granularity like concept.

module example_3;
  initial begin
    static bit [7:0] value_a = 8'h8C;
    static bit [7:0] value_b = {<<{value_a}};

    $display("value_b = 0x%h", value_b);
  end
endmodule

If the slice size would be 2 instead of 1, the bits would be reversed in groups of 2, leading to an output value of 8’b00_11_00_10.

If the slice size would be 3, groups of 3 bits would be created starting from the least significant 3 bits. Since we have an 8-bit input value, the last (leftmost) group will contain the remaining 2 bits. No padding or truncation is performed. The bit group reversing would then be performed, leading to the output value 8’b100_001_10.

4. Reverse the nibbles in a byte

A byte contains a low nibble and a high nibble. The order of the nibbles inside the byte can be reversed using the right-to-left streaming operator with a slice size of 4:

module example_4;
  initial begin
    static bit [7:0] value_a = 8'h8C;
    static bit [7:0] value_b = {<<4{value_a}};

    $display("value_b = 0x%h", value_b);
  end
endmodule

5. Reverse the bits of an array and pack them into a shortint

Reversing the elements of an array and, at the same time, the bits of each element of the array is easily achievable using the right-to-left streaming operator:

module example_5;
  initial begin
    static bit [7:0] array[2] = '{ 8'h8C, 8'hA4 };
    static shortint  value    = {<<{array}};

    $display("value = 0x%h", value);
  end
endmodule

6. Advanced packing

In this final example, we’ll take an array of 2-bit values and pack it into a structure. The ordering scheme used for the values in the array is little endian. We can achieve this by taking the result of a right-to-left streaming operator with a slice size of 2, and feeding it as input to another right-to-left streaming operator with a slice size of 4:

module example_6;
  typedef struct {
    bit [3:0] addr;
    bit [3:0] data;
  } packet_t;

  initial begin
    static bit [1:0] array[] = '{ 2'b10, 2'b01, 2'b11, 2'b00 };
    static packet_t  packet  = {<<4{ {<<2{array}} }};

    $display("packet addr = %b", packet.addr);
    $display("packet data = %b", packet.data);
  end
endmodule

If the ordering scheme is big endian, the packing can be performed with a single right-to-left streaming operator ( {>>{}} ), using the default slice size.

References

The above diagrams have been created using an open source design tool called Inkscape. Stay tuned for more packing/unpacking tutorials (>, <<)">Unpacking using streaming operators and UVM pack/unpack).

Comments

26 Responses

Gaurav Gupta says:

June 28, 2017 at 9:50 am

Very helpful post to get the basics cleared.

Reply
1. Horia-Răzvan Enescu says:
  
  September 5, 2017 at 12:27 pm
  
  Thank you Gaurav, I’m glad that it was useful for you!
mukund sojitra says:

September 1, 2017 at 7:42 pm

very well explained. Thank you so much
please keep adding new example

Reply
1. Horia-Răzvan Enescu says:
  
  September 5, 2017 at 12:38 pm
  
  Thank you Mukund! Do you have any particular example in mind that you would like to view?
Varun says:

September 17, 2017 at 9:57 pm
```
function void fill_pkt_data();
   int pkt_data_size;
   pkt_data_size = $urandom_range(8,24);
   //make it double word aligned (multiple of 4)
   pkt_data_size = (pkt_data_size >> 2) <<2;
   // build the list of data
   for(int i=0; i < pkt_data_size; i++) begin
      pkt_data.push_back($urandom());
   end
 endfunction
```
Would you guys be able to tell me what this piece of code is doing
Reply
1. Stefan Birman says:
  
  September 18, 2017 at 11:15 am
  
  Hi Varun!
  It is not much to say: the code is self-explanatory and the are also some comments.
2. Horia-Răzvan Enescu says:
  
  September 18, 2017 at 12:00 pm
  
  Also, note that the >> and << operators in your code are not streaming operators, but shift operators.
huseng says:

September 18, 2018 at 4:21 pm

Really nice explanation .
Thanks and Best regards!

Reply
Anargha says:

November 30, 2018 at 2:05 am

Hi,

In this line
static int value = {<<8{array}};

while reversing elements, instead of 8, can I use a variable? For ex:

int a = 4
static int value = {<<a{array}};

Would this be acceptable?

Reply
1. Cristian Bob says:
  
  December 6, 2018 at 5:19 pm
  Hi, Anargha.
  
  Unfortunately it is not possible to use the streaming operators with a variable or a const variable. You can use a parameter instead.
  
  A parameterized version of example_2:
```
module example_2;
  
  parameter a=8;

  initial begin
    static bit [7:0] array[4] = '{ 8'h8C, 8'h00, 8'hA4, 8'hFF };
    static int       value    = {<<a{array}};

    $display("value = 0x%h", value);
  end
endmodule 
```
  Another workaround to this problem would be utilizing MACROs.
```
`define A 8

module example_2;
  initial begin
    static bit [7:0] array[4] = '{ 8'h8C, 8'h00, 8'hA4, 8'hFF };
    static int       value    = {<<`A{array}};

    $display("value = 0x%h", value);
  end
endmodule
```
Sharan says:

December 8, 2018 at 5:34 pm

Please note that example 2 shows different value than what is described.
I tried this as I got a doubt looking at the example.

This is the output: value = 0xffa4008c

Reply
1. Mihai says:
  
  December 11, 2018 at 2:05 pm
  
  What do you mean ? Example 2 shows the exact same output value: 0xffa4008c.
David Larson says:

January 11, 2019 at 11:09 pm

So let’s say that you are packing into a variable that is wider than the source data.

byte src_data[$] = {‘hAA, ‘hBB, ‘hCC, ‘hDD};
uvm_reg_data_t reg_data = {>>byte{pkt.data}};

This will pack the info from src_data into reg_data starting at the MSB, so it is left shifted:

reg_data = ‘hAABBCCDD00000000

That is not what I want. I want it right shifted:

reg_data = ‘hAABBCCDD

How to get this right?

Reply
1. Dragos Dospinescu says:
  
  January 15, 2019 at 12:39 pm
  Hi David,
  
  There is no direct way that I know of to achieve what you need only using packing/unpacking operations.
  I did however explore a couple of possibilities, which I will show below.
  
  One option would be to shift the result by the number of bits needed to get rid of the padding.
```
byte src_data[$] = {'hAA, 'hBB, 'hCC, 'hDD};
uvm_reg_data_t reg_data = {>>byte{src_data}};
  
// $bits(reg_data) = size (in bits) of the destination variable.
// $bits(src_data) = size (in bits) of the source data.
// The difference in bits represent exactly the number of '0's padded to the right.
// Shift right the register to get rid of right padded 0s.
reg_data >>= ($bits(reg_data) - $bits(src_data));
```
  The second option is to reverse the packet’s data bytes before packing it into the register, and then reversing the bytes in the register.
  Example:
```
byte src_data[$] = {'hAA, 'hBB, 'hCC, 'hDD};
uvm_reg_data_t reg_data;

// reverse the bytes in the data packet
src_data.reverse();
// pack the reversed data into the register
reg_data = {>>byte{src_data}}; // register now contains 'hDDCCBBAA_00000000
// reverse the bytes in the register
reg_data = {<<byte{reg_data}}; // register now contains 'h00000000_AABBCCDD
```
  Option 2 is far less efficient because it involves more operations, but it doesn’t rely on the $bits system function, which does not work with dynamic arrays for all simulators.
  So, in the end you will have to experiment to see what suits your needs.
  If you find a better alternative, please share your solution.
  
  Regards,
  Dragos
2. David Larson says:
  
  January 15, 2019 at 7:18 pm
  
  Thank you Dragos. I didn’t think of the second solution, I like it. I suspect that we can skip src_data.reverse() by packing the reg_data using the right to left streaming operator and let it reverse the bytes for us (unconfirmed):
  
  reg_data = {<<byte{src_data}}; // register now contains 'hDDCCBBAA_00000000
  reg_data = {<<byte{reg_data}}; // register now contains 'h00000000_AABBCCDD
  
  I'll experiment with it.
  
  Thanks,
  David
3. Dragos Dospinescu says:
  
  January 16, 2019 at 11:02 am
  Hi David,
  
  You are correct indeed. I just checked your version of the solution and it seems to work just fine.
```
byte src_data[$] = {'hAA, 'hBB, 'hCC, 'hDD};
uvm_reg_data_t reg_data;

// reverse the bytes in the data packet
reg_data = {<<byte{src_data}}; // register now contains 'hDDCCBBAA_00000000
// reverse the bytes in the register
reg_data = {<<byte{reg_data}}; // register now contains 'h00000000_AABBCCDD
```
  Thanks for your input.
  
  Best Regards,
  Dragos
ElPrg says:

February 14, 2019 at 10:20 pm

Thank you for post. I had some question : what program you used for pictures ?

Reply
1. Aurelian Ionel Munteanu says:
  
  February 15, 2019 at 9:55 am
  
  I’m glad you like it. It is written in the last paragraph:
  
  The above diagrams have been created using an open source design tool called Inkscape.
Jakub says:

February 12, 2020 at 7:33 pm
Greetings. Thanks for this great page, i keep coming back to it. Any thoughts on how streams can work with 2D dynamic arrays?
```
bit a [][];
int width;
int length;
int filler = 'h1234abcd;

a = new[length]
foreach(a[i])
  a[i] = new[width]
```
now i want to fill each element of the array with filler[width-1:0]. So for example if width is 16 and length is 5, the resulting table looks like
abcd
abcd
abcd
abcd
abcd

the ugly way:
```
foreach(a[i])
  foreach(a[i][j])
    a[i][j] = filler[j];
```
this works too
```
foreach(a[i])
   a[i] = {<<{filler}};
```
is there anyway to assign a in a one-liner? I think the idea would be
```
a = {<<width{filler}};
```
but that does not compile because width is a variable.
Reply
Sahil says:

March 22, 2021 at 9:57 pm

Amazing Article.. bookmarking now.. Thanks alot!

Reply
Andrew says:

July 14, 2021 at 6:53 am

Very good article!
Thanks

Reply
Sai says:

December 1, 2021 at 8:45 pm

Greetings. This is a great article.

But I have a doubt in the last section: 6.) Advanced packing.
The last sentence says: “If the ordering scheme is big endian, the packing can be performed with a single right-to-left streaming operator ( {>>{}} ), using the default slice size.”

So, should I just use:

static packet_t packetBigEndian = {>>{array}};

for big-endian ordering scheme? How is it big-endian? Can someone please explain?
Thanks in advance…

Reply
1. Gabriel says:
  
  December 22, 2021 at 1:33 pm
  Hi Sai,
  The order is big-endian because it’s the way we chose to interpret the data and it refers to the data in the array, not the resulting packet. If the data is adjusted, using that right to left streaming operator, it should return the same result as the first example. In both cases, the packet’s arrays are little-endian.
```
static bit [1:0] array_little_endian[] = '{ 2'b10, 2'b01, 2'b11, 2'b00 };
static bit [0:1] array_big_endian[] = { 2'b01, 2'b10, 2'b00, 2'b11};
static packet_t  packet;
packet = {<<4{ {<<2{array_little_endian}} }};
$display("packet addr = %b", packet.addr);
$display("packet data = %b", packet.data);
packet = {>>{array_big_endian}};
$display("packet addr = %b", packet.addr);
$display("packet data = %b", packet.data);
```
  If you run the code, you will see that both will return the same result. The first array contains the initial example, and the second contains the data changed to match the new big-endian order.
LinhNV says:

April 17, 2022 at 6:37 am
Thank you for your post!

I’m using stream operator to inverse bits of a signal. The result is correct but there are warnings when I do compile.
Do you know about the cause of the below warnings? I also tried adding “1” right before the operator but it has the same message.
```
assign ACT_DR_R[9:0] = {<<{FMT_LANE_E[6:1]}}, {<<{FMT_LANE_F[3:0]}} 

Warning-[TRFSO] Typecast required for streaming operator
"{ << 1{FMT_LANE_E[6:1]}}"
  Stream operands require explicit typecast to be used with other operators

Warning-[TRFSO] Typecast required for streaming operator
"{ << {FMT_LANE_F[3:0]}}"
  Stream operands require explicit typecast to be used with other operators
```
Reply
1. Aurelian Ionel Munteanu says:
  
  April 18, 2022 at 7:19 am
  Hello, LinhNV.
  
  First of all you did not mention the simulator you are using.
  I also suspect that the assign code is incomplete. You should also have a concatenation operator {,} after the equal sign of the assign.
  
  I think the error code refers to the two RHS streaming operators.
  They can’t be implicitly concatenated. You need to explicitly cast their result. Either use a cast operator, either use 2 other variables
  
  Option1:
```
module top;
  typedef logic[5:0] my_6_b_t;
  typedef logic[3:0] my_4_b_t;
  
  logic[9:0] c,a,b;

  assign c[9:0] = {my_6_b_t'({<<{a[6:1]}}), my_4_b_t'({<<{b[3:0]}})};
endmodule
```
  Option2
```
module top;
  typedef logic[5:0] my_6_b_t;
  typedef logic[3:0] my_4_b_t;
  
  logic[9:0] c,a,b;
  my_6_b_t a_6 = {<<{a[6:1]}};
  my_4_b_t b_4 = {<<{b[3:0]}};

  assign c[9:0] = {a_6, b_4};
endmodule
```
Jasson Flinn says:

April 19, 2024 at 9:31 pm

I generally use the bit slicing syntax to create a bus from an array of bytes from my C-DPI return value

bit[127:0] rx_det_out;
byte det_out[64];

for(int i=0; i<64; i++)
rx_det_out[((i*2)+1)-:2] =det_out[i];

Is it possible to use a streaming operator to do something equivalent? When I try I get LHS != RHS errors

rx_det_out = {<<2{{det_out}}};

Reply

Subscribe to our newsletter

Do you want to be up to date with our latest articles?

Cookie	Type	Duration	Description
	0
__cfruid	1
_fbp	0	3 months	This cookie is set by Facebook to deliver advertisement when they are on Facebook or a digital platform powered by Facebook advertising after visiting this website.
_ga	0	2 years	This cookie is installed by Google Analytics. The cookie is used to calculate visitor, session, camapign data and keep track of site usage for the site's analytics report. The cookies store information anonymously and assigns a randoly generated number to identify unique visitors.
_gat	0	1 minute	This cookies is installed by Google Universal Analytics to throttle the request rate to limit the colllection of data on high traffic sites.
_gid	0	1 day	This cookie is installed by Google Analytics. The cookie is used to store information of how visitors use a website and helps in creating an analytics report of how the wbsite is doing. The data collected including the number visitors, the source where they have come from, and the pages viisted in an anonymous form.
cookielawinfo-checkbox-advertisement	0	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given their consent to the usage of cookies under the category 'Advertisement'.
cookielawinfo-checkbox-analytics	0	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category 'Analytics'.
cookielawinfo-checkbox-necessary	0	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category 'Necessary'.
cookielawinfo-checkbox-performance	0	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category 'Performance'.
cookielawinfo-checkbox-uncategorized	0	1 year
crumb	0
fr	1	3 months	The cookie is set by Facebook to show relevant advertisments to the users and measure and improve the advertisements. The cookie also tracks the behavior of the user across the web on sites that have Facebook pixel or Facebook social plugin.
GPS	0	30 minutes	This cookie is set by Youtube and registers a unique ID for tracking users based on their geographical location
IDE	1	2 years	Used by Google DoubleClick and stores information about how the user uses the website and any other advertisement before visiting the website. This is used to present users with ads that are relevant to them according to the user profile.
NID	1	6 months	This cookie is used to a profile based on user's interest and display personalized ads to the users.
viewed_cookie_policy	0	1 hour	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.
VISITOR_INFO1_LIVE	1	5 months	This cookie is set by Youtube. Used to track the information of the embedded YouTube videos on a website.
YSC	1		This cookies is set by Youtube and is used to track the views of embedded videos.

Cookie	Duration	Description
cookielawinfo-checkbox-advertisement	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given their consent to the usage of cookies under the category 'Advertisement'.
cookielawinfo-checkbox-analytics	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category 'Analytics'.
cookielawinfo-checkbox-necessary	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category 'Necessary'.
cookielawinfo-checkbox-performance	1 year	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category 'Performance'.
viewed_cookie_policy	1 hour	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.

Cookie	Type	Duration	Description
_fbp	0	3 months	This cookie is set by Facebook to deliver advertisement when they are on Facebook or a digital platform powered by Facebook advertising after visiting this website.
fr	1	3 months	The cookie is set by Facebook to show relevant advertisments to the users and measure and improve the advertisements. The cookie also tracks the behavior of the user across the web on sites that have Facebook pixel or Facebook social plugin.
IDE	1	2 years	Used by Google DoubleClick and stores information about how the user uses the website and any other advertisement before visiting the website. This is used to present users with ads that are relevant to them according to the user profile.
NID	1	6 months	This cookie is used to a profile based on user's interest and display personalized ads to the users.
VISITOR_INFO1_LIVE	1	5 months	This cookie is set by Youtube. Used to track the information of the embedded YouTube videos on a website.

Cookie	Duration	Description
_ga	2 years	This cookie is installed by Google Analytics. The cookie is used to calculate visitor, session, camapign data and keep track of site usage for the site's analytics report. The cookies store information anonymously and assigns a randoly generated number to identify unique visitors.
_gid	1 day	This cookie is installed by Google Analytics. The cookie is used to store information of how visitors use a website and helps in creating an analytics report of how the wbsite is doing. The data collected including the number visitors, the source where they have come from, and the pages viisted in an anonymous form.
GPS	30 minutes	This cookie is set by Youtube and registers a unique ID for tracking users based on their geographical location

Cookie	Type	Duration	Description
_gat	0	1 minute	This cookies is installed by Google Universal Analytics to throttle the request rate to limit the colllection of data on high traffic sites.
YSC	1		This cookies is set by Youtube and is used to track the views of embedded videos.