[linux-2.6] / Documentation / networking / dl2k.txt


    D-Link DL2000-based Gigabit Ethernet Adapter Installation
    for Linux
    May 23, 2002

Contents
========
 - Compatibility List
 - Quick Install
 - Compiling the Driver
 - Installing the Driver
 - Option parameter
 - Configuration Script Sample
 - Troubleshooting


Compatibility List
=================
Adapter Support:

D-Link DGE-550T Gigabit Ethernet Adapter.
D-Link DGE-550SX Gigabit Ethernet Adapter.
D-Link DL2000-based Gigabit Ethernet Adapter.


The driver support Linux kernel 2.4.7 later. We had tested it
on the environments below.

 . Red Hat v6.2 (update kernel to 2.4.7)
 . Red Hat v7.0 (update kernel to 2.4.7)
 . Red Hat v7.1 (kernel 2.4.7)
 . Red Hat v7.2 (kernel 2.4.7-10)


Quick Install
=============
Install linux driver as following command:

1. make all
2. insmod dl2k.ko
3. ifconfig eth0 up 10.xxx.xxx.xxx netmask 255.0.0.0
		    ^^^^^^^^^^^^^^^\	    ^^^^^^^^\
				    IP		     NETMASK
Now eth0 should active, you can test it by "ping" or get more information by
"ifconfig". If tested ok, continue the next step.

4. cp dl2k.ko /lib/modules/`uname -r`/kernel/drivers/net
5. Add the following line to /etc/modprobe.conf:
	alias eth0 dl2k
6. Run "netconfig" or "netconf" to create configuration script ifcfg-eth0
   located at /etc/sysconfig/network-scripts or create it manually.
   [see - Configuration Script Sample]
7. Driver will automatically load and configure at next boot time.

Compiling the Driver
====================
  In Linux, NIC drivers are most commonly configured as loadable modules.
The approach of building a monolithic kernel has become obsolete. The driver
can be compiled as part of a monolithic kernel, but is strongly discouraged.
The remainder of this section assumes the driver is built as a loadable module.
In the Linux environment, it is a good idea to rebuild the driver from the
source instead of relying on a precompiled version. This approach provides
better reliability since a precompiled driver might depend on libraries or
kernel features that are not present in a given Linux installation.

The 3 files necessary to build Linux device driver are dl2k.c, dl2k.h and
Makefile. To compile, the Linux installation must include the gcc compiler,
the kernel source, and the kernel headers. The Linux driver supports Linux
Kernels 2.4.7. Copy the files to a directory and enter the following command
to compile and link the driver:

CD-ROM drive
------------

[root@XXX /] mkdir cdrom
[root@XXX /] mount -r -t iso9660 -o conv=auto /dev/cdrom /cdrom
[root@XXX /] cd root
[root@XXX /root] mkdir dl2k
[root@XXX /root] cd dl2k
[root@XXX dl2k] cp /cdrom/linux/dl2k.tgz /root/dl2k
[root@XXX dl2k] tar xfvz dl2k.tgz
[root@XXX dl2k] make all

Floppy disc drive
-----------------

[root@XXX /] cd root
[root@XXX /root] mkdir dl2k
[root@XXX /root] cd dl2k
[root@XXX dl2k] mcopy a:/linux/dl2k.tgz /root/dl2k
[root@XXX dl2k] tar xfvz dl2k.tgz
[root@XXX dl2k] make all

Installing the Driver
=====================

  Manual Installation
  -------------------
  Once the driver has been compiled, it must be loaded, enabled, and bound
  to a protocol stack in order to establish network connectivity. To load a
  module enter the command:

  insmod dl2k.o

  or

  insmod dl2k.o <optional parameter>	; add parameter

  ===============================================================
   example: insmod dl2k.o media=100mbps_hd
   or	    insmod dl2k.o media=3
   or	    insmod dl2k.o media=3,2	; for 2 cards
  ===============================================================

  Please reference the list of the command line parameters supported by
  the Linux device driver below.

  The insmod command only loads the driver and gives it a name of the form
  eth0, eth1, etc. To bring the NIC into an operational state,
  it is necessary to issue the following command:

  ifconfig eth0 up

  Finally, to bind the driver to the active protocol (e.g., TCP/IP with
  Linux), enter the following command:

  ifup eth0

  Note that this is meaningful only if the system can find a configuration
  script that contains the necessary network information. A sample will be
  given in the next paragraph.

  The commands to unload a driver are as follows:

  ifdown eth0
  ifconfig eth0 down
  rmmod dl2k.o

  The following are the commands to list the currently loaded modules and
  to see the current network configuration.

  lsmod
  ifconfig


  Automated Installation
  ----------------------
  This section describes how to install the driver such that it is
  automatically loaded and configured at boot time. The following description
  is based on a Red Hat 6.0/7.0 distribution, but it can easily be ported to
  other distributions as well.

  Red Hat v6.x/v7.x
  -----------------
  1. Copy dl2k.o to the network modules directory, typically
     /lib/modules/2.x.x-xx/net or /lib/modules/2.x.x/kernel/drivers/net.
  2. Locate the boot module configuration file, most commonly modprobe.conf
     or modules.conf (for 2.4) in the /etc directory. Add the following lines:

     alias ethx dl2k
     options dl2k <optional parameters>

     where ethx will be eth0 if the NIC is the only ethernet adapter, eth1 if
     one other ethernet adapter is installed, etc. Refer to the table in the
     previous section for the list of optional parameters.
  3. Locate the network configuration scripts, normally the
     /etc/sysconfig/network-scripts directory, and create a configuration
     script named ifcfg-ethx that contains network information.
  4. Note that for most Linux distributions, Red Hat included, a configuration
     utility with a graphical user interface is provided to perform steps 2
     and 3 above.


Parameter Description
=====================
You can install this driver without any addtional parameter. However, if you
are going to have extensive functions then it is necessary to set extra
parameter. Below is a list of the command line parameters supported by the
Linux device
driver.

mtu=packet_size			- Specifies the maximum packet size. default
				  is 1500.

media=media_type		- Specifies the media type the NIC operates at.
				  autosense	Autosensing active media.
				  10mbps_hd	10Mbps half duplex.
				  10mbps_fd	10Mbps full duplex.
				  100mbps_hd	100Mbps half duplex.
				  100mbps_fd	100Mbps full duplex.
				  1000mbps_fd	1000Mbps full duplex.
				  1000mbps_hd	1000Mbps half duplex.
				  0		Autosensing active media.
				  1		10Mbps half duplex.
				  2		10Mbps full duplex.
				  3		100Mbps half duplex.
				  4		100Mbps full duplex.
				  5          	1000Mbps half duplex.
				  6          	1000Mbps full duplex.

				  By default, the NIC operates at autosense.
				  1000mbps_fd and 1000mbps_hd types are only
				  available for fiber adapter.

vlan=n				- Specifies the VLAN ID. If vlan=0, the
				  Virtual Local Area Network (VLAN) function is
				  disable.

jumbo=[0|1]			- Specifies the jumbo frame support. If jumbo=1,
				  the NIC accept jumbo frames. By default, this
				  function is disabled.
				  Jumbo frame usually improve the performance
				  int gigabit.
				  This feature need jumbo frame compatible 
				  remote.
				  
rx_coalesce=m			- Number of rx frame handled each interrupt.
rx_timeout=n			- Rx DMA wait time for an interrupt. 
				  If set rx_coalesce > 0, hardware only assert 
				  an interrupt for m frames. Hardware won't 
				  assert rx interrupt until m frames received or
				  reach timeout of n * 640 nano seconds. 
				  Set proper rx_coalesce and rx_timeout can 
				  reduce congestion collapse and overload which
				  has been a bottlenect for high speed network.
				  
				  For example, rx_coalesce=10 rx_timeout=800.
				  that is, hardware assert only 1 interrupt 
				  for 10 frames received or timeout of 512 us. 

tx_coalesce=n			- Number of tx frame handled each interrupt.
				  Set n > 1 can reduce the interrupts 
				  congestion usually lower performance of
				  high speed network card. Default is 16.
				  
tx_flow=[1|0]			- Specifies the Tx flow control. If tx_flow=0, 
				  the Tx flow control disable else driver
				  autodetect.
rx_flow=[1|0]			- Specifies the Rx flow control. If rx_flow=0, 
				  the Rx flow control enable else driver
				  autodetect.


Configuration Script Sample
===========================
Here is a sample of a simple configuration script:

DEVICE=eth0
USERCTL=no
ONBOOT=yes
POOTPROTO=none
BROADCAST=207.200.5.255
NETWORK=207.200.5.0
NETMASK=255.255.255.0
IPADDR=207.200.5.2


Troubleshooting
===============
Q1. Source files contain ^ M behind every line.
	Make sure all files are Unix file format (no LF). Try the following
    shell command to convert files.

	cat dl2k.c | col -b > dl2k.tmp
	mv dl2k.tmp dl2k.c

	OR

	cat dl2k.c | tr -d "\r" > dl2k.tmp
	mv dl2k.tmp dl2k.c

Q2: Could not find header files (*.h) ?
	To compile the driver, you need kernel header files. After
    installing the kernel source, the header files are usually located in
    /usr/src/linux/include, which is the default include directory configured
    in Makefile. For some distributions, there is a copy of header files in
    /usr/src/include/linux and /usr/src/include/asm, that you can change the
    INCLUDEDIR in Makefile to /usr/include without installing kernel source.
	Note that RH 7.0 didn't provide correct header files in /usr/include,
    including those files will make a wrong version driver.
Commit	Line	Data
1da177e4 LT	1
	2	D-Link DL2000-based Gigabit Ethernet Adapter Installation
	3	for Linux
	4	May 23, 2002
	5
	6	Contents
	7	========
	8	- Compatibility List
	9	- Quick Install
	10	- Compiling the Driver
	11	- Installing the Driver
	12	- Option parameter
	13	- Configuration Script Sample
	14	- Troubleshooting
	15
	16
	17	Compatibility List
	18	=================
	19	Adapter Support:
	20
	21	D-Link DGE-550T Gigabit Ethernet Adapter.
	22	D-Link DGE-550SX Gigabit Ethernet Adapter.
	23	D-Link DL2000-based Gigabit Ethernet Adapter.
	24
	25
	26	The driver support Linux kernel 2.4.7 later. We had tested it
	27	on the environments below.
	28
	29	. Red Hat v6.2 (update kernel to 2.4.7)
	30	. Red Hat v7.0 (update kernel to 2.4.7)
	31	. Red Hat v7.1 (kernel 2.4.7)
	32	. Red Hat v7.2 (kernel 2.4.7-10)
	33
	34
	35	Quick Install
	36	=============
	37	Install linux driver as following command:
	38
	39	1. make all
	40	2. insmod dl2k.ko
	41	3. ifconfig eth0 up 10.xxx.xxx.xxx netmask 255.0.0.0
	42	^^^^^^^^^^^^^^^\ ^^^^^^^^\
	43	IP NETMASK
	44	Now eth0 should active, you can test it by "ping" or get more information by
	45	"ifconfig". If tested ok, continue the next step.
	46
	47	4. cp dl2k.ko /lib/modules/`uname -r`/kernel/drivers/net
	48	5. Add the following line to /etc/modprobe.conf:
	49	alias eth0 dl2k
	50	6. Run "netconfig" or "netconf" to create configuration script ifcfg-eth0
	51	located at /etc/sysconfig/network-scripts or create it manually.
	52	[see - Configuration Script Sample]
	53	7. Driver will automatically load and configure at next boot time.
	54
	55	Compiling the Driver
	56	====================
	57	In Linux, NIC drivers are most commonly configured as loadable modules.
	58	The approach of building a monolithic kernel has become obsolete. The driver
	59	can be compiled as part of a monolithic kernel, but is strongly discouraged.
	60	The remainder of this section assumes the driver is built as a loadable module.
	61	In the Linux environment, it is a good idea to rebuild the driver from the
	62	source instead of relying on a precompiled version. This approach provides
	63	better reliability since a precompiled driver might depend on libraries or
	64	kernel features that are not present in a given Linux installation.
65
66	The 3 files necessary to build Linux device driver are dl2k.c, dl2k.h and
67	Makefile. To compile, the Linux installation must include the gcc compiler,
68	the kernel source, and the kernel headers. The Linux driver supports Linux
69	Kernels 2.4.7. Copy the files to a directory and enter the following command
70	to compile and link the driver:
71
72	CD-ROM drive
73	------------
74
75	[root@XXX /] mkdir cdrom
76	[root@XXX /] mount -r -t iso9660 -o conv=auto /dev/cdrom /cdrom
77	[root@XXX /] cd root
78	[root@XXX /root] mkdir dl2k
79	[root@XXX /root] cd dl2k
80	[root@XXX dl2k] cp /cdrom/linux/dl2k.tgz /root/dl2k
81	[root@XXX dl2k] tar xfvz dl2k.tgz
82	[root@XXX dl2k] make all
83
84	Floppy disc drive
85	-----------------
86
87	[root@XXX /] cd root
88	[root@XXX /root] mkdir dl2k
89	[root@XXX /root] cd dl2k
90	[root@XXX dl2k] mcopy a:/linux/dl2k.tgz /root/dl2k
91	[root@XXX dl2k] tar xfvz dl2k.tgz
92	[root@XXX dl2k] make all
93
94	Installing the Driver
95	=====================
96
97	Manual Installation
98	-------------------
99	Once the driver has been compiled, it must be loaded, enabled, and bound
100	to a protocol stack in order to establish network connectivity. To load a
101	module enter the command:
102
103	insmod dl2k.o
104
105	or
106
107	insmod dl2k.o <optional parameter> ; add parameter
108
109	===============================================================
110	example: insmod dl2k.o media=100mbps_hd
111	or insmod dl2k.o media=3
112	or insmod dl2k.o media=3,2 ; for 2 cards
113	===============================================================
114
115	Please reference the list of the command line parameters supported by
116	the Linux device driver below.
117
118	The insmod command only loads the driver and gives it a name of the form
119	eth0, eth1, etc. To bring the NIC into an operational state,
120	it is necessary to issue the following command:
121
122	ifconfig eth0 up
123
124	Finally, to bind the driver to the active protocol (e.g., TCP/IP with
125	Linux), enter the following command:
126
127	ifup eth0
128
129	Note that this is meaningful only if the system can find a configuration
130	script that contains the necessary network information. A sample will be
131	given in the next paragraph.
132
133	The commands to unload a driver are as follows:
134
135	ifdown eth0
136	ifconfig eth0 down
137	rmmod dl2k.o
138
139	The following are the commands to list the currently loaded modules and
140	to see the current network configuration.
141
142	lsmod
143	ifconfig
144
145
146	Automated Installation
147	----------------------
148	This section describes how to install the driver such that it is
149	automatically loaded and configured at boot time. The following description
150	is based on a Red Hat 6.0/7.0 distribution, but it can easily be ported to
151	other distributions as well.
152
153	Red Hat v6.x/v7.x
154	-----------------
155	1. Copy dl2k.o to the network modules directory, typically
156	/lib/modules/2.x.x-xx/net or /lib/modules/2.x.x/kernel/drivers/net.
157	2. Locate the boot module configuration file, most commonly modprobe.conf
158	or modules.conf (for 2.4) in the /etc directory. Add the following lines:
159
160	alias ethx dl2k
161	options dl2k <optional parameters>
162
163	where ethx will be eth0 if the NIC is the only ethernet adapter, eth1 if
164	one other ethernet adapter is installed, etc. Refer to the table in the
165	previous section for the list of optional parameters.
166	3. Locate the network configuration scripts, normally the
167	/etc/sysconfig/network-scripts directory, and create a configuration
168	script named ifcfg-ethx that contains network information.
169	4. Note that for most Linux distributions, Red Hat included, a configuration
170	utility with a graphical user interface is provided to perform steps 2
171	and 3 above.
172
173
174	Parameter Description
175	=====================
176	You can install this driver without any addtional parameter. However, if you
177	are going to have extensive functions then it is necessary to set extra
178	parameter. Below is a list of the command line parameters supported by the
179	Linux device
180	driver.
181
182	mtu=packet_size - Specifies the maximum packet size. default
183	is 1500.
184
185	media=media_type - Specifies the media type the NIC operates at.
186	autosense Autosensing active media.
187	10mbps_hd 10Mbps half duplex.
188	10mbps_fd 10Mbps full duplex.
189	100mbps_hd 100Mbps half duplex.
190	100mbps_fd 100Mbps full duplex.
191	1000mbps_fd 1000Mbps full duplex.
192	1000mbps_hd 1000Mbps half duplex.
193	0 Autosensing active media.
194	1 10Mbps half duplex.
195	2 10Mbps full duplex.
196	3 100Mbps half duplex.
197	4 100Mbps full duplex.
198	5 1000Mbps half duplex.
199	6 1000Mbps full duplex.
200
201	By default, the NIC operates at autosense.
202	1000mbps_fd and 1000mbps_hd types are only
203	available for fiber adapter.
204
205	vlan=n - Specifies the VLAN ID. If vlan=0, the
206	Virtual Local Area Network (VLAN) function is
207	disable.
208
209	jumbo=[0\|1] - Specifies the jumbo frame support. If jumbo=1,
210	the NIC accept jumbo frames. By default, this
211	function is disabled.
212	Jumbo frame usually improve the performance
213	int gigabit.
214	This feature need jumbo frame compatible
215	remote.
216
217	rx_coalesce=m - Number of rx frame handled each interrupt.
218	rx_timeout=n - Rx DMA wait time for an interrupt.
219	If set rx_coalesce > 0, hardware only assert
220	an interrupt for m frames. Hardware won't
221	assert rx interrupt until m frames received or
222	reach timeout of n * 640 nano seconds.
223	Set proper rx_coalesce and rx_timeout can
224	reduce congestion collapse and overload which
225	has been a bottlenect for high speed network.
226
227	For example, rx_coalesce=10 rx_timeout=800.
228	that is, hardware assert only 1 interrupt
229	for 10 frames received or timeout of 512 us.
230
231	tx_coalesce=n - Number of tx frame handled each interrupt.
232	Set n > 1 can reduce the interrupts
233	congestion usually lower performance of
234	high speed network card. Default is 16.
235
236	tx_flow=[1\|0] - Specifies the Tx flow control. If tx_flow=0,
237	the Tx flow control disable else driver
238	autodetect.
239	rx_flow=[1\|0] - Specifies the Rx flow control. If rx_flow=0,
240	the Rx flow control enable else driver
241	autodetect.
242
243
244	Configuration Script Sample
245	===========================
246	Here is a sample of a simple configuration script:
247
248	DEVICE=eth0
249	USERCTL=no
250	ONBOOT=yes
251	POOTPROTO=none
252	BROADCAST=207.200.5.255
253	NETWORK=207.200.5.0
254	NETMASK=255.255.255.0
255	IPADDR=207.200.5.2
256
257
258	Troubleshooting
259	===============
260	Q1. Source files contain ^ M behind every line.
261	Make sure all files are Unix file format (no LF). Try the following
262	shell command to convert files.
263
264	cat dl2k.c \| col -b > dl2k.tmp
265	mv dl2k.tmp dl2k.c
266
267	OR
268
269	cat dl2k.c \| tr -d "\r" > dl2k.tmp
270	mv dl2k.tmp dl2k.c
271
272	Q2: Could not find header files (*.h) ?
273	To compile the driver, you need kernel header files. After
274	installing the kernel source, the header files are usually located in
275	/usr/src/linux/include, which is the default include directory configured
276	in Makefile. For some distributions, there is a copy of header files in
277	/usr/src/include/linux and /usr/src/include/asm, that you can change the
278	INCLUDEDIR in Makefile to /usr/include without installing kernel source.
279	Note that RH 7.0 didn't provide correct header files in /usr/include,
280	including those files will make a wrong version driver.
281