How to Inspect Ethernet Packet Streams with Wireshark

Many protocol stacks in SoCs are based on the IEEE 802.3 Ethernet protocol as the data link layer, while the upper layers can be standard or application specific. Therefore, verification engineers have to inspect and debug Ethernet packet streams generated or monitored by the verification environment.

This article shows how to connect the Wireshark network protocol analyzer with a SystemVerilog verification environment in order to visualize Ethernet packet streams, either offline from a HEX dump file or dynamically using live packet capture.

Wireshark is an open source network protocol analyzer supported by a highly committed community that provides tons of tutorials and documentation. It helps you visualise and analyze hundreds of protocols and you can easily add support for a custom protocol using a dissector.

Install Wireshark and amiq_eth

System administrator access rights are required to install Wireshark. Installation instructions can be found in the Build and Install chapter.

To generate packets I use the amiq_eth library, a SystemVerilog/SystemC implementation of the IEEE 802.3 Ethernet framing protocol available on AMIQ’s GitHub repository.

Offline Analysis of Ethernet Packet Streams using a HEX Dump File

Wireshark can read HEX-dumps which are thoroughly described in the Import hex dump chapter. A HEX dump file contains the list of bytes of each Ethernet frame and can be created in SystemVerilog like this:

// open the HEX dump file
integer file_txt = $fopen("wireshark_file.txt"); 

for(int i = 0; i < number_of_packets; i++) begin
    amiq_eth_packet packet = generate_random_packet();

    // write the list of bytes into the file
    $fdisplay(file_txt, {packet.to_wireshark_string(),"\n"});
end

// close the HEX dump file
$fclose(file_txt);

where a packet class provides some utility functions like:

virtual class amiq_eth_packet extends uvm_object;
    //pack the Ethernet packet to a list of bytes in the format required by Wireshark software
    //@param byte_data - array in which to put the packed information
    virtual function void to_wireshark_array(ref byte unsigned byte_data[$]);
       bit bitstream[];
       bit current_pack_preamble = pack_preamble;
       bit current_pack_sfd = pack_sfd;
       pack_preamble = 0;
       pack_sfd = 0;
       void'(pack(bitstream));
       pack_preamble = current_pack_preamble;
       pack_sfd = current_pack_sfd;
       byte_data = {>> {bitstream}};
   endfunction

   //returns a string containing the bytes of the packet as required for Wireshark software
   //@return printable bytes of the packet
   virtual function string to_wireshark_string();
      string result = "";
      byte unsigned byte_data[$];
      to_wireshark_array(byte_data);

      for(int i = 0; i < byte_data.size(); i++) begin
         result = $sformatf("%s%06X %02X \n", result, i, byte_data[i]);
      end

      return result;
   endfunction
endclass

Start Wireshark, load the HEX dump file, and…yes, it’s as simple as that!

Visualize Ethernet Packet Streams using Live Packet Capture

This method allows you to inspect Ethernet packets in real-time, as they are generated or monitored in your SystemVerilog simulation.

First you have to save Ethernet packets in a libpcap formatted file. This format requires a binary file with a Global Header followed by an indefinite number of Packet Header – Packet Data pairs, as it is shown in the image bellow:

The amiq_eth library contains implementations of the Global Header, Packet Header and Packet Data, as well as a utility class to broadcast a stream of packets in amiq_eth_pcap_util.sv.

//class for streamming information into a PCAP file.
class amiq_eth_pcap_livestream;
   //file handler
   local integer file_pcap;
   //constructor
   //@param file_name - the name of the PCAP file - .pcap extention will be automatically appended
   function new(string file_name);
      file_pcap = amiq_eth_pcap_util::init_pcap_file($sformatf("%s.pcap", file_name));
   endfunction

   //write to PCAP file the ethernet packet
   //@param packet - the ethernet packet to write to pcap file
   function void broadcast(amiq_eth_packet packet);
      byte unsigned info[$];
      packet.to_wireshark_array(info);
      amiq_eth_pcap_util::write_to_pcap(file_pcap, info);
   endfunction

   //stop the streaming
   function void stop();
      $fclose(file_pcap);
   endfunction
endclass

Wireshark is able to connect to a system pipe and interpret the real-time PCAP information flowing through (see Pipes). You can create a system pipe and connect Wireshark to it this way:

mkfifo wireshark.fifo;
touch wireshark.pcap; 
tail -f wireshark.pcap >> wireshark.fifo &
wireshark -k -i wireshark.fifo &

Now you can start the simulation and enjoy the live packet stream:

amiq_eth/scripts/run.sh -livestream