0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =================================
0004 Chelsio S3 iSCSI Driver for Linux
0005 =================================
0006
0007 Introduction
0008 ============
0009
0010 The Chelsio T3 ASIC based Adapters (S310, S320, S302, S304, Mezz cards, etc.
0011 series of products) support iSCSI acceleration and iSCSI Direct Data Placement
0012 (DDP) where the hardware handles the expensive byte touching operations, such
0013 as CRC computation and verification, and direct DMA to the final host memory
0014 destination:
0015
0016 - iSCSI PDU digest generation and verification
0017
0018 On transmitting, Chelsio S3 h/w computes and inserts the Header and
0019 Data digest into the PDUs.
0020 On receiving, Chelsio S3 h/w computes and verifies the Header and
0021 Data digest of the PDUs.
0022
0023 - Direct Data Placement (DDP)
0024
0025 S3 h/w can directly place the iSCSI Data-In or Data-Out PDU's
0026 payload into pre-posted final destination host-memory buffers based
0027 on the Initiator Task Tag (ITT) in Data-In or Target Task Tag (TTT)
0028 in Data-Out PDUs.
0029
0030 - PDU Transmit and Recovery
0031
0032 On transmitting, S3 h/w accepts the complete PDU (header + data)
0033 from the host driver, computes and inserts the digests, decomposes
0034 the PDU into multiple TCP segments if necessary, and transmit all
0035 the TCP segments onto the wire. It handles TCP retransmission if
0036 needed.
0037
0038 On receiving, S3 h/w recovers the iSCSI PDU by reassembling TCP
0039 segments, separating the header and data, calculating and verifying
0040 the digests, then forwarding the header to the host. The payload data,
0041 if possible, will be directly placed into the pre-posted host DDP
0042 buffer. Otherwise, the payload data will be sent to the host too.
0043
0044 The cxgb3i driver interfaces with open-iscsi initiator and provides the iSCSI
0045 acceleration through Chelsio hardware wherever applicable.
0046
0047 Using the cxgb3i Driver
0048 =======================
0049
0050 The following steps need to be taken to accelerates the open-iscsi initiator:
0051
0052 1. Load the cxgb3i driver: "modprobe cxgb3i"
0053
0054 The cxgb3i module registers a new transport class "cxgb3i" with open-iscsi.
0055
0056 * in the case of recompiling the kernel, the cxgb3i selection is located at::
0057
0058 Device Drivers
0059 SCSI device support --->
0060 [*] SCSI low-level drivers --->
0061 <M> Chelsio S3xx iSCSI support
0062
0063 2. Create an interface file located under /etc/iscsi/ifaces/ for the new
0064 transport class "cxgb3i".
0065
0066 The content of the file should be in the following format::
0067
0068 iface.transport_name = cxgb3i
0069 iface.net_ifacename = <ethX>
0070 iface.ipaddress = <iscsi ip address>
0071
0072 * if iface.ipaddress is specified, <iscsi ip address> needs to be either the
0073 same as the ethX's ip address or an address on the same subnet. Make
0074 sure the ip address is unique in the network.
0075
0076 3. edit /etc/iscsi/iscsid.conf
0077 The default setting for MaxRecvDataSegmentLength (131072) is too big;
0078 replace with a value no bigger than 15360 (for example 8192)::
0079
0080 node.conn[0].iscsi.MaxRecvDataSegmentLength = 8192
0081
0082 * The login would fail for a normal session if MaxRecvDataSegmentLength is
0083 too big. A error message in the format of
0084 "cxgb3i: ERR! MaxRecvSegmentLength <X> too big. Need to be <= <Y>."
0085 would be logged to dmesg.
0086
0087 4. To direct open-iscsi traffic to go through cxgb3i's accelerated path,
0088 "-I <iface file name>" option needs to be specified with most of the
0089 iscsiadm command. <iface file name> is the transport interface file created
0090 in step 2.
