MOSCHIP MCS7830 USB2.0 TO ETHERNET DRIVER README

Version 1.3
31.03.2011


1. GENERAL

Please note, that I am not a professional programmer. Also, I am an absolute beginner in network technology. I am only a person interested in OS/2. This driver is my first attempt to write an OS/2 device driver. Cause I don't speak C programming language, this driver is written with Virtual Pascal and an assembler stub for linking the 32-bit code to the kernel. This work is done at my spare time and given to public for free. Please note that I will not support this driver and there's no guarantee that there will be a further version. It is not a project to the public but a result of my needs and my curiosity.

This driver would not exist without the help of many code snippets and free available information from many other people doing OS/2 development. Maybe my code will be helpful for someone else, so I have included full source code into source.zip. If you want to make things better you are invited to do so.

Please feel free to use the driver and the source but note, that some of the string-functions are taken from the Virtual Pascal sources.
And, of course, I am not responsible to any damage using this driver at your system! I have been testing this driver carefully but I am shure, there may be bugs left. As always, a bug in a device driver may crash the whole system. So please, be careful when testing this driver.


2. SUPPORTED DEVICES

This driver supports USB2.0 to Ethernet Adapters using MOSCHIP MCS7830 chip. The device identifies as Vendor 0x9710 and Product 0x7830 in the device descriptor. The driver accepts all devices with that combination of Vendor and Product ID. Mine was sold by Conrad at December 2007, Order Number 973119 for about 25 EURO.


3. PREREQUISITES

This driver should run on every Version of OS/2 Warp4 with recent Kernel and up.
You NEED an USB 2.0 Hub for doing something useful with it.
You NEED at least a 486 CPU (but this should not be a problem).
SMP is not tested due the lack of appropriate hardware and software.

My configuration:
AMD Athlon 630 MHz with Warp 4 FP15 and NEC-based USB2.0 Hub.


4. SPEED

Unfortunately, the OS/2 USB-Stack is not well documented. I had to accept, that the Ethernet-Adapter on a USB 1.1 Hub is far too slow to work with it (about 10 kbps or 1 kbyte per second - slower than a modem connection). I have been investigating the problem, but I am not capable to read the IBM C-Sources good enaugh to see, what the cause could be. The MOSCHIP tells USB-Stack three descriptors, one of them is an interrupt-descriptor with an interval of one. USB-Specification tells that for interrupt transfers bandwith has to be reserved by the host software (even if the endpoint is never used). 

Maybe IBM has implemented this feature properly and that causes the remaining bandwith for transfering the Ethernet data being so small, causing slow transfers. On USB 2.0 the overall bandwith is much greater, but on my tests even on USB 2.0 the transfer speed of Ethernet data is not as fast as I expected (about 50 Mbps). With other words, you will not be able to archive the full Ethernet speed, except with another USB-Stack or faster hardware.

I have been trying to overcome the limitations by manipulating the endpoint-descriptor to USBD.SYS, just before setting the device to work. But this did not change the situation. It seems that USBD does the reservation of bandwith just after the device being attached and before my driver is involved. That means, I cannot fix this.


5. INSTALLATION

The driver consists of two files: mcs7830.os2 (the driver) and mcs7830.nif (information file for MPTS).
You may install via MPTS-Configuration. Use the "others" button to copy the files to MPTS or copy the files manually to the X:\IBMCOM\MACS directory (where X is to be replaced with the name of the drive where MPTS is installed). After that, you should find the entry "Moschip USB 2.0 to Ethernet Adapter" in the list of available network cards. Follow the instructions of your MPTS installation to complete the installation.

You can configure the following elements:

Set Ethernet Speed an Duplex Mode [ETHERMODE]:
Number 0-4 with
	0 = Autodetect
	1 = 10 Mbps, Half Duplex
	2 = 10 Mbps, Full Duplex
	3 = 100 Mbps, Half Duplex
	4 = 100 Mbps, Full Duplex
Please note, Automatic detection of Full Duplex REQUIRES a hub with ports which are capable of performing N-Way auto-negotiation, so forcing the duplex mode to Full is recommended for most users connecting to a Full Duplex hub.

Locally Administered Address [NODE]:
Hex-String 12 characters
This is to be used by a network administrator - do not use it if you don't know what you do.

Serial Number Identifier [SERIALNR]:
Hex-String
This can be used if you have more than one adapter to link a specific adapter to a specific configuration. You can find the Serial Number (if the adapter has an EPROM) by investigating the Hardware Manager after plugging the adapter. You should find a line like "USB-MAC Controller SN:YYYYYYY" where YYYYY is the serial number provided by the adapter. This entry is case-sensitive, write exactly as shown!


6. MORE FEATURES

PROTOCOL.INI
The driver can hold up to three configurations and may be able to run three adapters at the same time (not tested). Simply double the entries for [MCS7830_nif] to [MCS7830_2_nif] or somewhat else and bind the neccessary protocols to it. Use the Serial Number Identifier (e.g. SERIALNR = "3b000405C") to define which adapter has to use which configuration. Please note that the driver assigns every adapter to the first configuration that is idle and either missing a SERIALNR-entry or that matches the number programmed to the adapter. You must not load the driver twice at config.sys!

CONFIG.SYS
You may add the following parameters after the DEVICE:= ... MCS7830.OS2 statement:
/V means "show up a loading message"
/W includes /V but shows more information. Also this causes the driver to write some debug messages to internal buffer, e.g. reciving a "plugged" message from USBD and others. This can be useful when investigating problems. The buffer can be read by typing the following in an OS/2 command window:
copy mcs7830$ con:

Please note, /W causes a speed panalty to your system an should only be used if you are investigating problems.


7. CHANGES FROM V1.0

Ressource Manager has been telling the wrong device type - fixed.

Performance improvements by using TKSSBase kernel variable and +Sfs option on alp processing.
Using TKSSBase (see 32DRV170.ZIP for a description by Matthieu WILLM) is much better then reading SS-Descriptor on every call to the driver as i did at the first version. I'ts a pitty that OS/2 kernel internals are so poorly documented when working with 32 bit device driver development.

The more important thing is a complete rework of the command queue internal workings. 
THIS MAY BREAK COMPATIBILITY WITH OLDER KERNELS! 

Background:
NDIS-Specification was made with Network-Adapters in mind, which have fully accessable memory buffers onboard. An USB-Adapter has such Memory, but not fully accessable. Instead, this buffers are accessable via the endpoints of the device in a serial manner. When the driver wants to send data, it has to move this data to a buffer in main memory. Second, USBD has to be called to move the data over USB. After that, the protocol stack should be informed that the data was processed. The same work has to be done when data was recived from ethernet. The protocol can tell the driver if it is busy. The driver has to buffer all messages in this case.

NDIS-Specification also tells that all calling from the protocol has to be accepted in either task or interrupt mode of the kernel. But as far as i know, USBD does not like to be called in interrupt mode.

To make things working in a reliable way, all work is done in a serial way. All data transfers are bufferd in main memory. When a complete frame is ready, a task time thread does the neccessary calls to either USBD or the protocol. My first attempt to this was using context hooks from the kernel. One hook was intended to handle data transportation, a second was bound to handle the connection and disconnection of the device. This seems to work, as long as there are no delays in the work to be done. But if there's somthing that needs a delay (waiting on a semaphore) the whole system waits! There's no problem with blocking a contect hook on a semaphore, but the whole system is blocked in this case and no other thread gets cpu time as long as the hook is blocked.

This caused a delay on boot with plugged ethernet adapter if the network is not ready. As i like to use the base code of this driver for other tasks (where blocking the whole system is unacceptable) i tried to overcome this.

The easy way would be to start a process (an *.exe) later on boot, giving the neccessary regular threads to the driver to work with. But i didn't like that (needs seperate *.EXE, creates a seperate process which never runs in ring3). I tried to create the threads within the driver from 32 bit ring 0 code. And it works, at least at the newer kernel revisions. But it may not work on older kernels or new developed ones, cause IBM never intended the CreateThread API to be called from within a driver. On the other hand the kernel starts up some threads on boot itself, so there must be a way to do this. The new threads become parts of the SYSINIT process.


CHANGES FROM V1.1

MAC-Part of Driver is locked until USB-Init is complete.
MAC-Data is stored and processed after USB-Init (as long as the buffers are big enaugh).
This might fix the problems that have been told when using with SMP.
It is also helpful when plugging the adapter in the middle of boot processing.
I've had several hangs within WPS when doing so.


8. RESTRICTIONS

As mentioned above, speed is not as fast as expected. I don't know how to fix this.

My driver does make no use of APM. On my Notebook, the USB-Port is powered down when entering Suspend. Before, my driver is told that the adapter was disconnected. On APM resume, the USB comes back to power, USBD is telling my driver that a device has been attached. Power saving features of the chip itself are enabled. 

Multicast-Addresses are restricted to one per adapter. Cause USB may not be the preferred way to build up a network server I decided not to implement more than one multicast address. I simply don't know what to use them for.

Broadcast-Addresses and matching Unicast-Addresses are reflected by software, cause the adapter does not support this.
Promiscuous mode should work the same way, testing with SWITCH.OS2 seems to be ok.

When the link is lost (but the adapter ist still connected to USB), the driver tells transmit errors to the protocol trying to send. After link is back, it can take up to 10 Sec. till the driver has polled the adapter and transmission resumes.

When the adapter is disconnected from USB, an adapter-check condition is told to the protocol. This causes a non resumable condition to the protocol so the link has to be established by using IFCONFIG again.

There may be a crash when using SWITCH.OS2 in AFOS2.SYS with this driver when you have another network card driver as lan0 and USB card as lan1 or higher. I tried to fix this, but it's not the fault of my driver. The crash occures when the first packet was send and my driver tells the protocol about success in transmission via SWITCH.OS2. On return from the protocol there seems to be an uninitialized return pointer... .
To avoid this, you can make shure that your lan0 is configured BEFORE the first access to lan1 (eg. by ifconfig lan0 before ifconfig lan1). On my system this removed the problem entirely, although it is a workaround an not a perfect solution.


9. THANKS & CONTACT

Thanks to all people spending time and money to keep OS/2 alive!

If you like to contact me, you can use the following email:


>My full name without space or dot< @ t-online.de
But please note, that it can take a few weeks, till you get an answer and I can only react to german or english language.

Also, I am reading the german support pages on OS2.ORG regulary.



Holger Veith



PS: To build the driver, you need:

- Virtual Pascal Version 2.1 Build 279
- the OS2 Toolkit 4.5 (alp, os2386.lib and link386.exe)

Look at the make.cmd file included. After setting the paths, compiling and linking should work. The compiler options for Virtual Pascal are specified in the source file. If you specify vp.exe or vpm.exe prior to alp in the make.cmd, you can work with the VP IDE and issue a complete automatic rebuild when leaving the IDE. 