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