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