Message-ID: <39535DA8.A5D014D4@uow.edu.au>
Date:   Fri, 23 Jun 2000 22:52:56 +1000
From:   Andrew Morton <andrewm@uow.edu.au>
MIME-Version: 1.0
To:     "netdev@oss.sgi.com" <netdev@oss.sgi.com>
Subject: Driver bug reporting
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Sender: owner-netdev@oss.sgi.com
Precedence: bulk

Andrey and I have been bemoaning the quality of the netdriver bug
reports, and the number of emails which go back and forth before
an adequate amount of info is gathered.

So we're putting together a 'reporting net driver problems' doc.
The idea is that each driver will say

	"See Documentation/networking/reporting-driver-problems.txt"

in its signon message.

This is what we have so far.   Go for it.


    Network driver problem HOWTO
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

    If you have a problem which you believe may be attributed to a
network driver, please report it to driver's maintainer.  The
development of high-quality driver software is impossible without user
feedback.  In many cases the authors are not even able to test all code
paths on their own hardware, and they certainly can't test their driver
against all third party switches and hubs.  So, your report is really
WELCOME!

    To be useful, the report should contain:

 1) Kernel version.

 2) An exact copy of the banner message which the driver generates
    on initialization.  All information in the banner is necessary for
    developers, otherwise it wouldn't be printed.

 3) Description of your problem.

    Explain what has happened, what didn't work as you expected,
    how and with which tools you checked it.  Did a previous version of
    the kernel or driver work correctly?

    Describe the circumstances under which the problem occurs. 
    Check your logs and include in the report any driver messages.

    An example of a good description of a problem is "All network
    communication seems to stop when I set full-duplex mode on the
    switch.  A ping from the computer to any other address shows 100%
    packet loss and produces ``Destination Host Unreachable'' messages.
    There are no kernel logs for the time of the experiment."

    An example of a bad description is "Help me! It hangs!".

    The email address of the driver maintainer is usually present in
comments
inside the driver source and in the MAINTAINERS file in the top level
kernel
source directory.


    If you are prepared to investigate the problem further you may also
refer to the next section of this document for more hints on how to do
this and how to collect more information about your hardware/system
configuration to describe better your problem.


    Reporting and diagnosing problems
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   Maintainers find that accurate and complete problem reports are
invaluable in resolving driver problems.  We are frequently not able to
reproduce problems and must rely on your patience and efforts to get to
the bottom of the problem.

   If you believe you have a driver problem here are some of the steps
you should take:

- Is it really a driver problem?

   Eliminate some variables: try different cards, different
   computers, different cables, different ports on the switch/hub,
   different versions of the kernel or of the driver, etc.

- OK, it's a driver problem.

   You need to generate a report.  Typically this is an email to the
   maintainer and/or linux-net@vger.rutgers.edu.  The maintainer's
   email address will be in the driver source or in the MAINTAINERS
file.

- The contents of your report will vary a lot depending upon the
  problem.  If it's a kernel crash then you should refer to the
  REPORTING-BUGS file.

  But for most problems it is useful to provide the following:

   o Kernel version, driver version

   o A copy of the banner message which the driver generates when
     it is initialised.  For example:

     eth0: 3Com PCI 3c905C Tornado at 0xa400,  00:50:da:6a:88:f0, IRQ 19
     8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate
interface.
     MII transceiver found at address 24, status 782d.
     Enabling bus-master transmits and whole-frame receives.

   o If it is a PCI device, the relevant output from 'lspci -vx', eg:

     00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast
Etherlink] (rev 74)
             Subsystem: 3Com Corporation: Unknown device 9200
             Flags: bus master, medium devsel, latency 32, IRQ 19
             I/O ports at a400 [size=128]
             Memory at db000000 (32-bit, non-prefetchable) [size=128]
             Expansion ROM at <unassigned> [disabled] [size=128K]
             Capabilities: [dc] Power Management version 2
     00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
     10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
     20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
     30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a

   o A description of the environment: 10baseT? 100baseT?
     full/half duplex? switched or hubbed?

   o Any additional module parameters which you may be providing to the
driver.

   o Any kernel logs which are produced.  The more the merrier. 
     If this is a large file and you are sending your report to a
     mailing list, mention that you have the logfile, but don't send
     it.  If you're reporting direct to the maintainer then just send
     it.

     To ensure that all kernel logs are available, add the
     following line to /etc/syslog.conf:

         kern.* /var/log/messages

     Then restart syslogd with:

         /etc/rc.d/init.d/syslog restart

     (The above may vary, depending upon which Linux distribution you
use).

    o If your problem is reproducible then that's great.  Try the
      following:

      1) Increase the debug level.  Usually this is done via:

         a) modprobe driver.o debug=7
         b) In /etc/conf.modules (or modules.conf):
            options driver_name debug=7

      2) Recreate the problem with the higher debug level,
         send all logs to the maintainer.

      3) Download you card's diagnostic tool from Donald
         Backer's website http://www.scyld.com/diag.  Download
         mii-diag.c as well.  Build these.

         a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
            working correctly.  Save the output.

         b) Run the above commands when the card is malfunctioning. 
Send
            both sets of output.

    Finally, please be patient and be prepared to do some work.  You
may end up working on this problem for a week or more as the maintainer
asks more questions, asks for more tests, asks for patches to be
applied, etc.  At the end of it all, the problem may even remain
unresolved.