Bugs HowTo

How do I report bugs?

1. First, make sure you are running the latest version of ndiswrapper available at http://projects.sourceforge.net/ndiswrapper. Bug fixes appear in the latest released version.
2. Do NOT file bug report if something doesn’t work for you. Many of the bug reports are not really about bugs, but problems about not configuring ndiswrapper or not using ndiswrapper properly - read Installation, FAQ, Troubleshooting etc. before filing a bug report. Note that Bug reporting is not a way to seek help - it is just for informing about real bugs!
3. Make sure you are using one of the drivers in the wiki List, not from your card vendor or CD. Not all drivers for all cards are tested.
4. If you have to use a driver not in the wiki List because you are using a device that is not yet known to work, include web link from which this driver can be loaded.
5. If it is not a known problem, post details to either mailing list or forums. Follow the procedure below to collect useful information.
6. Give detailed information about what the problem is and how to reproduce it.
7. Run ‘ndiswrapper-buginfo’ script that is part of utils. Submit ‘/tmp/ndiswrapper-buginfo.gz’ file.
8. Starting with version 1.4-rc1, debug log can be controlled flexibly. First, compile ndiswrapper with:

cd ndiswrapper-version/driver
make clean
make DEBUG=6 IO_DEBUG=1 EVENT_DEBUG=1 USB_DEBUG=1
insmod ./ndiswrapper.ko debug=3

Note: Do NOT install driver with make install after compiling with debug flags

This enables debug log for IO layer (IO_DEBUG), events (EVENT_DEBUG), USB layer (USB_DEBUG) as well as level 6 (highest level as of now) for the rest. If for some reason you don’t want, say, USB layer messages, just don’t pass USB_DEBUG option to make. ‘debug=’ option sets initial value of debug flag. This can be used to enable/disable/set debug level; e.g., if the bug you are trying to locate is not during initialization but, say, when module is removed, debug log during initialization may not be useful, so load the module with ‘insmod ./driver/ndiswrapper.ko debug=0’. This will not print any debug log. Later, just before module is being removed, enable debug log by writing to procfs: ‘echo 6 > /proc/net/ndiswrapper/debug; rmmod ndiswrapper’ (you can specify any other level instead of 6, if you wish, but USB log, events log etc are printed at any level >= 1). If you want even finer control, e.g., if driver crashes when scanning, you can edit the source files to (temporarily) enable debug, so, for this case, edit iw_ndis.c, function iw_get_scan so it has

debug = 4;
...
debug = 0;

Somewhat similar effect can be achieved by writing to procfs instead of editing code:

echo 4 > /proc/net/ndiswrapper/debug
iwlist wlan0 scan
echo 0 > /proc/net/ndiswrapper/debug

1. Load the module from Console 1 not from X Window. Make sure that no kernel modules are loaded but the ones really needed for testing pcmcia, usbcore, netcarddriver for netconsole, etc.. Use lsmod/rmmod to unload kernel modules that are not needed i.e. soundcard, modem, acpi helper modules, etc.
   
   insmod ./ndiswrapper.ko
   
   
2. Now you will see debug information scrolling over your screen. If you don’t see messages on screen, first make sure printk is configured to print information on screen run echo 7 > /proc/sys/kernel/printk. If you are using metalog instead of syslog try adjusting the verbosity level and/or enable console logging. If it doesn’t crash, you can try to blindly issue commands like setting mode, wep key or essid that cause it to crash. This way, if kernel crashes, the information on the screen shows useful information exactly what caused crash. Write down the information on the screen values of registers is not useful, so don’t worry about those. The most relevant information is the function in which crash occurs and a few lines of debug trace information right before the oops is printed. If you use plain console 80×24 lines, then not much information can be seen. So, use a framebuffer e.g., vesa framebuffer with as high resolution as possible. If you don’t want to copy the screen contents by hand, or if syslog continues to print more messages such that real-crash-data scrolls off the screen, use netconsole see Documentation/networking/netconsole.txt under Linux kernel source directory which is explained further down. At any level higher than 2, the messages may be printed at such a rate that syslog may miss some of the messages. To prevent this loss, increase log buffer length with the boot parameter log_buf_len=4M, which sets the buffer to 4 Megabytes you can increase this further if necessary. Post the system messages (usually in /var/log/kern.log or /var/log/messages, but it depends on distribution). Submit as much debug trace as possible (from when module is loaded till at least when problem manifests). Without full debug trace showing what might be the problem, it is not possible for developers to understand and fix the bug.
3. If indeed it is a bug, developers will request you to file a bug report on the sourceforge bug tracker at http://sourceforge.net/tracker/?atid=604450&group_id=93482&func=browse.
4. If you file a bug without following these guidelines, don’t expect it to be resolved it may even simply be deleted.
5. More on netconsole:
   • You need a running host, say RECIPIENT, in the same lan that will listen for the udp packets issued by the crashing machine. Make sure that a firewall doesn’t block those packets you want to receive. For the listener you can use netcat:nc -u -l -p 6666 > crash.log
   • Issue the following commands to broadcast your log to the lan, before the kernel crashes. This will send out udp packets to <IP-OF-RECIPIENT> onto port 6666. On most configurations it should work without having to supply <MAC-OF-RECIPIENT>, it did not on mine however. /etc/init.d/sysklogd stop dmesg -n8 noMAC example: modprobe netconsole netconsole=@/,@192.168.2.23/ full example: modprobe netconsole netconsole=@/,@192.168.2.23/23:45:45:67:89:00
   • If the netconsole module refuses to load, it could be that the driver for your network card doesn’t feature netpoll. For sis900 cards see http://www.brownhat.org/sis900.html, which is necessary for the netconsole module to work.

How to locate a regression?

As more features are added, bugs are “fixed’, some drivers may break. As ndiswrapper supports many drivers and developers don’t have all the hardware that works with it, regressions (what worked with a version may break later) are unavoidable. If you find a regression, it is easy to locate what may have caused the regression by isolating a patch with the procedure below.

• First, locate a latest version that works fine. You can get various versions from http://sourceforge.net/project/showfiles.php?group_id=93482. Then find out the svn revision corresponding to that version from http://ndiswrapper.svn.sourceforge.net/viewvc/ndiswrapper/tags/ For example, version 1.44 of ndiswrapper is svn revision 2363 and version 1.45 is revision 2398. If the regression is between versions 1.44 and 1.45, we need to locate when this happened between revisions 2363 an 2398.
• Get svn trunk code: In a terminal, run

svn co https://ndiswrapper.svn.sourceforge.net/svnroot/ndiswrapper/trunk/ndiswrapper

This retrieves trunk (where the latest development code is taking place). Now, change to ndiswrapper directory with cd ndiswrapper and to update the code corresponding to the revision 2364, for example, run svn up -r 2364. Now, install ndiswrapper with make install and run it to check for regression with revision 2364. If that works fine, then find another revision, say, 2375, that may have regression with svn up -r 2375 in ndiswrapper directory and again install it and try. Repeat these steps (guessing a revision which is the first time the regression occurs, updating to that revision and trying it). Once you find the first revision that causes the regression, post detailed message (more details, the easier it is for the developers) to forums.