Intel QAT rate-limiting SLA sysfs ABI | Linux 6.18.37

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

1. 요약·해설

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

SLA operation interface

sysfs-driver-qat_rl:1-35

sla_op는 cir, pir, srv, rp, id와 함께 add·get·update·rm·rm_all을 수행하며 operation별 input과 output attributes가 다릅니다.

Ring-pair mask and SLA identifier

sysfs-driver-qat_rl:36-105

rp는 최대 4개 ring pairs를 64-bit hexadecimal mask로 지정하고, id는 생성 결과를 받거나 기존 SLA를 get·update·remove할 때 선택합니다.

Committed and peak information rates

sysfs-driver-qat_rl:106-173

cir은 보장 rate, pir은 다른 SLAs가 device를 모두 사용하지 않을 때 도달할 수 있는 최대 rate이며 add·update 전에 설정하고 get 뒤 읽습니다.

SLA service and remaining capability

sysfs-driver-qat_rl:174-226

srv는 SLA의 sym·asym·dc service를 정하고, cap_rem은 특정 service/SLA에 새로 배정하거나 기존 SLA를 늘릴 수 있는 remaining capability를 반환합니다.

2. 영어 원문 전체

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

원문 전체 펼치기

1 What: /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

2 Date: January 2024

3 KernelVersion: 6.7

4 Contact: [email protected]

5 Description:

6 (WO) This attribute is used to perform an operation on an SLA.

7 The supported operations are: add, update, rm, rm_all, and get.

9 Input values must be filled through the associated attribute in

10 this group before a write to this file.

11 If the operation completes successfully, the associated

12 attributes will be updated.

13 The associated attributes are: cir, pir, srv, rp, and id.

15 Supported operations:

17 * add: Creates a new SLA with the provided inputs from user.

18 * Inputs: cir, pir, srv, and rp

19 * Output: id

21 * get: Returns the configuration of the specified SLA in id attribute

22 * Inputs: id

23 * Outputs: cir, pir, srv, and rp

25 * update: Updates the SLA with new values set in the following attributes

26 * Inputs: id, cir, and pir

28 * rm: Removes the specified SLA in the id attribute.

29 * Inputs: id

31 * rm_all: Removes all the configured SLAs.

32 * Inputs: None

34 This attribute is only available for qat_4xxx and qat_6xxx devices.

36 What: /sys/bus/pci/devices/<BDF>/qat_rl/rp

37 Date: January 2024

38 KernelVersion: 6.7

39 Contact: [email protected]

40 Description:

41 (RW) When read, reports the current assigned ring pairs for the

42 queried SLA.

43 When wrote to, configures the ring pairs associated to a new SLA.

45 The value is a 64-bit bit mask and is written/displayed in hex.

46 Each bit of this mask represents a single ring pair i.e.,

47 bit 1 == ring pair id 0; bit 3 == ring pair id 2.

49 Selected ring pairs must to be assigned to a single service,

50 i.e. the one provided with the srv attribute. The service

51 assigned to a certain ring pair can be checked by querying

52 the attribute qat/rp2srv.

54 The maximum number of ring pairs is 4 per SLA.

56 Applicability in sla_op:

58 * WRITE: add operation

59 * READ: get operation

61 Example usage::

63 ## Read

64 # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id

65 # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp

66 0x5

68 ## Write

69 # echo 0x5 > /sys/bus/pci/devices/<BDF>/qat_rl/rp

71 This attribute is only available for qat_4xxx and qat_6xxx devices.

73 What: /sys/bus/pci/devices/<BDF>/qat_rl/id

74 Date: January 2024

75 KernelVersion: 6.7

76 Contact: [email protected]

77 Description:

78 (RW) If written to, the value is used to retrieve a particular

79 SLA and operate on it.

80 This is valid only for the following operations: update, rm,

81 and get.

82 A read of this attribute is only guaranteed to have correct data

83 after creation of an SLA.

85 Applicability in sla_op:

87 * WRITE: rm and update operations

88 * READ: add and get operations

90 Example usage::

92 ## Read

93 ## Set attributes e.g. cir, pir, srv, etc

94 # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

95 # cat /sys/bus/pci/devices/<BDF>/qat_rl/id

96 4

98 ## Write

99 # echo 7 > /sys/bus/pci/devices/<BDF>/qat_rl/id

100 # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

101 # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp

102 0x5 ## ring pair ID 0 and ring pair ID 2

103

104 This attribute is only available for qat_4xxx and qat_6xxx devices.

105

106 What: /sys/bus/pci/devices/<BDF>/qat_rl/cir

107 Date: January 2024

108 KernelVersion: 6.7

109 Contact: [email protected]

110 Description:

111 (RW) Committed information rate (CIR). Rate guaranteed to be

112 achieved by a particular SLA. The value is expressed in

113 permille scale, i.e. 1000 refers to the maximum device

114 throughput for a selected service.

115

116 After sending a "get" to sla_op, this will be populated with the

117 CIR for that queried SLA.

118 Write to this file before sending an "add/update" sla_op, to set

119 the SLA to the specified value.

120

121 Applicability in sla_op:

122

123 * WRITE: add and update operations

124 * READ: get operation

125

126 Example usage::

127

128 ## Write

129 # echo 500 > /sys/bus/pci/devices/<BDF>/qat_rl/cir

130 # echo "add" /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

131

132 ## Read

133 # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id

134 # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

135 # cat /sys/bus/pci/devices/<BDF>/qat_rl/cir

136 500

137

138 This attribute is only available for qat_4xxx and qat_6xxx devices.

139

140 What: /sys/bus/pci/devices/<BDF>/qat_rl/pir

141 Date: January 2024

142 KernelVersion: 6.7

143 Contact: [email protected]

144 Description:

145 (RW) Peak information rate (PIR). The maximum rate that can be

146 achieved by that particular SLA. An SLA can reach a value

147 between CIR and PIR when the device is not fully utilized by

148 requests from other users (assigned to different SLAs).

149

150 After sending a "get" to sla_op, this will be populated with the

151 PIR for that queried SLA.

152 Write to this file before sending an "add/update" sla_op, to set

153 the SLA to the specified value.

154

155 Applicability in sla_op:

156

157 * WRITE: add and update operations

158 * READ: get operation

159

160 Example usage::

161

162 ## Write

163 # echo 750 > /sys/bus/pci/devices/<BDF>/qat_rl/pir

164 # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

165

166 ## Read

167 # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id

168 # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

169 # cat /sys/bus/pci/devices/<BDF>/qat_rl/pir

170 750

171

172 This attribute is only available for qat_4xxx and qat_6xxx devices.

173

174 What: /sys/bus/pci/devices/<BDF>/qat_rl/srv

175 Date: January 2024

176 KernelVersion: 6.7

177 Contact: [email protected]

178 Description:

179 (RW) Service (SRV). Represents the service (sym, asym, dc)

180 associated to an SLA.

181 Can be written to or queried to set/show the SRV type for an SLA.

182 The SRV attribute is used to specify the SRV type before adding

183 an SLA. After an SLA is configured, reports the service

184 associated to that SLA.

185

186 Applicability in sla_op:

187

188 * WRITE: add and update operations

189 * READ: get operation

190

191 Example usage::

192

193 ## Write

194 # echo "dc" > /sys/bus/pci/devices/<BDF>/qat_rl/srv

195 # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

196 # cat /sys/bus/pci/devices/<BDF>/qat_rl/id

197 4

198

199 ## Read

200 # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id

201 # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

202 # cat /sys/bus/pci/devices/<BDF>/qat_rl/srv

203 dc

204

205 This attribute is only available for qat_4xxx and qat_6xxx devices.

206

207 What: /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem

208 Date: January 2024

209 KernelVersion: 6.7

210 Contact: [email protected]

211 Description:

212 (RW) This file will return the remaining capability for a

213 particular service/sla. This is the remaining value that a new

214 SLA can be set to or a current SLA can be increased with.

215

216 Example usage::

217

218 # echo "asym" > /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem

219 # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem

220 250

221 # echo 250 > /sys/bus/pci/devices/<BDF>/qat_rl/cir

222 # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

223 # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem

224 0

225

226 This attribute is only available for qat_4xxx and qat_6xxx devices.

227

3. 한국어 전문 번역

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

SLA operation control

1-35

항목	한국어 전문 번역
What	/sys/bus/pci/devices/<BDF>/qat_rl/sla_op
Date	2024년 1월
KernelVersion	6.7
Contact	[email protected]
Description	SLA에 operation을 수행하는 write-only attribute입니다. 지원 operations는 add, update, rm, rm_all, get입니다. 이 file에 쓰기 전에 이 group의 연계 attribute에 input values를 채워야 하며 operation이 성공하면 연계 attributes가 갱신됩니다. 연계 attributes는 cir, pir, srv, rp, id입니다. add는 cir·pir·srv·rp를 input으로 받아 새 SLA를 만들고 id를 output합니다. get은 id로 지정한 SLA configuration을 조회하여 cir·pir·srv·rp를 output합니다. update는 id·cir·pir로 SLA를 갱신합니다. rm은 id로 지정한 SLA를 제거하고 rm_all은 input 없이 configured SLAs를 모두 제거합니다. 이 attribute는 qat_4xxx와 qat_6xxx devices에서만 사용할 수 있습니다.
Access	Write-only

QAT SLA operations

OperationInputsOutputs / effect

addcir, pir, srv, rpid; create SLA

getidcir, pir, srv, rp

updateid, cir, pirUpdate SLA

rmidRemove selected SLA

rm_allNoneRemove all configured SLAs

각 sla_op command의 input과 output attributes를 구조화했습니다.

SLA ring-pair mask

36-72

항목	한국어 전문 번역
What	/sys/bus/pci/devices/<BDF>/qat_rl/rp
Date	2024년 1월
KernelVersion	6.7
Contact	[email protected]
Description	Read하면 조회한 SLA에 현재 assign된 ring pairs를 보고하고, write하면 새 SLA에 연결할 ring pairs를 구성합니다. 값은 64-bit bit mask이며 hexadecimal로 쓰고 표시합니다. Mask의 각 bit는 ring pair 하나를 나타내므로 bit 1은 ring-pair id 0, bit 3은 ring-pair id 2입니다. 선택한 ring pairs는 srv attribute가 제공한 하나의 service에 모두 assign되어야 합니다. 특정 ring pair의 service는 qat/rp2srv로 확인할 수 있습니다. SLA마다 최대 ring pairs 수는 4개입니다. sla_op에서 write는 add operation, read는 get operation에 적용됩니다. 이 attribute는 qat_4xxx와 qat_6xxx devices에서만 사용할 수 있습니다.
Access	Read-write
Value	64-bit hexadecimal bit mask
Maximum	4 ring pairs per SLA

Ring-pair bit-mask example

Hex maskSet bitsSelected ring-pair IDs

0x5Bits 1 and 30 and 2

Example 0x5가 ring-pair IDs 0과 2를 선택하는 관계입니다.

## Read
# echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
# cat /sys/bus/pci/devices/<BDF>/qat_rl/rp
0x5

## Write
# echo 0x5 > /sys/bus/pci/devices/<BDF>/qat_rl/rp

SLA identifier

73-105

항목	한국어 전문 번역
What	/sys/bus/pci/devices/<BDF>/qat_rl/id
Date	2024년 1월
KernelVersion	6.7
Contact	[email protected]
Description	Write하면 특정 SLA를 retrieve하고 operation 대상에 사용합니다. 이 사용은 update, rm, get operations에서만 valid합니다. 이 attribute를 read한 data는 SLA를 생성한 뒤에만 정확함이 보장됩니다. sla_op에서 write는 rm·update operations, read는 add·get operations에 적용됩니다. 이 attribute는 qat_4xxx와 qat_6xxx devices에서만 사용할 수 있습니다.
Access	Read-write

## Read
## Set attributes e.g. cir, pir, srv, etc
# echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
# cat /sys/bus/pci/devices/<BDF>/qat_rl/id
4

## Write
# echo 7 > /sys/bus/pci/devices/<BDF>/qat_rl/id
# echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
# cat /sys/bus/pci/devices/<BDF>/qat_rl/rp
0x5  ## ring pair ID 0 and ring pair ID 2

Committed information rate

106-139

항목	한국어 전문 번역
What	/sys/bus/pci/devices/<BDF>/qat_rl/cir
Date	2024년 1월
KernelVersion	6.7
Contact	[email protected]
Description	CIR(Committed Information Rate)은 특정 SLA에 달성이 보장되는 rate입니다. 값은 permille scale이며 1000은 선택한 service의 최대 device throughput을 뜻합니다. sla_op에 get을 보낸 뒤에는 조회한 SLA의 CIR로 채워집니다. add/update sla_op 전에 이 file에 써서 SLA의 CIR을 설정합니다. sla_op에서 write는 add·update operations, read는 get operation에 적용됩니다. 이 attribute는 qat_4xxx와 qat_6xxx devices에서만 사용할 수 있습니다.
Access	Read-write
Scale	Permille; 1000 = maximum device throughput

QAT SLA rate fields

AttributeMeaningOperation timing

cirGuaranteed committed rateWrite before add/update; read after get

pirMaximum peak rateWrite before add/update; read after get

cap_remRemaining allocatable capabilityWrite service/SLA selector; read remainder

Guaranteed, peak와 remaining allocation values의 역할을 비교합니다.

## Write
# echo 500 > /sys/bus/pci/devices/<BDF>/qat_rl/cir
# echo "add" /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

## Read
# echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
# echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
# cat /sys/bus/pci/devices/<BDF>/qat_rl/cir
500

Peak information rate

140-173

항목	한국어 전문 번역
What	/sys/bus/pci/devices/<BDF>/qat_rl/pir
Date	2024년 1월
KernelVersion	6.7
Contact	[email protected]
Description	PIR(Peak Information Rate)은 특정 SLA가 달성할 수 있는 maximum rate입니다. 다른 SLAs에 assign된 users의 requests가 device를 완전히 사용하지 않을 때 SLA는 CIR과 PIR 사이의 value에 도달할 수 있습니다. sla_op에 get을 보낸 뒤에는 조회한 SLA의 PIR로 채워집니다. add/update sla_op 전에 이 file에 써서 SLA의 PIR을 설정합니다. sla_op에서 write는 add·update operations, read는 get operation에 적용됩니다. 이 attribute는 qat_4xxx와 qat_6xxx devices에서만 사용할 수 있습니다.
Access	Read-write

## Write
# echo 750 > /sys/bus/pci/devices/<BDF>/qat_rl/pir
# echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op

## Read
# echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
# echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
# cat /sys/bus/pci/devices/<BDF>/qat_rl/pir
750

SLA service

174-206

항목	한국어 전문 번역
What	/sys/bus/pci/devices/<BDF>/qat_rl/srv
Date	2024년 1월
KernelVersion	6.7
Contact	[email protected]
Description	SRV(Service)는 SLA와 연결된 service(sym, asym, dc)를 나타냅니다. SLA의 SRV type을 설정하거나 표시하기 위해 쓰거나 조회할 수 있습니다. SLA를 add하기 전에 SRV type을 지정하며, SLA가 configured된 뒤에는 해당 SLA의 service를 보고합니다. sla_op에서 write는 add·update operations, read는 get operation에 적용됩니다. 이 attribute는 qat_4xxx와 qat_6xxx devices에서만 사용할 수 있습니다.
Access	Read-write
Values	sym, asym, dc

QAT SLA configuration workflow

Set srv and rp for the target service and ring pairsSet cir and pir rate valuesWrite add to sla_opRead generated idWrite id and get to retrieve cir, pir, srv and rp

연계 attributes를 채운 뒤 sla_op를 실행하고 결과 fields를 읽는 순서입니다.

## Write
# echo "dc" > /sys/bus/pci/devices/<BDF>/qat_rl/srv
# echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
# cat /sys/bus/pci/devices/<BDF>/qat_rl/id
4

## Read
# echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
# echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
# cat /sys/bus/pci/devices/<BDF>/qat_rl/srv
dc

Remaining SLA capability

207-226

항목	한국어 전문 번역
What	/sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
Date	2024년 1월
KernelVersion	6.7
Contact	[email protected]
Description	특정 service/SLA의 remaining capability를 반환합니다. 새 SLA에 설정하거나 현재 SLA를 늘리는 데 사용할 수 있는 remaining value입니다. Example에서는 asym의 remaining capability 250을 CIR로 새 SLA에 배정한 뒤 remaining value가 0이 됩니다. 이 attribute는 qat_4xxx와 qat_6xxx devices에서만 사용할 수 있습니다.
Access	Read-write

# echo "asym" > /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
# cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
250
# echo 250 > /sys/bus/pci/devices/<BDF>/qat_rl/cir
# echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
# cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
0