SocLib Components General Index


1) Functional Description

The VciMasterNic component, is a GMII compliant, network controller for Gigabit Ethernet network, with a built-in DMA capability.

It can support a throughput of 1 Gigabit/s, as long as the system clock frequency is larger or equal to the GMII clock frequency (ie 125 MHz).

To improve the throughput, this component supports up to 8 channels. These channels are indexed by a key derived from the (source) remote IP address and port for the received (RX) packets, and from the (destination) remote IP address and port for the sent (TX) packets:

            uint32_t key = ( ((addr     ) & 0xFF) +
                             ((addr > 8 ) & 0xFF) +
                             ((addr > 16) & 0xFF) +
                             ((addr > 24) & 0xFF) +
                             ((port     ) & 0xFF) +
                             ((port > 8 ) & 0xFF) ) % nb_channels; 

The actual number of channels is an hardware parameter. The Ethernet packet length can have any value, in the range [42 to 2040] bytes.

The data transfer unit between software and the NIC is a 2K bytes container, containing one single Ethernet packet.

1.1 Software queues

The received packets (RX) and the sent packets (TX) are stored in two memory mapped queues, handled as software FIFOs. They are and called chained buffer, and defined by the nic_chbuf_s C structure. Each slot in the queue is a container. Each container can contain one single UDP packet or TCP segment. The number of containers, defining the FIFO depth, is a software defined parameter.

struct nic_chbuf_s
    uint32_t   wid;                              /*! current container write index         */
    uint32_t   rid;                              /*! current container read index          */
    uint64_t   cont_pad[SOCLIB_NIC_CHBUF_DEPTH]; /*! containers physical base addresses    */
    uint32_t * cont_ptr[SOCLIB_NIC_CHBUF_DEPTH]; /*! containers virtual base addresses     */

The physical addresses are used by the hardware NIC DMA engines. The virtual addresses are used by the software NIC drivers.

1.2 Container format

The nic_cont_s C structure contains a 2040 bytes data buffer, the actual ethernet packet length (in bytes), and the container state : full (owned by the reader) / empty (owned by the writer). Thist state variable is used as a SET/RESET flip-flop, by the software server thread, and the hardware NIC DMA engine.

struct nic_cont_s
    uint8_t    buf[2040];                        /*! Ethernet packet (42 to 2040 bytes     */
    uint32_t   length;                           /*! actual packet length in bytes         */
    uint32_t   state;                            /*! zero == empty / non zero == full      */

Inside the NIC controller, each channel implements a 2 slots chained buffer (two containers) for RX, and another 2 slots chained buffer( two containers) for TX. For each channel, the build-in RX_DMA engine moves the RX containers from the internal 2 slots chained buffer to the external chained buffer implementing the RX queue in memory. Another build-in TX-DMA engine moves the TX containers from the external chained buffer implementing the TX queue in memory, to the internal TX 2 slots chained buffer.

1.3 pipe-lined transfers

To improve the throughput for one specific channel, the DMA engines use pipelined bursts: The burst length cannot be larger than 64 bytes, but each channel send 4 pipelined VCI transactions to mask the round-trip latency. Therefore, this NIC controller can control up to 64 parallel VCI transactions (8 channels * 4 bursts * 2 directions). The CMD/RSP matching uses both the VCI TRDID and PKTID fields:

  • the channel index is sent in SRCID
  • the burst index is sent in TRDID[1:0]
  • the is_rx bit is sent in TRDID[2]

1.4 hard/soft synchronisation

Regarding the TX paquets, the TX_DMA[k] engines (one TX DMA per channel) implement a polling policy on the TX queue, with a delay (defined by the TX_DMA_PERIOD hardware parameter) between retry if the TX queue is empty. It signals the TX server thread with an IRQ when the TX queue changes from the full state, to non-full.

Regarding the RX paquets, the RX_DMA[k] engines (one RX DMA per channel) implement a polling policy on the RX queue, with a delay (defined by the RX_DMA_PERIOD hardware parameter) between retry if the RX queue is full. It signals the RX server thread with an IRQ when the TR queue changes from the empty state, to non-empty.

1.5 GMII physical interface modeling

The SystemC simulation model supports three modes of operation, defined by a constructor parameter:

  • NIC_MODE_FILE: Both the RX packets stream an the TX packets stream are read/written from/to dedicated files "nic_rx_file.txt" and "nic_tx_file.txt", stored in the same directory as the top.cpp file.
  • NIC_MODE_SYNTHESIS: The TX packet stream is still written to the "nic_tx_file.txt" file, but the RX packet stream is synthesised. The packet length (between 42 and 1538 bytes) and the source MAC address (8 possible values) are pseudo-random numbers.
  • NIC_MODE_TAP: The TX and RX packet streams are send and received to and from the physical network controller of the workstation running the simulation.

2) Addressable registers

The addressable registers can be split in two classes: global registers, and channel registers.

2.1) global registers

These registers are used for global NIC configuration or status, and are not linked to a specific channel.

NIC_G_CHANNELS Read Only returns actual number of channels
NIC_G_NPKT_RESET Write Only reset all packets counters
NIC_G_NPKT_RX_G2S_RECEIVED Read_Only packets received on GMII RX port
NIC_G_NPKT_RX_G2S_DISCARDED Read Only RX packets discarded by RX_G2S FSM
NIC_G_NPKT_RX_DES_SUCCESS Read Only RX packets transmited by RX_DES FSM
NIC_G_NPKT_RX_DES_TOO_SMALL Read Only discarded too small RX packets (<60B)
NIC_G_NPKT_RX_DES_TOO_BIG Read Only discarded too big RX packets (>1514B)
NIC_G_NPKT_RX_DES_MFIFO_FULL Read Only discarded RX packets if fifo full
NIC_G_NPKT_RX_DES_CRC_FAIL Read Only discarded RX packets if CRC32 failure
NIC_G_NPKT_RX_DISP_BROADCAST Read Only broadcast RX packets received
NIC_G_NPKT_RX_DISP_CH_FULL Read Only discarded RX packets if channel full
NIC_G_NPKT_TX_DISP_TOO_SMALL Read Only discarded too small TX packets (<60B)
NIC_G_NPKT_TX_DISP_TOO_BIG Read Only discarded too big TX packets (>1514B)
NIC_G_NPKT_TX_DISP_TRANSMIT Read Only transmited TX packets

2.2) Channel registers

These registers are replicated for each channel.

NIC_RX_CHANNEL_RUN Write Only channel activation
NIC_RX_CHBUF_DESC_LO Read/Write RX chbuf descriptor low word
NIC_RX_CHBUF_DESC_HI Read/Write RX chbuf descriptor high word
NIC_RX_CHBUF_NBUFS Read/WRITE RX chbuf depth (buffers)
NIC_RX_CHANNEL_STATE Read Only RX channel status
NIC_TX_CHANNEL_RUN Write Only TX channel activation
NIC_TX_CHBUF_DESC_LO Read/Write TX chbuf descriptor low word
NIC_TX_CHBUF_DESC_HI Read/Write TX chbuf descriptor high word
NIC_TX_CHBUF_NBUFS Read/Write TX chbuf depth (buffers)
NIC_TX_CHANNEL_STATE Read Only TX channel status

For extensibility issues, you should access all these registers using the globally-defined offsets in file


This hardware component checks for segmentation violation, and can be used as a default target.

3) Component definition & usage


Uses( 'vci_master_nic' )

4) CABA Implementation

CABA sources

CABA Constructor parameters

     sc_core::sc_module_name name,   //  Component Name
     const soclib::common::MappingTable &mt,   // MappingTable
     const soclib::common::IntTab &rx_srcid,  // RX DMA initiator index
     const soclib::common::IntTab &tx_srcid,  // TX DMA initiator index
     const soclib::common::IntTab &tgtid,  // target index
     const size_t channels,   // Number of channels
     const uint32_t burst_order,   // ln2( dma_burst_size ) 
     const int mode,   // GMII physical interface modeling
     const uint32_t inter_frame_gap);   // delay between two packets

CABA Ports

  • p_resetn : Global system reset
  • p_clk : Global system clock
  • p_vci : The VCI target port
  • p_rx_irq[k] : As many RX IRQ ports as the number of channels
  • p_tx_irq[k] : As many TX IRQ ports as the number of channels
Last modified 3 years ago Last modified on Jul 30, 2020, 3:26:56 PM