InfiniBand SRP initiator stable sysfs ABI | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

SRP target login

sysfs-driver-ib_srp:1-73

add_target에 comma-separated parameter를 기록해 target port ID, destination path, SCSI limit, S/G 전송과 completion vector를 구성합니다.

Local HCA와 port

sysfs-driver-ib_srp:74-84

SRP class instance를 만든 local InfiniBand HCA 이름과 port 번호를 제공합니다.

SCSI host transport state

sysfs-driver-ib_srp:86-161

생성된 SCSI host에서 S/G, RDMA channel, completion vector, local·remote GID와 target identifier를 조회합니다.

SRP request credit

sysfs-driver-ib_srp:163-192

Target service ID, source GID, 현재 request credit과 credit 고갈로 기다린 횟수를 제공합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/add_target

2 Date: January 2, 2006

3 KernelVersion: 2.6.15

4 Contact: linux-rdma@vger.kernel.org

5 Description: Interface for making ib_srp connect to a new target.

6 One can request ib_srp to connect to a new target by writing

7 a comma-separated list of login parameters to this sysfs

8 attribute. The supported parameters are:

10 * id_ext, a 16-digit hexadecimal number specifying the eight

11 byte identifier extension in the 16-byte SRP target port

12 identifier. The target port identifier is sent by ib_srp

13 to the target in the SRP_LOGIN_REQ request.

14 * ioc_guid, a 16-digit hexadecimal number specifying the eight

15 byte I/O controller GUID portion of the 16-byte target port

16 identifier.

17 * dgid, a 32-digit hexadecimal number specifying the

18 destination GID.

19 * pkey, a four-digit hexadecimal number specifying the

20 InfiniBand partition key.

21 * service_id, a 16-digit hexadecimal number specifying the

22 InfiniBand service ID used to establish communication with

23 the SRP target. How to find out the value of the service ID

24 is specified in the documentation of the SRP target.

25 * max_sect, a decimal number specifying the maximum number of

26 512-byte sectors to be transferred via a single SCSI command.

27 * max_cmd_per_lun, a decimal number specifying the maximum

28 number of outstanding commands for a single LUN.

29 * io_class, a hexadecimal number specifying the SRP I/O class.

30 Must be either 0xff00 (rev 10) or 0x0100 (rev 16a). The I/O

31 class defines the format of the SRP initiator and target

32 port identifiers.

33 * initiator_ext, a 16-digit hexadecimal number specifying the

34 identifier extension portion of the SRP initiator port

35 identifier. This data is sent by the initiator to the target

36 in the SRP_LOGIN_REQ request.

37 * cmd_sg_entries, a number in the range 1..255 that specifies

38 the maximum number of data buffer descriptors stored in the

39 SRP_CMD information unit itself. With allow_ext_sg=0 the

40 parameter cmd_sg_entries defines the maximum S/G list length

41 for a single SRP_CMD, and commands whose S/G list length

42 exceeds this limit after S/G list collapsing will fail.

43 * allow_ext_sg, whether ib_srp is allowed to include a partial

44 memory descriptor list in an SRP_CMD instead of the entire

45 list. If a partial memory descriptor list has been included

46 in an SRP_CMD the remaining memory descriptors are

47 communicated from initiator to target via an additional RDMA

48 transfer. Setting allow_ext_sg to 1 increases the maximum

49 amount of data that can be transferred between initiator and

50 target via a single SCSI command. Since not all SRP target

51 implementations support partial memory descriptor lists the

52 default value for this option is 0.

53 * sg_tablesize, a number in the range 1..2048 specifying the

54 maximum S/G list length the SCSI layer is allowed to pass to

55 ib_srp. Specifying a value that exceeds cmd_sg_entries is

56 only safe with partial memory descriptor list support enabled

57 (allow_ext_sg=1).

58 * comp_vector, a number in the range 0..n-1 specifying the

59 MSI-X completion vector of the first RDMA channel. Some

60 HCA's allocate multiple (n) MSI-X vectors per HCA port. If

61 the IRQ affinity masks of these interrupts have been

62 configured such that each MSI-X interrupt is handled by a

63 different CPU then the comp_vector parameter can be used to

64 spread the SRP completion workload over multiple CPU's.

65 * tl_retry_count, a number in the range 2..7 specifying the

66 IB RC retry count.

67 * queue_size, the maximum number of commands that the

68 initiator is allowed to queue per SCSI host. The default

69 value for this parameter is 62. The lowest supported value

70 is 2.

71 * max_it_iu_size, a decimal number specifying the maximum

72 initiator to target information unit length.

74 What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/ibdev

75 Date: January 2, 2006

76 KernelVersion: 2.6.15

77 Contact: linux-rdma@vger.kernel.org

78 Description: HCA name (<hca>).

80 What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/port

81 Date: January 2, 2006

82 KernelVersion: 2.6.15

83 Contact: linux-rdma@vger.kernel.org

84 Description: HCA port number (<port_number>).

86 What: /sys/class/scsi_host/host<n>/allow_ext_sg

87 Date: May 19, 2011

88 KernelVersion: 2.6.39

89 Contact: linux-rdma@vger.kernel.org

90 Description: Whether ib_srp is allowed to include a partial memory

91 descriptor list in an SRP_CMD when communicating with an SRP

92 target.

94 What: /sys/class/scsi_host/host<n>/ch_count

95 Date: April 1, 2015

96 KernelVersion: 3.19

97 Contact: linux-rdma@vger.kernel.org

98 Description: Number of RDMA channels used for communication with the SRP

99 target.

100

101 What: /sys/class/scsi_host/host<n>/cmd_sg_entries

102 Date: May 19, 2011

103 KernelVersion: 2.6.39

104 Contact: linux-rdma@vger.kernel.org

105 Description: Maximum number of data buffer descriptors that may be sent to

106 the target in a single SRP_CMD request.

107

108 What: /sys/class/scsi_host/host<n>/comp_vector

109 Date: September 2, 2013

110 KernelVersion: 3.11

111 Contact: linux-rdma@vger.kernel.org

112 Description: Completion vector used for the first RDMA channel.

113

114 What: /sys/class/scsi_host/host<n>/dgid

115 Date: June 17, 2006

116 KernelVersion: 2.6.17

117 Contact: linux-rdma@vger.kernel.org

118 Description: InfiniBand destination GID used for communication with the SRP

119 target. Differs from orig_dgid if port redirection has happened.

120

121 What: /sys/class/scsi_host/host<n>/id_ext

122 Date: June 17, 2006

123 KernelVersion: 2.6.17

124 Contact: linux-rdma@vger.kernel.org

125 Description: Eight-byte identifier extension portion of the 16-byte target

126 port identifier.

127

128 What: /sys/class/scsi_host/host<n>/ioc_guid

129 Date: June 17, 2006

130 KernelVersion: 2.6.17

131 Contact: linux-rdma@vger.kernel.org

132 Description: Eight-byte I/O controller GUID portion of the 16-byte target

133 port identifier.

134

135 What: /sys/class/scsi_host/host<n>/local_ib_device

136 Date: November 29, 2006

137 KernelVersion: 2.6.19

138 Contact: linux-rdma@vger.kernel.org

139 Description: Name of the InfiniBand HCA used for communicating with the

140 SRP target.

141

142 What: /sys/class/scsi_host/host<n>/local_ib_port

143 Date: November 29, 2006

144 KernelVersion: 2.6.19

145 Contact: linux-rdma@vger.kernel.org

146 Description: Number of the HCA port used for communicating with the

147 SRP target.

148

149 What: /sys/class/scsi_host/host<n>/orig_dgid

150 Date: June 17, 2006

151 KernelVersion: 2.6.17

152 Contact: linux-rdma@vger.kernel.org

153 Description: InfiniBand destination GID specified in the parameters

154 written to the add_target sysfs attribute.

155

156 What: /sys/class/scsi_host/host<n>/pkey

157 Date: June 17, 2006

158 KernelVersion: 2.6.17

159 Contact: linux-rdma@vger.kernel.org

160 Description: A 16-bit number representing the InfiniBand partition key used

161 for communication with the SRP target.

162

163 What: /sys/class/scsi_host/host<n>/req_lim

164 Date: October 20, 2010

165 KernelVersion: 2.6.36

166 Contact: linux-rdma@vger.kernel.org

167 Description: Number of requests ib_srp can send to the target before it has

168 to wait for more credits. For more information see also the

169 SRP credit algorithm in the SRP specification.

170

171 What: /sys/class/scsi_host/host<n>/service_id

172 Date: June 17, 2006

173 KernelVersion: 2.6.17

174 Contact: linux-rdma@vger.kernel.org

175 Description: InfiniBand service ID used for establishing communication with

176 the SRP target.

177

178 What: /sys/class/scsi_host/host<n>/sgid

179 Date: February 1, 2014

180 KernelVersion: 3.13

181 Contact: linux-rdma@vger.kernel.org

182 Description: InfiniBand GID of the source port used for communication with

183 the SRP target.

184

185 What: /sys/class/scsi_host/host<n>/zero_req_lim

186 Date: September 20, 2006

187 KernelVersion: 2.6.18

188 Contact: linux-rdma@vger.kernel.org

189 Description: Number of times the initiator had to wait before sending a

190 request to the target because it ran out of credits. For more

191 information see also the SRP credit algorithm in the SRP

192 specification.

193

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

새 SRP target 연결 요청

1-9

항목	내용
What	/sys/class/infiniband_srp/srp-<hca>-<port_number>/add_target
Date	2006년 1월 2일
KernelVersion	2.6.15
Contact	linux-rdma@vger.kernel.org

ib_srp가 새 target에 연결하도록 요청하는 interface다. Comma로 구분한 login parameter 목록을 이 sysfs attribute에 쓰면 연결을 시작한다.

add_target에서 SCSI host 생성까지

add_target에 comma-separated parameter 기록HCA port에서 destination GID와 service ID로 연결SRP_LOGIN_REQ에 initiator·target port identifier 전달Target login 성공host<n> SCSI host와 transport attribute 생성

Target identity와 InfiniBand path parameter

10-36

Parameter	형식	의미
id_ext	16자리 hexadecimal	16-byte SRP target port identifier 중 8-byte identifier-extension 부분이다. ib_srp가 SRP_LOGIN_REQ로 target에 보낸다.
ioc_guid	16자리 hexadecimal	16-byte target port identifier 중 8-byte I/O-controller GUID 부분이다.
dgid	32자리 hexadecimal	Destination GID를 지정한다.
pkey	4자리 hexadecimal	InfiniBand partition key를 지정한다.
service_id	16자리 hexadecimal	SRP target과 통신을 설정할 때 사용하는 InfiniBand service ID다. 값을 찾는 방법은 SRP target 문서가 정한다.
max_sect	decimal	SCSI command 하나로 전송할 수 있는 512-byte sector의 최대 개수다.
max_cmd_per_lun	decimal	LUN 하나에 동시에 outstanding 상태로 둘 수 있는 command의 최대 개수다.
io_class	hexadecimal	SRP I/O class다. 0xff00(rev 10) 또는 0x0100(rev 16a)만 허용된다. I/O class는 SRP initiator와 target port identifier의 형식을 정한다.
initiator_ext	16자리 hexadecimal	SRP initiator port identifier의 identifier-extension 부분이다. Initiator가 SRP_LOGIN_REQ로 target에 보낸다.

SRP_CMD의 scatter/gather descriptor

37-57

Parameter	범위·기본값	의미와 제약
cmd_sg_entries	1..255	SRP_CMD information unit 자체에 저장할 수 있는 data-buffer descriptor의 최대 개수다. allow_ext_sg=0이면 SRP_CMD 하나의 최대 S/G list 길이가 된다. S/G list collapsing 뒤에도 이 limit를 넘는 command는 실패한다.
allow_ext_sg	기본값 0	전체 memory-descriptor list 대신 일부만 SRP_CMD에 넣도록 허용할지 정한다. 일부만 넣으면 나머지는 추가 RDMA transfer로 initiator에서 target에 전달한다. 1로 설정하면 SCSI command 하나로 전송할 수 있는 최대 data 양이 커지지만, 모든 SRP target이 partial list를 지원하지 않으므로 기본값은 0이다.
sg_tablesize	1..2048	SCSI layer가 ib_srp에 넘길 수 있는 최대 S/G list 길이다. cmd_sg_entries보다 큰 값을 지정하는 것은 partial memory-descriptor list 지원을 켠 allow_ext_sg=1일 때만 안전하다.

Partial S/G list를 사용할 때의 descriptor 전달

Initiator SCSI layerSRP_CMDSRP target

01 S/G list 생성cmd_sg_entries까지 내장Command 수신

02 allow_ext_sg=0초과하면 command 실패추가 list 없음

03 allow_ext_sg=1Partial list 표시남은 descriptor를 RDMA로 수신

allow_ext_sg가 0이면 모든 descriptor가 SRP_CMD 안에 들어가야 하고, 1이면 남은 descriptor를 별도 RDMA로 전달할 수 있다.

Completion CPU 배치와 queue limit

58-73

Parameter	범위·기본값	의미
comp_vector	0..n-1	첫 번째 RDMA channel이 사용할 MSI-X completion vector다. HCA port 하나에 여러 MSI-X vector를 할당한 HCA에서 각 interrupt affinity를 서로 다른 CPU로 설정했다면 SRP completion 부하를 여러 CPU에 분산할 수 있다.
tl_retry_count	2..7	InfiniBand Reliable Connection(RC)의 retry count다.
queue_size	기본 62, 최소 2	Initiator가 SCSI host 하나당 queue에 넣을 수 있는 command의 최대 개수다.
max_it_iu_size	decimal	Initiator에서 target으로 보내는 information unit의 최대 길이다.

SRP class instance의 HCA와 port

74-84

두 ABI는 2006년 1월 2일 kernel 2.6.15에 도입됐고 linux-rdma@vger.kernel.org가 담당한다.

경로	설명
/sys/class/infiniband_srp/srp-<hca>-<port_number>/ibdev	HCA 이름, 즉 경로의 <hca> 값을 표시한다.
/sys/class/infiniband_srp/srp-<hca>-<port_number>/port	HCA port 번호, 즉 경로의 <port_number> 값을 표시한다.

SCSI host의 command와 RDMA channel 설정

86-113

경로 suffix	도입	설명
allow_ext_sg	2011-05-19 · 2.6.39	SRP target과 통신할 때 ib_srp가 SRP_CMD에 partial memory-descriptor list를 넣도록 허용하는지 나타낸다.
ch_count	2015-04-01 · 3.19	SRP target과 통신하는 데 사용하는 RDMA channel의 수다.
cmd_sg_entries	2011-05-19 · 2.6.39	SRP_CMD request 하나로 target에 보낼 수 있는 data-buffer descriptor의 최대 개수다.
comp_vector	2013-09-02 · 3.11	첫 번째 RDMA channel이 사용하는 completion vector다.

Remote target identifier와 redirect 전후 GID

114-134

경로 suffix	도입	설명
dgid	2006-06-17 · 2.6.17	SRP target과 통신할 때 실제로 사용하는 InfiniBand destination GID다. Port redirection이 일어났다면 orig_dgid와 다르다.
id_ext	2006-06-17 · 2.6.17	16-byte target port identifier 중 8-byte identifier-extension 부분이다.
ioc_guid	2006-06-17 · 2.6.17	16-byte target port identifier 중 8-byte I/O-controller GUID 부분이다.

Local HCA, original destination과 partition

135-161

경로 suffix	도입	설명
local_ib_device	2006-11-29 · 2.6.19	SRP target과 통신할 때 사용하는 local InfiniBand HCA 이름이다.
local_ib_port	2006-11-29 · 2.6.19	SRP target과 통신할 때 사용하는 HCA port 번호다.
orig_dgid	2006-06-17 · 2.6.17	add_target sysfs attribute에 기록한 parameter의 원래 InfiniBand destination GID다.
pkey	2006-06-17 · 2.6.17	SRP target과 통신할 때 사용하는 InfiniBand partition key를 나타내는 16-bit 값이다.

Service, source GID와 SRP request credit

163-192

경로 suffix	도입	설명
req_lim	2010-10-20 · 2.6.36	ib_srp가 더 많은 credit을 기다리기 전에 target으로 보낼 수 있는 request의 수다. 자세한 내용은 SRP specification의 SRP credit algorithm을 참조한다.
service_id	2006-06-17 · 2.6.17	SRP target과 통신을 설정할 때 사용하는 InfiniBand service ID다.
sgid	2014-02-01 · 3.13	SRP target과 통신할 때 사용하는 source port의 InfiniBand GID다.
zero_req_lim	2006-09-20 · 2.6.18	Credit이 고갈되어 initiator가 target에 request를 보내기 전에 기다려야 했던 횟수다. 자세한 내용은 SRP specification의 SRP credit algorithm을 참조한다.

SRP request credit 소모와 대기

Target이 request credit 제공Initiator가 request를 보내며 credit 소비req_lim 범위 안에서 계속 전송Credit이 0이면 추가 credit을 기다림대기가 발생할 때 zero_req_lim 증가

req_lim은 현재 보낼 수 있는 양을 제한하고 zero_req_lim은 credit 고갈이 실제 대기를 일으킨 횟수를 누적한다.