README revision 157566 
1$FreeBSD: head/sys/dev/em/README 157566 2006-04-06 17:09:03Z glebius $
2FreeBSD* Driver for the Intel(R) PRO/1000 Family of Adapters
3============================================================
4
5January 4, 2006
6
7
8Contents
9========
10
11- Overview
12- Identifying Your Adapter
13- Building and Installation
14- Speed and Duplex Configuration
15- Additional Configurations
16- Known Limitations
17- Support
18- License
19
20
21Overview
22========
23
24This file describes the FreeBSD* driver for the Intel(R) PRO/1000 Family of
25Adapters. This driver has been developed for use with FreeBSD, Release 4.11
26and greater and Release 5.4.
27
28For questions related to hardware requirements, refer to the documentation
29supplied with your Intel PRO/1000 adapter. All hardware requirements listed
30apply to use with FreeBSD.
31
32
33Identifying Your Adapter
34========================
35
36For information on how to identify your adapter, go to the Adapter &
37Driver ID Guide at:
38
39http://support.intel.com/support/network/sb/cs-012904.htm
40
41
42For the latest Intel network drivers for FreeBSD, see:
43
44http://downloadfinder.intel.com/scripts-df-external/support_intel.aspx
45
46
47NOTE: Mobile adapters are not fully supported.
48
49
50Building and Installation
51=========================
52
53NOTE: The driver can be installed as a dynamic loadable kernel module or
54      compiled into the kernel. You must have kernel sources installed in
55      order to compile the driver module.
56
57In the instructions below, x.x.x is the driver version as indicated in the
58name of the driver tar file.
59
601. Move the base driver tar file to the directory of your choice. For
61   example, use /home/username/em or /usr/local/src/em.
62
632. Untar/unzip the archive:
64
65        tar xvfz em-x.x.x.tar.gz
66
67   This will create an em-x.x.x directory.
68
693. To create a loadable module, perform the following steps.
70   NOTE: To compile the driver into the kernel, go directly to step 4.
71
72        a. To compile the module
73
74                  cd em-x.x.x
75                  make
76
77        b. To install the compiled module in system directory:
78
79                  make install
80
81        c. If you want the driver to load automatically when the system is booted:
82
83              1. Edit /boot/loader.conf, and add the following line:
84
85                  if_em_load="YES"
86
874. To compile the driver into the kernel:
88
89        cd em-x.x.x/src
90
91        cp if_em* /usr/src/sys/dev/em
92
93        cp Makefile.kernel /usr/src/sys/modules/em/Makefile
94
95   Edit the /usr/src/sys/conf/files.i386 file, and add the following lines only if
96   they don't already exist:
97
98        dev/em/if_em.c optional em
99
100        dev/em/if_em_hw.c optional em
101
102   Remove the following lines from the /usr/src/sys/conf/files.i386 file,
103   if they exist:
104
105        dev/em/if_em_fxhw.c optional em
106        dev/em/if_em_phy.c optional em
107
108   Edit the kernel configuration file (i.e., GENERIC or MYKERNEL) in
109   /usr/src/sys/i386/conf, and ensure the following line is present:
110
111        device em
112
113   Compile and install the kernel. The system must be rebooted for the kernel
114   updates to take effect. For additional information on compiling the
115   kernel, consult the FreeBSD operating system documentation.
116
1175. To assign an IP address to the interface, enter the following:
118
119        ifconfig em<interface_num> <IP_address>
120
1216. Verify that the interface works. Enter the following, where <IP_address>
122   is the IP address for another machine on the same subnet as the interface
123   that is being tested:
124
125        ping <IP_address>
126
1277. To configure the IP address to remain after reboot, edit /etc/rc.conf,
128   and create the appropriate ifconfig_em<interface_num>entry:
129
130        ifconfig_em<interface_num>="<ifconfig_settings>"
131
132   Example usage:
133
134        ifconfig_em0="inet 192.168.10.1 netmask 255.255.255.0"
135
136   NOTE: For assistance, see the ifconfig man page.
137
138
139Speed and Duplex Configuration
140==============================
141
142By default, the adapter auto-negotiates the speed and duplex of the
143connection. If there is a specific need, the ifconfig utility can be used to
144configure the speed and duplex settings on the adapter. Example usage:
145
146        ifconfig em<interface_num> <IP_address> media 100baseTX mediaopt
147            full-duplex
148
149   NOTE: Only use mediaopt to set the driver to full-duplex. If mediaopt is
150         not specified and you are not running at gigabit speed, the driver
151         defaults to half-duplex.
152
153
154This driver supports the following media type options:
155
156   autoselect      -  Enables auto-negotiation for speed and duplex.
157
158   10baseT/UTP     -  Sets speed to 10 Mbps. Use the ifconfig mediaopt
159                      option to select full-duplex mode.
160
161   100baseTX       -  Sets speed to 100 Mbps. Use the ifconfig mediaopt
162                      option to select full-duplex mode.
163
164   1000baseTX      -  Sets speed to 1000 Mbps. In this case, the driver
165                      supports only full-duplex mode.
166
167   1000baseSX      -  Sets speed to 1000 Mbps. In this case, the driver
168                      supports only full-duplex mode.
169
170For more information on the ifconfig utility, see the ifconfig man page.
171
172
173Additional Configurations
174=========================
175
176The driver supports Transmit/Receive Checksum Offload and Jumbo Frames on
177all but the 82542-based adapters.  For specific adapters, refer to the
178Identifying Your Adapter section.
179
180  Jumbo Frames
181  ------------
182  To enable Jumbo Frames, use the ifconfig utility to set the Maximum
183  Transport Unit (MTU) frame size above its default of 1500 bytes.
184
185  The Jumbo Frames MTU range for Intel Adapters is 1500 to 16110. To modify
186  the setting, enter the following:
187
188        ifconfig em<interface_num> <hostname or IP address> mtu 9000
189
190  To confirm the MTU used between two specific devices, use:
191
192        route get <destination_IP_address>
193
194  Notes:
195
196  - Only enable Jumbo Frames if your network infrastructure supports them.
197
198  - To enable Jumbo Frames, increase the MTU size on the interface beyond
199    1500.
200
201  - The Jumbo Frames setting on the switch must be set to at least 22 bytes
202    larger than that of the MTU.
203
204  - The maximum MTU setting for Jumbo Frames is 16110.  This value coincides
205    with the maximum Jumbo Frames size of 16128.
206
207  - Some Intel gigabit adapters that support Jumbo Frames have a frame size
208    limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes.
209    The adapters with this limitation are based on the Intel(R) 82571EB,
210    82572EI, 82573L and 80003ES2LAN controller.  These correspond to the
211    following product names:
212     Intel(R) PRO/1000 PT Server Adapter
213     Intel(R) PRO/1000 PT Desktop Adapter
214     Intel(R) PRO/1000 PT Network Connection
215     Intel(R) PRO/1000 PT Dual Port Server Adapter
216     Intel(R) PRO/1000 PT Dual Port Network Connection
217     Intel(R) PRO/1000 PF Server Adapter
218     Intel(R) PRO/1000 PF Network Connection
219     Intel(R) PRO/1000 PF Dual Port Server Adapter
220     Intel(R) PRO/1000 PB Server Connection
221     Intel(R) PRO/1000 PL Network Connection
222     Intel(R) PRO/1000 EB Network Connection with I/O Acceleration
223     Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration
224
225  - Adapters based on the Intel(R) 82542 and 82573V/E controller do not
226    support Jumbo Frames. These correspond to the following product names:
227     Intel(R) PRO/1000 Gigabit Server Adapter
228     Intel(R) PRO/1000 PM Network Connection
229
230  - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or
231    loss of link.
232
233
234  VLANs
235  -----
236  To create a new VLAN interface:
237
238        ifconfig <vlan_name> create
239
240  To associate the VLAN interface with a physical interface and
241  assign a VLAN ID, IP address, and netmask:
242
243        ifconfig <vlan_name> <ip_address> netmask <subnet_mask> vlan
244           <vlan_id> vlandev <physical_interface>
245
246  Example:
247
248        ifconfig vlan10 10.0.0.1 netmask 255.255.255.0 vlan10 vlandev em0
249
250  In this example, all packets will be marked on egress with  802.1Q VLAN
251  tags, specifying a VLAN ID of 10.
252
253  To remove a VLAN interface:
254
255        ifconfig <vlan_name> destroy
256
257
258  Polling
259  -------
260  To enable polling in the driver, add the following options to the kernel
261  configuration, and then recompile the kernel:
262
263        options DEVICE_POLLING
264        options HZ=1000
265
266  At runtime use:
267        ifconfig em0 polling to turn polling on
268  Use:
269        ifconfig em0 -polling to turn polling off
270
271
272  Checksum Offload
273  ----------------
274  Checksum offloading is not supported on 82542 Gigabit adapters.
275
276  Checksum offloading supports both TCP and UDP packets and is
277  supported for both transmit and receive.
278
279  Checksum offloading can be enabled or disabled using ifconfig.
280  Both transmit and receive offloading will be either enabled or
281  disabled together. You cannot enable/disable one without the other.
282
283  To enable checksum offloading:
284
285         ifconfig <interface_num> rxcsum
286
287  To disable checksum offloading:
288
289         ifconfig <interface_num> -rxcsum
290
291  To confirm the current setting:
292
293         ifconfig <interface_num>
294
295  Look for the presence or absence of the following line:
296
297         options=3 <RXCSUM,TXCSUM>
298
299  See the ifconfig man page for further information.
300
301
302Known Limitations
303=================
304
305  In FreeBSD version 4.x with Symmetric MultiProcessing (SMP), there is a known
306  issue on some newer hardware.  The problem is generic kernel and only in SMP
307  mode.  The workaround is to either use FreeBSD version 4.x in single processor
308  mode, or use FreeBSD 5.4 or later.
309
310  There are known performance issues with this driver when running UDP traffic
311  with Jumbo Frames.
312
313  There is a known compatibility issue where time to link is slow or link is not
314  established between 82541/82547 controllers and some switches.  Known switches
315  include:
316        Planex FXG-08TE
317        I-O Data ETG-SH8
318
319  The driver can be compiled with the following changes:
320
321  Edit ./em.x.x.x/src/if_em.h to uncomment the #define EM_MASTER_SLAVE
322  from within the comments.  For example, change from:
323
324      /* #define EM_MASTER_SLAVE  2 */
325  to:
326      #define EM_MASTER_SLAVE  2
327
328  Use one of the following options:
329      1 = Master mode
330      2 = Slave mode
331      3 = Auto master/slave
332  Setting 2 is recommended.
333
334  Recompile the module:
335          a. To compile the module
336                cd em-x.x.x
337                make clean
338                make
339
340   b. To install the compiled module in system directory:
341                make install
342
343
344Support
345=======
346
347For general information and support, go to the Intel support website at:
348
349        http://support.intel.com
350
351If an issue is identified, support is through email only at:
352freebsdnic@mailbox.intel.com
353
354
355License
356=======
357
358This software program is released under the terms of a license agreement
359between you ('Licensee') and Intel. Do not use or load this software or any
360associated materials (collectively, the 'Software') until you have carefully
361read the full terms and conditions of the LICENSE located in this software
362package. By loading or using the Software, you agree to the terms of this
363Agreement. If you do not agree with the terms of this Agreement, do not
364install or use the Software.
365
366* Other names and brands may be claimed as the property of others.
367