Raw API - 2021.1 English

Xilinx Standalone Library Documentation OS and Libraries Document Collection (UG643)

Document ID
UG643
Release Date
2021-06-16
Version
2021.1 English

The Raw API is callback based. Applications obtain access directly into the TCP stack and vice-versa. As a result, there is no extra socket layer, and using the Raw API provides excellent performance at the price of compatibility with other TCP stacks.

Xilinx Adapter Requirements when using the RAW API

In addition to the lwIP RAW API, the Xilinx adapters provide the xemacif_input utility function for receiving packets. This function must be called at frequent intervals to move the received packets from the interrupt handlers to the lwIP stack. Depending on the type of packet received, lwIP then calls registered application callbacks. The <Vitis_install_path>/sw/ThirdParty/sw_services/lwip211/src/lwip-2.1.1/doc/rawapi.txt file describes the lwIP Raw API.

LwIP Performance

The following table provides the maximum TCP throughput achievable by FPGA, CPU, EMAC, and system frequency in RAW modes. Applications requiring high performance should use the RAW API.
FPGA CPU EMAC System Frequency Max TCP Throughput in RAW Mode (Mbps)
Virtex MicroBlaze axi-ethernet 100 MHz RX Side: 182 TX Side: 100
Virtex MicroBlaze xps-ll-temac 100 MHz RX Side: 178 TX Side: 100
Virtex MicroBlaze xps-ethernetlite 100 MHz RX Side: 50 TX Side: 38

RAW API Example

Applications using the RAW API are single threaded. The following pseudo-code illustrates a typical RAW mode program structure.
int main()
{
        struct netif *netif, server_netif;
        ip_addr_t ipaddr, netmask, gw;

        
        unsigned char mac_ethernet_address[] = 
                {0x00, 0x0a, 0x35, 0x00, 0x01, 0x02};

        lwip_init();

        
        if (!xemac_add(netif, &ipaddr, &netmask, 
                &gw, mac_ethernet_address, 
                EMAC_BASEADDR)) {
                printf(“Error adding N/W interface\n\r”);
                return -1;
        }
        netif_set_default(netif);

        
        platform_enable_interrupts();

        
        netif_set_up(netif);

        
        start_application();

        
        while (1) {
                xemacif_input(netif);
                
                transfer_data();
        }
}