====== Driver test: link detection ======

===== Rationale =====

Users expect link state errors to be reported as such, rather than having to be inferred from DHCP timeouts etc.  Drivers should therefore update the link state in response to external link up and link down events (e.g. disconnecting or reconnecting a network cable).

===== Background =====

The driver should update the link state using ''netdev_link_up()'', ''netdev_link_down()'' and/or ''netdev_link_err()''.  The user can observe the link state from the command line using ''[[:cmd:ifstat]]''.

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

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

  - Before starting, ensure that system power is off and the network cable is connected.
  - Power on and boot to the iPXE command line.
  - Use ifstat to identify the name of your network interface (hereafter assumed to be ''net0'').
  - Open the interface using ''[[:cmd:ifopen]] net0''.
  - Use ''[[:cmd:ifstat]]'' to verify that the link state is reported as ''Up''.  Some networks (e.g. Infiniband) take a long time to reach link-up; you may have to wait several seconds.
  - Disconnect the network cable.
  - Use ''[[:cmd:ifstat]]'' to verify that the link state is reported as ''Down'' (or some more specific link error, if the driver uses ''netdev_link_err()'')
  - Reconnect the network cable.
  - Use ''[[:cmd:ifstat]]'' to verify that the link state is again reported as ''Up''.

===== Troubleshooting =====

=== Link state valid only immediately after opening ===

You may find that your driver is capable of detecting the link state at the time that the interface is opened (using ''[[:cmd:ifopen]]''), but does not respond to subsequent link state changes such as a cable being disconnected.

Most NICs support a link state change interrupt, which is typically reported via the same mechanism used to report TX and RX completions.  Your ''poll()'' routine should check for a reported link state change and react appropriately.