====== Driver test: loopback ======

===== Rationale =====

The ''[[:cmd:lotest]]'' command allows the correct operation of both the receive and transmit datapaths to be verified independently under high packet load and with no dependency on external servers or network components.  Additionally, it is one of the few tests capable of detecting whether or not the receive datapath is correctly stripping the CRC.

===== Background =====

''[[:cmd:lotest]]'' operates using two network interfaces on the same machine, both controlled by iPXE.  The two interfaces should be directly connected with a single cable, with no intervening switch.

Ideally, one of the network interfaces should belong to a known-good NIC that is not controlled by the driver you are currently developing, since this allows you to isolate problems to either the transmit or the receive datapath.  If you are testing a dual-port NIC, then you may use the two ports as the two interfaces, with the caveat that this will not allow you to easily distinguish between problems in the transmit and receive datapaths.

{{ :clipart:nic.jpeg?237x222|A network card}}

===== Test sequence =====

  - Before starting, ensure that your network interface is directly connected to a second network interface on the same machine.
  - Boot into a version of iPXE with [[:buildcfg:LOTEST_CMD]] enabled and with support for both network interfaces.
  - Use ''[[:cmd:ifstat]]'' to identify the name of your network interface (hereafter assumed to be ''net0'') and the name of the second network interface (hereafter assumed to be ''net1'').
  - Initiate testing of the transmit datapath using ''lotest net0 net1''.
  - Verify that the packet counter displayed by ''lotest'' increases steadily and rapidly.
  - Abort the test using ''Ctrl-C''.
  - Initiate testing of the receive datapath using ''lotest net1 net0''.
  - Verify that the packet counter displayed by ''lotest'' increases steadily and rapidly.
  - Abort the test using ''Ctrl-C''.

===== Troubleshooting ====

=== Length mismatch ===

When testing the receive datapath, you will observe a ''Length mismatch'' error if your driver is not correctly stripping the Ethernet CRC from the received packet.  You should ideally configure the NIC to strip the CRC in hardware.  If the NIC does not support this, then you may strip the CRC in software by subtracting 4 bytes from the length of the received packet before passing it to ''netdev_rx()'':

    iob_put ( iobuf, ( len - 4 /* strip CRC */ ) );
    netdev_rx ( netdev, iobuf );