**************************************** README **************************************** Chelsio Network driver for Macintosh OS X Version : 1.10.11 Date : 02/03/2016 Overview ================================================================================ Chelsio's installer package installs T5,T4 and T3 network drivers for Macintosh OS X operating system. The network driver provides support for PCI Express Ethernet adapters based on the Chelsio Terminator (T5,T4 and T3) ASIC. The driver also supports Jumbo Frames, Transmit/Receive checksum offload, TCP segmentation offload (TSO/LSO), MSI Interrupts, Gatekeeper and Large Receive Offload (LRO). The installer package contains T5/T4/T3 kernel extension installation feature. Please refer section 4.1 for details. ================================================================================ CONTENTS ================================================================================ - 1. Requirements - 2. Supported Operating System - 3. Supported Adapters - 4. How to Use - 5. Support Documentation - 6. Customer Support 1. Requirements ================================================================================ - Chelsio T5 40/10/1Gb or T4/T3 10/1Gb adapter and system with below mentioned supported platforms. 2. Supported Operating System ================================================================================ This release of the Chelsio Network driver supports the following Intel based Macintosh OS X platforms in NIC mode: - Macintosh OS X 10.11.x (El Capitan 64-bit) - Macintosh OS X 10.10.x (Yosemite 64-bit) Other versions have not been tested and are not guaranteed to work. 3. Supported Adapters ================================================================================ 3.1. T5 Adapters ------------------ - T580-CR - T580-SO-CR - T580-LP-CR - T520-LL-CR - T520-SO-CR - T520-CR - T540-CR 3.2. T4 Adapters ------------------ - T420-CR - T440-CR - T404-BT - T422-CR - T420-SO-CR - T420-LL-CR - T440-LP-CR - T420-CX 3.3. T3 Adapters ------------------ - N310E - N310E-CXA - N320E-GEN2 - S310E-SR - S310E-SR+ - S310E-CXA - S310E-CR - N320E-CXA* - S320E-CR* - S320E-LP-CR* - S302E* - S320E-CXA* *Only port 0 (first port) supported. 4. How to Use ================================================================================ The driver must be installed by the administrator. Any attempt in installing the driver as a regular user will fail. 4.1. Installing the driver -------------------------- i. Mount the disk image cxgb.dmg file by double-clicking on it. The cxgb disk image should mount as a new device and place you in the base directory of the cxgb device. If the disk image is downloaded by Safari it will mount automatically. ii. Locate the "cxgb.mpkg" installer package inside the mounted device and double-click on it to start the installer. The installer will guide you through the remainder of the installation process. **NOTE: - Installer provides facility to customize installation. User can choose between cxgb (T5/T4 kernel extension), cxgb3 (T3 kernel extension) or cxgbtool (command line utility). In standard installation all three components will be selected & installed. - To know more about T3 network driver, please refer the README displayed during the driver installation. 4.2. Loading the Network driver ------------------------------- NOTE: The installer will copy the signed KEXT into /Library/Extensions/ directory. - To load the T5/T4 driver, run the following command: host:root# sudo kextload /Library/Extensions/cxgb.kext - To load the T3 driver, run the following command: host:root# sudo kextload /Library/Extensions/cxgb3.kext 4.3. Driver configuration and tuning ------------------------------------ For recent kernels, code-signing checks are enabled by default. Apple provides various mechanisms to disable them globally if required. Prior to MacOSX 10.11, if the Info.plist file needs to be modified for some reason then use the following commands: host:root# sudo nvram boot-args="kext-dev-mode=1" host:root# reboot 4.3.1. Important configurable parameters Based on the adapter installed in the system (T5 or T4), please add the following parameters under the appropriate section in Info.plist file. (The installer will copy the Info.plist file to /Library/Extensions/cxgb.kext/Contents/ directory) E.g., for T5, add the and elements in the "Terminator5" element section. i. LRO Large Receive Offload support is enabled by default. It can be disabled by setting the key LRO in the property list to an LRO mode of zero: LRO 0 Supported modes are 0,1,2,3. Default is mode 1. Mode 2 does LRO for pure acks while Mode 3 doesn't do LRO for mbuf header sized packets. ii. TCP Segmentation Offload support TCP Segmentation Offload support is enabled by default. It can be disabled globally by using the following command: host:root# sysctl net.inet.tcp.tso=0 TSO can also be disabled in the driver by setting the key "TSO" in the property list to any string: TSO iii. MSI Interrupts MSI interrupts are available and enabled by default. They can be disabled by adding the entry with key "MSI" in the property list: MSI disable Currently, the driver initializes one qset per port. The driver supports multiple MSI vectors if available. 4.3.2. Kernel tuning: i. Increasing default parameter values Edit /etc/sysctl.conf to increase default parameter values on Mac OS X client: For example, If the default value for kern.ipc.maxsockbuf < 2097152 then set it in /etc/sysctl.conf to be 2097152. ii. Increasing mbuf cluster If dmesg output contains "outputPacket() zero segments", it means in order to support the workload the number of mbuf clusters available should be increased as packet drops are occurring. This can be achieved by increasing the number of mbuf clusters using boot-args parameter ncl. See http://support.apple.com/kb/HT3512 for more information. 4.4. Network Device Configuration --------------------------------- Please refer to the operating system documentation for administration and configuration of network devices. **NOTE: - Some operating systems may attempt to auto-configure the detected hardware and some may not detect all ports on a multi-port adapter. If this happens, please refer to the operating system documentation for manually configuring the network device. - Network preferences panel should be used for changing interface properties such as active/inactive or MTU size. 4.5. cxgbtool ------------- The app cxgbtool is used to display or change Chelsio network card settings. For more help, use cxgbtool help command at command prompt as follows : host:root# cxgbtool -h NOTE:cxgbtool supports filtering settings on the Chelsio T3 based adapters only. 4.6. Firmware Update -------------------- The minimum firmware version (v1.10.11.249) matching the driver must be loaded before the new driver installed can load, and the loading is initiated by the post-install phase of the installer. The current driver can load the new firmware using the "loadfw" command of cxgbtool that came with the currently installed driver. Follow the steps mentioned below: i. If not done already, mount the new disk image "cxgb.dmg" file by double-clicking on it. The cxgb disk image should mount as a new device and place you in the base directory of the cxgb device. ii. Browse to the "firmware" directory. For example, if the disk image was mounted to /Volumes, run the following commands to load the appropriate firmware based on Chelsio adapter family: host:root# cd /Volumes/cxgb-x.y.z/firmware host:root# cxgbtool cxgbX loadfw .bin In the event that firmware needs to be loaded but the driver issues timeout messages then disable the master PF's BSD interface and then add the entry with key "fwattach" in the property list before loading the firmware: fwattach disable Loading firmware and setting hardware registers can only be done using the master physical function which restricts the BSD interface name that can be used as a parameter to cxgbtool for those commands. By default the master physical function is associated with Port 0. 4.7. Unloading the Network driver --------------------------------- - To unload the T5/T4 driver, run the following command: host:root# sudo kextunload /Library/Extensions/cxgb.kext - To unload the T3 driver, run the following command: host:root# sudo kextunload /Library/Extensions/cxgb3.kext NOTE: Unloading the driver while traffic is running, is not recommended. 4.8. Uninstalling the Network driver ------------------------------------ Refer section "4.7. Unloading the driver" and unload the driver depending on driver type. - To Uninstall the T5/T4 driver, run the following command: host:root# rm -rf /Library/Extensions/cxgb.kext - To uninstall the T3 driver, run the following command: host:root# rm -rf /Library/Extensions/cxgb3.kext 5. Support Documentation ================================================================================ The documentation for this release can be found in the cxgb-x.x.x directory. It contains: - cxgbtool README 6. Customer Support ================================================================================ Please contact Chelsio support at support@chelsio.com for any issues regarding the product. ******************************************************************************** Copyright (C) 2016 Chelsio Communications. All Rights Reserved. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Chelsio Communications. Chelsio Communications assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system,or transmitted in any form or by any means without the express written consent of Chelsio Communications.