**************************************** README **************************************** Chelsio Network Driver for macOS Version : 1.23.4b2 (Beta) Date : 05/02/2019 Overview ================================================================================ Chelsio's installer package installs T6,T5,T4 and T3 network drivers for macOS operating system. The network driver provides support for PCI Express Ethernet adapters based on the Chelsio Terminator (T6,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 T6/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 T6/T5/T4/T3 adapter and system with below mentioned supported platforms. 2. Supported Operating System ================================================================================ This release of the Chelsio Network driver supports the following Intel based platforms in NIC mode: - macOS 10.14 (Mojave 64-bit) - macOS 10.13 (High Sierra 64-bit) - macOS 10.12.x (Sierra 64-bit) - Macintosh OS X 10.11.x (El Capitan 64-bit) Other versions have not been tested and are not guaranteed to work. 3. Supported Adapters ================================================================================ T6 Adapters ----------- - T6225-CR - T6225-LL-CR - T6225-SO-CR - T62100-CR - T62100-LP-CR - T62100-SO-CR T5 Adapters ----------- - T580-CR - T580-SO-CR - T580-LP-CR - T520-LL-CR - T520-SO-CR - T520-CR - T520-BT - T540-CR - T540-LP-CR - T540-SO-CR T4 Adapters ----------- - T420-CR - T440-CR - T404-BT - T422-CR - T420-SO-CR - T420-LL-CR - T440-LP-CR - T420-CX 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. NOTE: Spider cables not 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. Driver Installation ======================== GUI --- a) Mount the disk image cxgb-x.y.z.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 using Safari browser it will mount automatically. b) Locate the "cxgb.pkg" 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 (T6/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. CLI --- a) Mount the disk image cxgb-x.y.z.dmg host:root# hdiutil mount Desktop/cxgb-x.y.z.dmg The disk image will be mounted to "/Volumes" directory. b) Install the driver: host:root# installer -pkg /Volumes/cxgb-x.y.z/cxgb.pkg -target / 4.2. Driver Loading =================== NOTE: The installer will copy the signed KEXT into /Library/Extensions/ directory. - To load the T6/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 ========================= 4.3.1. Important Configurable Parameters ---------------------------------------- - FEC Chelsio T6 Unified Wire adapters support changing Forward Error Correction (FEC). The existing FEC settings can be viewed using: host:root# sudo cxgbtool fec To set FEC: host:root# sudo cxgbtool fec Here value can be: rs : Reed-Solomon FEC baser: Base-R/Reed-Solomon FEC auto : Use standard FEC settings as specified by IEEE 802.3 interpretations of Cable Transceiver Module parameters. off : Turn off FEC. NOTE: - FEC auto-negotiation is not supported on optic link. - If auto-negotiation is disabled, ensure that the same FEC is set on both sides of the link, for the link to come up. - LRO Large Receive Offload (LRO) support is enabled by default. It can be disabled using cxgbtool: host:root# sudo cxgbtool cxgbX lro 0 To verify if LRO is enabled or disabled use: host:root# sudo cxgbtool cxgbX qset In the output, the LRO field should display 0 if disabled and 1 if enabled. - TCP Segmentation Offload Support TCP Segmentation Offload has been supported since Snow Leopard and enabled by default. It can be disabled globally by using: host:root# sysctl net.inet.tcp.tso=0 4.3.2. Kernel Tuning -------------------- - Increasing default parameter values Edit /etc/sysctl.conf to increase default parameter values on the client: For example, If the default value for kern.ipc.maxsockbuf < 2097152 then set it in /etc/sysctl.conf to be 2097152. - 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. 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. The cxgbtool command with no parameters will list the master physical function BSD interface name. For more information use cxgbtool help: host:root# sudo cxgbtool -h NOTE: cxgbtool supports filtering settings on the Chelsio T3 based adapters only. 4.6. Firmware Update ==================== The minimum firmware version (v1.23.4.0) 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-x.y.z.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# sudo cxgbtool cxgbX loadfw .bin 4.7. Driver Unloading ===================== - To unload the T6/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. Driver Uninstallation ========================== Before proceeding refer section "Unloading the driver" and unload the driver depending on driver type. - To uninstall the T6/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 contains: - README - Release Notes - User's Guide 6. Customer Support ================================================================================ Please contact Chelsio support at support@chelsio.com for any issues regarding the product. ******************************************************************************** Copyright (C) 2019 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.