Handling hardware errors

See ``Error handling'' for general information about handling error conditions in device drivers. The following guidelines pertain to specific hardware failures that occur in the network adapters supported by MDI drivers.

Fatal errors

An MDI driver should never panic the system by calling cmn_err(D3) with CE_PANIC as the first argument. If the hardware has failed, the driver should:

• issue a message on the console with cmn_err(CE_WARN,...).

• send a MAC_HWFAIL_IND(D7mdi) message upstream or reinitialize the adapter. Do not do both.

• If reinitialization fails, the driver should send a MAC_HWFAIL_IND(D7mdi) message upstream and be marked as down until it is successfully reinitialized by the driver's close(D2mdi) and open(D2mdi) routines. Note that interrupts will not be processed and transmit frames will be dropped in this case.

Handling a loose cable

All MDI drivers should be coded to detect a link loss (in other words, the cable has been removed, loosened, or damaged) and to react appropriately. The following steps are recommended:

• Issue one notice per link loss using the cmn_err(D3) or cmn_err(D3oddi) function, such as:

     cmn_err(CE_NOTE, "<driver>: link loss, check network connection");
  

  Only one such message should be issued per link loss event.

• The driver's uwput(D2mdi) entry point routine should silently drop all new M_DATA(D7str) messages that indicate data to be transmitted. Other messages such as M_IOCTL(D7str) and M_FLUSH(D7str) should still be processed, even if the link is not available.

• Flush the transmit queue.

• Disable the transmitter.

• Do not disable the queue to prevent the STREAMS scheduler from running the driver's wsrv( ) code, if any.

• Do not attempt to send frames that are already queued by the hardware.

• While the link is not present, the driver must react appropriately to interrupts that occur:

  
  DDI 7 drivers

  device interrupts that occur should cause the driver to scan through its table because other hardware (including another network card that is controlled by the same driver) could be sharing the same IRQ.

  
  DDI 8 drivers

  the driver's interrupt routine should determine whether the interrupt belongs to it or not.

  
  ODDI drivers (SCO OpenServer 5)

• When link integrity is reestablished, restart the transmitter and start sending frames again. The driver should issue a notice such as the following:

     cmn_err(CE_NOTE, "<driver>: link resumed")
  

• If the hardware does not generate interrupts, the driver should establish a repeating itimeout(D3) or timeout(D3oddi) call with the TO_PERIODIC flag to query link status at periodic intervals; once per second is usually adequate.

• Send a MAC_HWFAIL_IND(D7mdi) message upstream to initiate a failover event if a backup adapter has been configured. Note that this may cause your driver to get closed and re-opened when no backup adapter is configured.