summaryrefslogtreecommitdiffstats
path: root/Documentation/admin-guide
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+samsung@kernel.org>2019-06-18 10:47:10 -0400
committerMauro Carvalho Chehab <mchehab+samsung@kernel.org>2019-07-15 10:03:01 -0400
commite7751617dd0599ceadf4221cb08e04307b00aa1f (patch)
tree16b7a5858f6b4c641e3346e2438f83df49ababa7 /Documentation/admin-guide
parent330d48105245abfb8c9ca491dc53ea500657217a (diff)
docs: blockdev: add it to the admin-guide
The blockdev book basically contains user-faced documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Diffstat (limited to 'Documentation/admin-guide')
-rw-r--r--Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg588
-rw-r--r--Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg459
-rw-r--r--Documentation/admin-guide/blockdev/drbd/conn-states-8.dot18
-rw-r--r--Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst42
-rw-r--r--Documentation/admin-guide/blockdev/drbd/disk-states-8.dot16
-rw-r--r--Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot85
-rw-r--r--Documentation/admin-guide/blockdev/drbd/figures.rst28
-rw-r--r--Documentation/admin-guide/blockdev/drbd/index.rst19
-rw-r--r--Documentation/admin-guide/blockdev/drbd/node-states-8.dot13
-rw-r--r--Documentation/admin-guide/blockdev/floppy.rst255
-rw-r--r--Documentation/admin-guide/blockdev/index.rst14
-rw-r--r--Documentation/admin-guide/blockdev/nbd.rst31
-rw-r--r--Documentation/admin-guide/blockdev/paride.rst439
-rw-r--r--Documentation/admin-guide/blockdev/ramdisk.rst177
-rw-r--r--Documentation/admin-guide/blockdev/zram.rst422
-rw-r--r--Documentation/admin-guide/index.rst1
-rw-r--r--Documentation/admin-guide/kernel-parameters.txt18
17 files changed, 2616 insertions, 9 deletions
diff --git a/Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg b/Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg
new file mode 100644
index 000000000000..f87cfa0dc2fb
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg
@@ -0,0 +1,588 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!-- Created with Inkscape (http://www.inkscape.org/) -->
3<svg
4 xmlns:svg="http://www.w3.org/2000/svg"
5 xmlns="http://www.w3.org/2000/svg"
6 version="1.0"
7 width="210mm"
8 height="297mm"
9 viewBox="0 0 21000 29700"
10 id="svg2"
11 style="fill-rule:evenodd">
12 <defs
13 id="defs4" />
14 <g
15 id="Default"
16 style="visibility:visible">
17 <desc
18 id="desc180">Master slide</desc>
19 </g>
20 <path
21 d="M 11999,8601 L 11899,8301 L 12099,8301 L 11999,8601 z"
22 id="path193"
23 style="fill:#008000;visibility:visible" />
24 <path
25 d="M 11999,7801 L 11999,8361"
26 id="path197"
27 style="fill:none;stroke:#008000;visibility:visible" />
28 <path
29 d="M 7999,10401 L 7899,10101 L 8099,10101 L 7999,10401 z"
30 id="path209"
31 style="fill:#008000;visibility:visible" />
32 <path
33 d="M 7999,9601 L 7999,10161"
34 id="path213"
35 style="fill:none;stroke:#008000;visibility:visible" />
36 <path
37 d="M 11999,7801 L 11685,7840 L 11724,7644 L 11999,7801 z"
38 id="path225"
39 style="fill:#008000;visibility:visible" />
40 <path
41 d="M 7999,7001 L 11764,7754"
42 id="path229"
43 style="fill:none;stroke:#008000;visibility:visible" />
44 <g
45 transform="matrix(0.9895258,-0.1443562,0.1443562,0.9895258,-1244.4792,1416.5139)"
46 id="g245"
47 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
48 <text
49 id="text247">
50 <tspan
51 x="9139 9368 9579 9808 9986 10075 10252 10481 10659 10837 10909"
52 y="9284"
53 id="tspan249">RSDataReply</tspan>
54 </text>
55 </g>
56 <path
57 d="M 7999,9601 L 8281,9458 L 8311,9655 L 7999,9601 z"
58 id="path259"
59 style="fill:#008000;visibility:visible" />
60 <path
61 d="M 11999,9001 L 8236,9565"
62 id="path263"
63 style="fill:none;stroke:#008000;visibility:visible" />
64 <g
65 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,1620.9382,-1639.4947)"
66 id="g279"
67 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
68 <text
69 id="text281">
70 <tspan
71 x="8743 8972 9132 9310 9573 9801 10013 10242 10419 10597 10775 10953 11114"
72 y="7023"
73 id="tspan283">CsumRSRequest</tspan>
74 </text>
75 </g>
76 <text
77 id="text297"
78 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
79 <tspan
80 x="4034 4263 4440 4703 4881 5042 5219 5397 5503 5681 5842 6003 6180 6341 6519 6625 6803 6980 7158 7336 7497 7586 7692"
81 y="5707"
82 id="tspan299">w_make_resync_request()</tspan>
83 </text>
84 <text
85 id="text313"
86 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
87 <tspan
88 x="12199 12305 12483 12644 12821 12893 13054 13232 13410 13638 13816 13905 14083 14311 14489 14667 14845 15023 15184 15272 15378"
89 y="7806"
90 id="tspan315">receive_DataRequest()</tspan>
91 </text>
92 <text
93 id="text329"
94 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
95 <tspan
96 x="12199 12377 12483 12660 12838 13016 13194 13372 13549 13621 13799 13977 14083 14261 14438 14616 14794 14955 15133 15294 15399"
97 y="8606"
98 id="tspan331">drbd_endio_read_sec()</tspan>
99 </text>
100 <text
101 id="text345"
102 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
103 <tspan
104 x="12191 12420 12597 12775 12953 13131 13309 13486 13664 13825 13986 14164 14426 14604 14710 14871 15049 15154 15332 15510 15616"
105 y="9007"
106 id="tspan347">w_e_end_csum_rs_req()</tspan>
107 </text>
108 <text
109 id="text361"
110 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
111 <tspan
112 x="4444 4550 4728 4889 5066 5138 5299 5477 5655 5883 6095 6324 6501 6590 6768 6997 7175 7352 7424 7585 7691"
113 y="9507"
114 id="tspan363">receive_RSDataReply()</tspan>
115 </text>
116 <text
117 id="text377"
118 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
119 <tspan
120 x="4457 4635 4741 4918 5096 5274 5452 5630 5807 5879 6057 6235 6464 6569 6641 6730 6908 7086 7247 7425 7585 7691"
121 y="10407"
122 id="tspan379">drbd_endio_write_sec()</tspan>
123 </text>
124 <text
125 id="text393"
126 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
127 <tspan
128 x="4647 4825 5003 5180 5358 5536 5714 5820 5997 6158 6319 6497 6658 6836 7013 7085 7263 7424 7585 7691"
129 y="10907"
130 id="tspan395">e_end_resync_block()</tspan>
131 </text>
132 <path
133 d="M 11999,11601 L 11685,11640 L 11724,11444 L 11999,11601 z"
134 id="path405"
135 style="fill:#000080;visibility:visible" />
136 <path
137 d="M 7999,10801 L 11764,11554"
138 id="path409"
139 style="fill:none;stroke:#000080;visibility:visible" />
140 <g
141 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,2434.7562,-1674.649)"
142 id="g425"
143 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
144 <text
145 id="text427">
146 <tspan
147 x="9320 9621 9726 9798 9887 10065 10277 10438"
148 y="10943"
149 id="tspan429">WriteAck</tspan>
150 </text>
151 </g>
152 <text
153 id="text443"
154 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
155 <tspan
156 x="12199 12377 12555 12644 12821 13033 13105 13283 13444 13604 13816 13977 14138 14244"
157 y="11559"
158 id="tspan445">got_BlockAck()</tspan>
159 </text>
160 <text
161 id="text459"
162 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
163 <tspan
164 x="7999 8304 8541 8778 8990 9201 9413 9650 10001 10120 10357 10594 10806 11043 11280 11398 11703 11940 12152 12364 12601 12812 12931 13049 13261 13498 13710 13947 14065 14302 14540 14658 14777 14870 15107 15225 15437 15649 15886"
165 y="4877"
166 id="tspan461">Checksum based Resync, case not in sync</tspan>
167 </text>
168 <text
169 id="text475"
170 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
171 <tspan
172 x="6961 7266 7571 7854 8159 8299 8536 8654 8891 9010 9247 9484 9603 9840 9958 10077 10170 10407"
173 y="2806"
174 id="tspan477">DRBD-8.3 data flow</tspan>
175 </text>
176 <text
177 id="text491"
178 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
179 <tspan
180 x="5190 5419 5596 5774 5952 6113 6291 6468 6646 6824 6985 7146 7324 7586 7692"
181 y="7005"
182 id="tspan493">w_e_send_csum()</tspan>
183 </text>
184 <path
185 d="M 11999,17601 L 11899,17301 L 12099,17301 L 11999,17601 z"
186 id="path503"
187 style="fill:#008000;visibility:visible" />
188 <path
189 d="M 11999,16801 L 11999,17361"
190 id="path507"
191 style="fill:none;stroke:#008000;visibility:visible" />
192 <path
193 d="M 11999,16801 L 11685,16840 L 11724,16644 L 11999,16801 z"
194 id="path519"
195 style="fill:#008000;visibility:visible" />
196 <path
197 d="M 7999,16001 L 11764,16754"
198 id="path523"
199 style="fill:none;stroke:#008000;visibility:visible" />
200 <g
201 transform="matrix(0.9895258,-0.1443562,0.1443562,0.9895258,-2539.5806,1529.3491)"
202 id="g539"
203 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
204 <text
205 id="text541">
206 <tspan
207 x="9269 9498 9709 9798 9959 10048 10226 10437 10598 10776"
208 y="18265"
209 id="tspan543">RSIsInSync</tspan>
210 </text>
211 </g>
212 <path
213 d="M 7999,18601 L 8281,18458 L 8311,18655 L 7999,18601 z"
214 id="path553"
215 style="fill:#000080;visibility:visible" />
216 <path
217 d="M 11999,18001 L 8236,18565"
218 id="path557"
219 style="fill:none;stroke:#000080;visibility:visible" />
220 <g
221 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,3461.4027,-1449.3012)"
222 id="g573"
223 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
224 <text
225 id="text575">
226 <tspan
227 x="8743 8972 9132 9310 9573 9801 10013 10242 10419 10597 10775 10953 11114"
228 y="16023"
229 id="tspan577">CsumRSRequest</tspan>
230 </text>
231 </g>
232 <text
233 id="text591"
234 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
235 <tspan
236 x="12199 12305 12483 12644 12821 12893 13054 13232 13410 13638 13816 13905 14083 14311 14489 14667 14845 15023 15184 15272 15378"
237 y="16806"
238 id="tspan593">receive_DataRequest()</tspan>
239 </text>
240 <text
241 id="text607"
242 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
243 <tspan
244 x="12199 12377 12483 12660 12838 13016 13194 13372 13549 13621 13799 13977 14083 14261 14438 14616 14794 14955 15133 15294 15399"
245 y="17606"
246 id="tspan609">drbd_endio_read_sec()</tspan>
247 </text>
248 <text
249 id="text623"
250 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
251 <tspan
252 x="12191 12420 12597 12775 12953 13131 13309 13486 13664 13825 13986 14164 14426 14604 14710 14871 15049 15154 15332 15510 15616"
253 y="18007"
254 id="tspan625">w_e_end_csum_rs_req()</tspan>
255 </text>
256 <text
257 id="text639"
258 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
259 <tspan
260 x="5735 5913 6091 6180 6357 6446 6607 6696 6874 7085 7246 7424 7585 7691"
261 y="18507"
262 id="tspan641">got_IsInSync()</tspan>
263 </text>
264 <text
265 id="text655"
266 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
267 <tspan
268 x="7999 8304 8541 8778 8990 9201 9413 9650 10001 10120 10357 10594 10806 11043 11280 11398 11703 11940 12152 12364 12601 12812 12931 13049 13261 13498 13710 13947 14065 14159 14396 14514 14726 14937 15175"
269 y="13877"
270 id="tspan657">Checksum based Resync, case in sync</tspan>
271 </text>
272 <path
273 d="M 12000,24601 L 11900,24301 L 12100,24301 L 12000,24601 z"
274 id="path667"
275 style="fill:#008000;visibility:visible" />
276 <path
277 d="M 12000,23801 L 12000,24361"
278 id="path671"
279 style="fill:none;stroke:#008000;visibility:visible" />
280 <path
281 d="M 8000,26401 L 7900,26101 L 8100,26101 L 8000,26401 z"
282 id="path683"
283 style="fill:#008000;visibility:visible" />
284 <path
285 d="M 8000,25601 L 8000,26161"
286 id="path687"
287 style="fill:none;stroke:#008000;visibility:visible" />
288 <path
289 d="M 12000,23801 L 11686,23840 L 11725,23644 L 12000,23801 z"
290 id="path699"
291 style="fill:#008000;visibility:visible" />
292 <path
293 d="M 8000,23001 L 11765,23754"
294 id="path703"
295 style="fill:none;stroke:#008000;visibility:visible" />
296 <g
297 transform="matrix(0.9895258,-0.1443562,0.1443562,0.9895258,-3543.8452,1630.5143)"
298 id="g719"
299 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
300 <text
301 id="text721">
302 <tspan
303 x="9464 9710 9921 10150 10328 10505 10577"
304 y="25236"
305 id="tspan723">OVReply</tspan>
306 </text>
307 </g>
308 <path
309 d="M 8000,25601 L 8282,25458 L 8312,25655 L 8000,25601 z"
310 id="path733"
311 style="fill:#008000;visibility:visible" />
312 <path
313 d="M 12000,25001 L 8237,25565"
314 id="path737"
315 style="fill:none;stroke:#008000;visibility:visible" />
316 <g
317 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,4918.2801,-1381.2128)"
318 id="g753"
319 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
320 <text
321 id="text755">
322 <tspan
323 x="9142 9388 9599 9828 10006 10183 10361 10539 10700"
324 y="23106"
325 id="tspan757">OVRequest</tspan>
326 </text>
327 </g>
328 <text
329 id="text771"
330 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
331 <tspan
332 x="12200 12306 12484 12645 12822 12894 13055 13233 13411 13656 13868 14097 14274 14452 14630 14808 14969 15058 15163"
333 y="23806"
334 id="tspan773">receive_OVRequest()</tspan>
335 </text>
336 <text
337 id="text787"
338 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
339 <tspan
340 x="12200 12378 12484 12661 12839 13017 13195 13373 13550 13622 13800 13978 14084 14262 14439 14617 14795 14956 15134 15295 15400"
341 y="24606"
342 id="tspan789">drbd_endio_read_sec()</tspan>
343 </text>
344 <text
345 id="text803"
346 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
347 <tspan
348 x="12192 12421 12598 12776 12954 13132 13310 13487 13665 13843 14004 14182 14288 14465 14643 14749"
349 y="25007"
350 id="tspan805">w_e_end_ov_req()</tspan>
351 </text>
352 <text
353 id="text819"
354 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
355 <tspan
356 x="5101 5207 5385 5546 5723 5795 5956 6134 6312 6557 6769 6998 7175 7353 7425 7586 7692"
357 y="25507"
358 id="tspan821">receive_OVReply()</tspan>
359 </text>
360 <text
361 id="text835"
362 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
363 <tspan
364 x="4492 4670 4776 4953 5131 5309 5487 5665 5842 5914 6092 6270 6376 6554 6731 6909 7087 7248 7426 7587 7692"
365 y="26407"
366 id="tspan837">drbd_endio_read_sec()</tspan>
367 </text>
368 <text
369 id="text851"
370 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
371 <tspan
372 x="4902 5131 5308 5486 5664 5842 6020 6197 6375 6553 6714 6892 6998 7175 7353 7425 7586 7692"
373 y="26907"
374 id="tspan853">w_e_end_ov_reply()</tspan>
375 </text>
376 <path
377 d="M 12000,27601 L 11686,27640 L 11725,27444 L 12000,27601 z"
378 id="path863"
379 style="fill:#000080;visibility:visible" />
380 <path
381 d="M 8000,26801 L 11765,27554"
382 id="path867"
383 style="fill:none;stroke:#000080;visibility:visible" />
384 <g
385 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,5704.1907,-1328.312)"
386 id="g883"
387 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
388 <text
389 id="text885">
390 <tspan
391 x="9279 9525 9736 9965 10143 10303 10481 10553"
392 y="26935"
393 id="tspan887">OVResult</tspan>
394 </text>
395 </g>
396 <text
397 id="text901"
398 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
399 <tspan
400 x="12200 12378 12556 12645 12822 13068 13280 13508 13686 13847 14025 14097 14185 14291"
401 y="27559"
402 id="tspan903">got_OVResult()</tspan>
403 </text>
404 <text
405 id="text917"
406 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
407 <tspan
408 x="8000 8330 8567 8660 8754 8991 9228 9346 9558 9795 9935 10028 10146"
409 y="21877"
410 id="tspan919">Online verify</tspan>
411 </text>
412 <text
413 id="text933"
414 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
415 <tspan
416 x="4641 4870 5047 5310 5488 5649 5826 6004 6182 6343 6521 6626 6804 6982 7160 7338 7499 7587 7693"
417 y="23005"
418 id="tspan935">w_make_ov_request()</tspan>
419 </text>
420 <path
421 d="M 8000,6500 L 7900,6200 L 8100,6200 L 8000,6500 z"
422 id="path945"
423 style="fill:#008000;visibility:visible" />
424 <path
425 d="M 8000,5700 L 8000,6260"
426 id="path949"
427 style="fill:none;stroke:#008000;visibility:visible" />
428 <path
429 d="M 3900,5500 L 3700,5500 L 3700,11000 L 3900,11000"
430 id="path961"
431 style="fill:none;stroke:#000000;visibility:visible" />
432 <path
433 d="M 3900,14500 L 3700,14500 L 3700,18600 L 3900,18600"
434 id="path973"
435 style="fill:none;stroke:#000000;visibility:visible" />
436 <path
437 d="M 3900,22800 L 3700,22800 L 3700,26900 L 3900,26900"
438 id="path985"
439 style="fill:none;stroke:#000000;visibility:visible" />
440 <text
441 id="text1001"
442 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
443 <tspan
444 x="4492 4670 4776 4953 5131 5309 5487 5665 5842 5914 6092 6270 6376 6554 6731 6909 7087 7248 7426 7587 7692"
445 y="6506"
446 id="tspan1003">drbd_endio_read_sec()</tspan>
447 </text>
448 <text
449 id="text1017"
450 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
451 <tspan
452 x="4034 4263 4440 4703 4881 5042 5219 5397 5503 5681 5842 6003 6180 6341 6519 6625 6803 6980 7158 7336 7497 7586 7692"
453 y="14708"
454 id="tspan1019">w_make_resync_request()</tspan>
455 </text>
456 <text
457 id="text1033"
458 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
459 <tspan
460 x="5190 5419 5596 5774 5952 6113 6291 6468 6646 6824 6985 7146 7324 7586 7692"
461 y="16006"
462 id="tspan1035">w_e_send_csum()</tspan>
463 </text>
464 <path
465 d="M 8000,15501 L 7900,15201 L 8100,15201 L 8000,15501 z"
466 id="path1045"
467 style="fill:#008000;visibility:visible" />
468 <path
469 d="M 8000,14701 L 8000,15261"
470 id="path1049"
471 style="fill:none;stroke:#008000;visibility:visible" />
472 <text
473 id="text1065"
474 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
475 <tspan
476 x="4492 4670 4776 4953 5131 5309 5487 5665 5842 5914 6092 6270 6376 6554 6731 6909 7087 7248 7426 7587 7692"
477 y="15507"
478 id="tspan1067">drbd_endio_read_sec()</tspan>
479 </text>
480 <path
481 d="M 16100,9000 L 16300,9000 L 16300,7500 L 16100,7500"
482 id="path1077"
483 style="fill:none;stroke:#000000;visibility:visible" />
484 <path
485 d="M 16100,18000 L 16300,18000 L 16300,16500 L 16100,16500"
486 id="path1089"
487 style="fill:none;stroke:#000000;visibility:visible" />
488 <path
489 d="M 16100,25000 L 16300,25000 L 16300,23500 L 16100,23500"
490 id="path1101"
491 style="fill:none;stroke:#000000;visibility:visible" />
492 <text
493 id="text1117"
494 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
495 <tspan
496 x="2026 2132 2293 2471 2648 2826 3004 3076 3254 3431 3503 3681 3787"
497 y="5402"
498 id="tspan1119">rs_begin_io()</tspan>
499 </text>
500 <text
501 id="text1133"
502 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
503 <tspan
504 x="2027 2133 2294 2472 2649 2827 3005 3077 3255 3432 3504 3682 3788"
505 y="14402"
506 id="tspan1135">rs_begin_io()</tspan>
507 </text>
508 <text
509 id="text1149"
510 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
511 <tspan
512 x="2026 2132 2293 2471 2648 2826 3004 3076 3254 3431 3503 3681 3787"
513 y="22602"
514 id="tspan1151">rs_begin_io()</tspan>
515 </text>
516 <text
517 id="text1165"
518 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
519 <tspan
520 x="1426 1532 1693 1871 2031 2209 2472 2649 2721 2899 2988 3166 3344 3416 3593 3699"
521 y="11302"
522 id="tspan1167">rs_complete_io()</tspan>
523 </text>
524 <text
525 id="text1181"
526 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
527 <tspan
528 x="1526 1632 1793 1971 2131 2309 2572 2749 2821 2999 3088 3266 3444 3516 3693 3799"
529 y="18931"
530 id="tspan1183">rs_complete_io()</tspan>
531 </text>
532 <text
533 id="text1197"
534 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
535 <tspan
536 x="1526 1632 1793 1971 2131 2309 2572 2749 2821 2999 3088 3266 3444 3516 3693 3799"
537 y="27231"
538 id="tspan1199">rs_complete_io()</tspan>
539 </text>
540 <text
541 id="text1213"
542 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
543 <tspan
544 x="16126 16232 16393 16571 16748 16926 17104 17176 17354 17531 17603 17781 17887"
545 y="7402"
546 id="tspan1215">rs_begin_io()</tspan>
547 </text>
548 <text
549 id="text1229"
550 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
551 <tspan
552 x="16127 16233 16394 16572 16749 16927 17105 17177 17355 17532 17604 17782 17888"
553 y="16331"
554 id="tspan1231">rs_begin_io()</tspan>
555 </text>
556 <text
557 id="text1245"
558 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
559 <tspan
560 x="16127 16233 16394 16572 16749 16927 17105 17177 17355 17532 17604 17782 17888"
561 y="23302"
562 id="tspan1247">rs_begin_io()</tspan>
563 </text>
564 <text
565 id="text1261"
566 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
567 <tspan
568 x="16115 16221 16382 16560 16720 16898 17161 17338 17410 17588 17677 17855 18033 18105 18282 18388"
569 y="9302"
570 id="tspan1263">rs_complete_io()</tspan>
571 </text>
572 <text
573 id="text1277"
574 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
575 <tspan
576 x="16115 16221 16382 16560 16720 16898 17161 17338 17410 17588 17677 17855 18033 18105 18282 18388"
577 y="18331"
578 id="tspan1279">rs_complete_io()</tspan>
579 </text>
580 <text
581 id="text1293"
582 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
583 <tspan
584 x="16126 16232 16393 16571 16731 16909 17172 17349 17421 17599 17688 17866 18044 18116 18293 18399"
585 y="25302"
586 id="tspan1295">rs_complete_io()</tspan>
587 </text>
588</svg>
diff --git a/Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg b/Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg
new file mode 100644
index 000000000000..48a1e2165fec
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg
@@ -0,0 +1,459 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!-- Created with Inkscape (http://www.inkscape.org/) -->
3<svg
4 xmlns:svg="http://www.w3.org/2000/svg"
5 xmlns="http://www.w3.org/2000/svg"
6 version="1.0"
7 width="210mm"
8 height="297mm"
9 viewBox="0 0 21000 29700"
10 id="svg2"
11 style="fill-rule:evenodd">
12 <defs
13 id="defs4" />
14 <g
15 id="Default"
16 style="visibility:visible">
17 <desc
18 id="desc176">Master slide</desc>
19 </g>
20 <path
21 d="M 11999,19601 L 11899,19301 L 12099,19301 L 11999,19601 z"
22 id="path189"
23 style="fill:#008000;visibility:visible" />
24 <path
25 d="M 11999,18801 L 11999,19361"
26 id="path193"
27 style="fill:none;stroke:#008000;visibility:visible" />
28 <path
29 d="M 7999,21401 L 7899,21101 L 8099,21101 L 7999,21401 z"
30 id="path205"
31 style="fill:#008000;visibility:visible" />
32 <path
33 d="M 7999,20601 L 7999,21161"
34 id="path209"
35 style="fill:none;stroke:#008000;visibility:visible" />
36 <path
37 d="M 11999,18801 L 11685,18840 L 11724,18644 L 11999,18801 z"
38 id="path221"
39 style="fill:#008000;visibility:visible" />
40 <path
41 d="M 7999,18001 L 11764,18754"
42 id="path225"
43 style="fill:none;stroke:#008000;visibility:visible" />
44 <text
45 x="-3023.845"
46 y="1106.8124"
47 transform="matrix(0.9895258,-0.1443562,0.1443562,0.9895258,0,0)"
48 id="text243"
49 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
50 <tspan
51 x="6115.1553 6344.1553 6555.1553 6784.1553 6962.1553 7051.1553 7228.1553 7457.1553 7635.1553 7813.1553 7885.1553"
52 y="21390.812"
53 id="tspan245">RSDataReply</tspan>
54 </text>
55 <path
56 d="M 7999,20601 L 8281,20458 L 8311,20655 L 7999,20601 z"
57 id="path255"
58 style="fill:#008000;visibility:visible" />
59 <path
60 d="M 11999,20001 L 8236,20565"
61 id="path259"
62 style="fill:none;stroke:#008000;visibility:visible" />
63 <text
64 x="3502.5356"
65 y="-2184.6621"
66 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,0,0)"
67 id="text277"
68 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
69 <tspan
70 x="12321.536 12550.536 12761.536 12990.536 13168.536 13257.536 13434.536 13663.536 13841.536 14019.536 14196.536 14374.536 14535.536"
71 y="15854.338"
72 id="tspan279">RSDataRequest</tspan>
73 </text>
74 <text
75 id="text293"
76 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
77 <tspan
78 x="4034 4263 4440 4703 4881 5042 5219 5397 5503 5681 5842 6003 6180 6341 6519 6625 6803 6980 7158 7336 7497 7586 7692"
79 y="17807"
80 id="tspan295">w_make_resync_request()</tspan>
81 </text>
82 <text
83 id="text309"
84 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
85 <tspan
86 x="12199 12305 12483 12644 12821 12893 13054 13232 13410 13638 13816 13905 14083 14311 14489 14667 14845 15023 15184 15272 15378"
87 y="18806"
88 id="tspan311">receive_DataRequest()</tspan>
89 </text>
90 <text
91 id="text325"
92 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
93 <tspan
94 x="12199 12377 12483 12660 12838 13016 13194 13372 13549 13621 13799 13977 14083 14261 14438 14616 14794 14955 15133 15294 15399"
95 y="19606"
96 id="tspan327">drbd_endio_read_sec()</tspan>
97 </text>
98 <text
99 id="text341"
100 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
101 <tspan
102 x="12191 12420 12597 12775 12953 13131 13309 13486 13664 13770 13931 14109 14287 14375 14553 14731 14837 15015 15192 15298"
103 y="20007"
104 id="tspan343">w_e_end_rsdata_req()</tspan>
105 </text>
106 <text
107 id="text357"
108 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
109 <tspan
110 x="4444 4550 4728 4889 5066 5138 5299 5477 5655 5883 6095 6324 6501 6590 6768 6997 7175 7352 7424 7585 7691"
111 y="20507"
112 id="tspan359">receive_RSDataReply()</tspan>
113 </text>
114 <text
115 id="text373"
116 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
117 <tspan
118 x="4457 4635 4741 4918 5096 5274 5452 5630 5807 5879 6057 6235 6464 6569 6641 6730 6908 7086 7247 7425 7585 7691"
119 y="21407"
120 id="tspan375">drbd_endio_write_sec()</tspan>
121 </text>
122 <text
123 id="text389"
124 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
125 <tspan
126 x="4647 4825 5003 5180 5358 5536 5714 5820 5997 6158 6319 6497 6658 6836 7013 7085 7263 7424 7585 7691"
127 y="21907"
128 id="tspan391">e_end_resync_block()</tspan>
129 </text>
130 <path
131 d="M 11999,22601 L 11685,22640 L 11724,22444 L 11999,22601 z"
132 id="path401"
133 style="fill:#000080;visibility:visible" />
134 <path
135 d="M 7999,21801 L 11764,22554"
136 id="path405"
137 style="fill:none;stroke:#000080;visibility:visible" />
138 <text
139 x="4290.3008"
140 y="-2369.6162"
141 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,0,0)"
142 id="text423"
143 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
144 <tspan
145 x="13610.301 13911.301 14016.301 14088.301 14177.301 14355.301 14567.301 14728.301"
146 y="19573.385"
147 id="tspan425">WriteAck</tspan>
148 </text>
149 <text
150 id="text439"
151 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
152 <tspan
153 x="12199 12377 12555 12644 12821 13033 13105 13283 13444 13604 13816 13977 14138 14244"
154 y="22559"
155 id="tspan441">got_BlockAck()</tspan>
156 </text>
157 <text
158 id="text455"
159 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
160 <tspan
161 x="7999 8304 8541 8753 8964 9201 9413 9531 9769 9862 10099 10310 10522 10734 10852 10971 11208 11348 11585 11822"
162 y="16877"
163 id="tspan457">Resync blocks, 4-32K</tspan>
164 </text>
165 <path
166 d="M 12000,7601 L 11900,7301 L 12100,7301 L 12000,7601 z"
167 id="path467"
168 style="fill:#008000;visibility:visible" />
169 <path
170 d="M 12000,6801 L 12000,7361"
171 id="path471"
172 style="fill:none;stroke:#008000;visibility:visible" />
173 <path
174 d="M 12000,6801 L 11686,6840 L 11725,6644 L 12000,6801 z"
175 id="path483"
176 style="fill:#008000;visibility:visible" />
177 <path
178 d="M 8000,6001 L 11765,6754"
179 id="path487"
180 style="fill:none;stroke:#008000;visibility:visible" />
181 <text
182 x="-1288.1796"
183 y="1279.7666"
184 transform="matrix(0.9895258,-0.1443562,0.1443562,0.9895258,0,0)"
185 id="text505"
186 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
187 <tspan
188 x="8174.8208 8475.8203 8580.8203 8652.8203 8741.8203 8919.8203 9131.8203 9292.8203"
189 y="9516.7666"
190 id="tspan507">WriteAck</tspan>
191 </text>
192 <path
193 d="M 8000,8601 L 8282,8458 L 8312,8655 L 8000,8601 z"
194 id="path517"
195 style="fill:#000080;visibility:visible" />
196 <path
197 d="M 12000,8001 L 8237,8565"
198 id="path521"
199 style="fill:none;stroke:#000080;visibility:visible" />
200 <text
201 x="1065.6655"
202 y="-2097.7664"
203 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,0,0)"
204 id="text539"
205 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
206 <tspan
207 x="10682.666 10911.666 11088.666 11177.666"
208 y="4107.2339"
209 id="tspan541">Data</tspan>
210 </text>
211 <text
212 id="text555"
213 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
214 <tspan
215 x="4746 4924 5030 5207 5385 5563 5826 6003 6164 6342 6520 6626 6803 6981 7159 7337 7498 7587 7692"
216 y="5505"
217 id="tspan557">drbd_make_request()</tspan>
218 </text>
219 <text
220 id="text571"
221 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
222 <tspan
223 x="12200 12306 12484 12645 12822 12894 13055 13233 13411 13639 13817 13906 14084 14190"
224 y="6806"
225 id="tspan573">receive_Data()</tspan>
226 </text>
227 <text
228 id="text587"
229 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
230 <tspan
231 x="12200 12378 12484 12661 12839 13017 13195 13373 13550 13622 13800 13978 14207 14312 14384 14473 14651 14829 14990 15168 15328 15434"
232 y="7606"
233 id="tspan589">drbd_endio_write_sec()</tspan>
234 </text>
235 <text
236 id="text603"
237 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
238 <tspan
239 x="12192 12370 12548 12725 12903 13081 13259 13437 13509 13686 13847 14008 14114"
240 y="8007"
241 id="tspan605">e_end_block()</tspan>
242 </text>
243 <text
244 id="text619"
245 style="font-size:318px;font-weight:400;fill:#000080;visibility:visible;font-family:Helvetica embedded">
246 <tspan
247 x="5647 5825 6003 6092 6269 6481 6553 6731 6892 7052 7264 7425 7586 7692"
248 y="8606"
249 id="tspan621">got_BlockAck()</tspan>
250 </text>
251 <text
252 id="text635"
253 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
254 <tspan
255 x="8000 8305 8542 8779 9016 9109 9346 9486 9604 9956 10049 10189 10328 10565 10705 10942 11179 11298 11603 11742 11835 11954 12191 12310 12428 12665 12902 13139 13279 13516 13753"
256 y="4877"
257 id="tspan637">Regular mirrored write, 512-32K</tspan>
258 </text>
259 <text
260 id="text651"
261 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
262 <tspan
263 x="5381 5610 5787 5948 6126 6304 6482 6659 6837 7015 7087 7265 7426 7587 7692"
264 y="6003"
265 id="tspan653">w_send_dblock()</tspan>
266 </text>
267 <path
268 d="M 8000,6800 L 7900,6500 L 8100,6500 L 8000,6800 z"
269 id="path663"
270 style="fill:#008000;visibility:visible" />
271 <path
272 d="M 8000,6000 L 8000,6560"
273 id="path667"
274 style="fill:none;stroke:#008000;visibility:visible" />
275 <text
276 id="text683"
277 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
278 <tspan
279 x="4602 4780 4886 5063 5241 5419 5597 5775 5952 6024 6202 6380 6609 6714 6786 6875 7053 7231 7409 7515 7587 7692"
280 y="6905"
281 id="tspan685">drbd_endio_write_pri()</tspan>
282 </text>
283 <path
284 d="M 12000,13602 L 11900,13302 L 12100,13302 L 12000,13602 z"
285 id="path695"
286 style="fill:#008000;visibility:visible" />
287 <path
288 d="M 12000,12802 L 12000,13362"
289 id="path699"
290 style="fill:none;stroke:#008000;visibility:visible" />
291 <path
292 d="M 12000,12802 L 11686,12841 L 11725,12645 L 12000,12802 z"
293 id="path711"
294 style="fill:#008000;visibility:visible" />
295 <path
296 d="M 8000,12002 L 11765,12755"
297 id="path715"
298 style="fill:none;stroke:#008000;visibility:visible" />
299 <text
300 x="-2155.5266"
301 y="1201.5964"
302 transform="matrix(0.9895258,-0.1443562,0.1443562,0.9895258,0,0)"
303 id="text733"
304 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
305 <tspan
306 x="7202.4736 7431.4736 7608.4736 7697.4736 7875.4736 8104.4736 8282.4736 8459.4736 8531.4736"
307 y="15454.597"
308 id="tspan735">DataReply</tspan>
309 </text>
310 <path
311 d="M 8000,14602 L 8282,14459 L 8312,14656 L 8000,14602 z"
312 id="path745"
313 style="fill:#008000;visibility:visible" />
314 <path
315 d="M 12000,14002 L 8237,14566"
316 id="path749"
317 style="fill:none;stroke:#008000;visibility:visible" />
318 <text
319 x="2280.3804"
320 y="-2103.2141"
321 transform="matrix(0.9788674,0.2044961,-0.2044961,0.9788674,0,0)"
322 id="text767"
323 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
324 <tspan
325 x="11316.381 11545.381 11722.381 11811.381 11989.381 12218.381 12396.381 12573.381 12751.381 12929.381 13090.381"
326 y="9981.7861"
327 id="tspan769">DataRequest</tspan>
328 </text>
329 <text
330 id="text783"
331 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
332 <tspan
333 x="4746 4924 5030 5207 5385 5563 5826 6003 6164 6342 6520 6626 6803 6981 7159 7337 7498 7587 7692"
334 y="11506"
335 id="tspan785">drbd_make_request()</tspan>
336 </text>
337 <text
338 id="text799"
339 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
340 <tspan
341 x="12200 12306 12484 12645 12822 12894 13055 13233 13411 13639 13817 13906 14084 14312 14490 14668 14846 15024 15185 15273 15379"
342 y="12807"
343 id="tspan801">receive_DataRequest()</tspan>
344 </text>
345 <text
346 id="text815"
347 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
348 <tspan
349 x="12200 12378 12484 12661 12839 13017 13195 13373 13550 13622 13800 13978 14084 14262 14439 14617 14795 14956 15134 15295 15400"
350 y="13607"
351 id="tspan817">drbd_endio_read_sec()</tspan>
352 </text>
353 <text
354 id="text831"
355 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
356 <tspan
357 x="12192 12421 12598 12776 12954 13132 13310 13487 13665 13843 14021 14110 14288 14465 14571 14749 14927 15033"
358 y="14008"
359 id="tspan833">w_e_end_data_req()</tspan>
360 </text>
361 <g
362 id="g835"
363 style="visibility:visible">
364 <desc
365 id="desc837">Drawing</desc>
366 <text
367 id="text847"
368 style="font-size:318px;font-weight:400;fill:#008000;font-family:Helvetica embedded">
369 <tspan
370 x="4885 4991 5169 5330 5507 5579 5740 5918 6096 6324 6502 6591 6769 6997 7175 7353 7425 7586 7692"
371 y="14607"
372 id="tspan849">receive_DataReply()</tspan>
373 </text>
374 </g>
375 <text
376 id="text863"
377 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
378 <tspan
379 x="8000 8305 8398 8610 8821 8914 9151 9363 9575 9693 9833 10070 10307 10544 10663 10781 11018 11255 11493 11632 11869 12106"
380 y="10878"
381 id="tspan865">Diskless read, 512-32K</tspan>
382 </text>
383 <text
384 id="text879"
385 style="font-size:318px;font-weight:400;fill:#008000;visibility:visible;font-family:Helvetica embedded">
386 <tspan
387 x="5029 5258 5435 5596 5774 5952 6130 6307 6413 6591 6769 6947 7125 7230 7408 7586 7692"
388 y="12004"
389 id="tspan881">w_send_read_req()</tspan>
390 </text>
391 <text
392 id="text895"
393 style="font-size:423px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
394 <tspan
395 x="6961 7266 7571 7854 8159 8278 8515 8633 8870 9107 9226 9463 9581 9700 9793 10030"
396 y="2806"
397 id="tspan897">DRBD 8 data flow</tspan>
398 </text>
399 <path
400 d="M 3900,5300 L 3700,5300 L 3700,7000 L 3900,7000"
401 id="path907"
402 style="fill:none;stroke:#000000;visibility:visible" />
403 <path
404 d="M 3900,17600 L 3700,17600 L 3700,22000 L 3900,22000"
405 id="path919"
406 style="fill:none;stroke:#000000;visibility:visible" />
407 <path
408 d="M 16100,20000 L 16300,20000 L 16300,18500 L 16100,18500"
409 id="path931"
410 style="fill:none;stroke:#000000;visibility:visible" />
411 <text
412 id="text947"
413 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
414 <tspan
415 x="2126 2304 2376 2554 2731 2909 3087 3159 3337 3515 3587 3764 3870"
416 y="5202"
417 id="tspan949">al_begin_io()</tspan>
418 </text>
419 <text
420 id="text963"
421 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
422 <tspan
423 x="1632 1810 1882 2060 2220 2398 2661 2839 2910 3088 3177 3355 3533 3605 3783 3888"
424 y="7331"
425 id="tspan965">al_complete_io()</tspan>
426 </text>
427 <text
428 id="text979"
429 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
430 <tspan
431 x="2126 2232 2393 2571 2748 2926 3104 3176 3354 3531 3603 3781 3887"
432 y="17431"
433 id="tspan981">rs_begin_io()</tspan>
434 </text>
435 <text
436 id="text995"
437 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
438 <tspan
439 x="1626 1732 1893 2071 2231 2409 2672 2849 2921 3099 3188 3366 3544 3616 3793 3899"
440 y="22331"
441 id="tspan997">rs_complete_io()</tspan>
442 </text>
443 <text
444 id="text1011"
445 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
446 <tspan
447 x="16027 16133 16294 16472 16649 16827 17005 17077 17255 17432 17504 17682 17788"
448 y="18402"
449 id="tspan1013">rs_begin_io()</tspan>
450 </text>
451 <text
452 id="text1027"
453 style="font-size:318px;font-weight:400;fill:#000000;visibility:visible;font-family:Helvetica embedded">
454 <tspan
455 x="16115 16221 16382 16560 16720 16898 17161 17338 17410 17588 17677 17855 18033 18105 18282 18388"
456 y="20331"
457 id="tspan1029">rs_complete_io()</tspan>
458 </text>
459</svg>
diff --git a/Documentation/admin-guide/blockdev/drbd/conn-states-8.dot b/Documentation/admin-guide/blockdev/drbd/conn-states-8.dot
new file mode 100644
index 000000000000..025e8cf5e64a
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/conn-states-8.dot
@@ -0,0 +1,18 @@
1digraph conn_states {
2 StandAllone -> WFConnection [ label = "ioctl_set_net()" ]
3 WFConnection -> Unconnected [ label = "unable to bind()" ]
4 WFConnection -> WFReportParams [ label = "in connect() after accept" ]
5 WFReportParams -> StandAllone [ label = "checks in receive_param()" ]
6 WFReportParams -> Connected [ label = "in receive_param()" ]
7 WFReportParams -> WFBitMapS [ label = "sync_handshake()" ]
8 WFReportParams -> WFBitMapT [ label = "sync_handshake()" ]
9 WFBitMapS -> SyncSource [ label = "receive_bitmap()" ]
10 WFBitMapT -> SyncTarget [ label = "receive_bitmap()" ]
11 SyncSource -> Connected
12 SyncTarget -> Connected
13 SyncSource -> PausedSyncS
14 SyncTarget -> PausedSyncT
15 PausedSyncS -> SyncSource
16 PausedSyncT -> SyncTarget
17 Connected -> WFConnection [ label = "* on network error" ]
18}
diff --git a/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst b/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst
new file mode 100644
index 000000000000..66036b901644
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst
@@ -0,0 +1,42 @@
1================================
2kernel data structure for DRBD-9
3================================
4
5This describes the in kernel data structure for DRBD-9. Starting with
6Linux v3.14 we are reorganizing DRBD to use this data structure.
7
8Basic Data Structure
9====================
10
11A node has a number of DRBD resources. Each such resource has a number of
12devices (aka volumes) and connections to other nodes ("peer nodes"). Each DRBD
13device is represented by a block device locally.
14
15The DRBD objects are interconnected to form a matrix as depicted below; a
16drbd_peer_device object sits at each intersection between a drbd_device and a
17drbd_connection::
18
19 /--------------+---------------+.....+---------------\
20 | resource | device | | device |
21 +--------------+---------------+.....+---------------+
22 | connection | peer_device | | peer_device |
23 +--------------+---------------+.....+---------------+
24 : : : : :
25 : : : : :
26 +--------------+---------------+.....+---------------+
27 | connection | peer_device | | peer_device |
28 \--------------+---------------+.....+---------------/
29
30In this table, horizontally, devices can be accessed from resources by their
31volume number. Likewise, peer_devices can be accessed from connections by
32their volume number. Objects in the vertical direction are connected by double
33linked lists. There are back pointers from peer_devices to their connections a
34devices, and from connections and devices to their resource.
35
36All resources are in the drbd_resources double-linked list. In addition, all
37devices can be accessed by their minor device number via the drbd_devices idr.
38
39The drbd_resource, drbd_connection, and drbd_device objects are reference
40counted. The peer_device objects only serve to establish the links between
41devices and connections; their lifetime is determined by the lifetime of the
42device and connection which they reference.
diff --git a/Documentation/admin-guide/blockdev/drbd/disk-states-8.dot b/Documentation/admin-guide/blockdev/drbd/disk-states-8.dot
new file mode 100644
index 000000000000..d06cfb46fb98
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/disk-states-8.dot
@@ -0,0 +1,16 @@
1digraph disk_states {
2 Diskless -> Inconsistent [ label = "ioctl_set_disk()" ]
3 Diskless -> Consistent [ label = "ioctl_set_disk()" ]
4 Diskless -> Outdated [ label = "ioctl_set_disk()" ]
5 Consistent -> Outdated [ label = "receive_param()" ]
6 Consistent -> UpToDate [ label = "receive_param()" ]
7 Consistent -> Inconsistent [ label = "start resync" ]
8 Outdated -> Inconsistent [ label = "start resync" ]
9 UpToDate -> Inconsistent [ label = "ioctl_replicate" ]
10 Inconsistent -> UpToDate [ label = "resync completed" ]
11 Consistent -> Failed [ label = "io completion error" ]
12 Outdated -> Failed [ label = "io completion error" ]
13 UpToDate -> Failed [ label = "io completion error" ]
14 Inconsistent -> Failed [ label = "io completion error" ]
15 Failed -> Diskless [ label = "sending notify to peer" ]
16}
diff --git a/Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot b/Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot
new file mode 100644
index 000000000000..6d9cf0a7b11d
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot
@@ -0,0 +1,85 @@
1// vim: set sw=2 sts=2 :
2digraph {
3 rankdir=BT
4 bgcolor=white
5
6 node [shape=plaintext]
7 node [fontcolor=black]
8
9 StandAlone [ style=filled,fillcolor=gray,label=StandAlone ]
10
11 node [fontcolor=lightgray]
12
13 Unconnected [ label=Unconnected ]
14
15 CommTrouble [ shape=record,
16 label="{communication loss|{Timeout|BrokenPipe|NetworkFailure}}" ]
17
18 node [fontcolor=gray]
19
20 subgraph cluster_try_connect {
21 label="try to connect, handshake"
22 rank=max
23 WFConnection [ label=WFConnection ]
24 WFReportParams [ label=WFReportParams ]
25 }
26
27 TearDown [ label=TearDown ]
28
29 Connected [ label=Connected,style=filled,fillcolor=green,fontcolor=black ]
30
31 node [fontcolor=lightblue]
32
33 StartingSyncS [ label=StartingSyncS ]
34 StartingSyncT [ label=StartingSyncT ]
35
36 subgraph cluster_bitmap_exchange {
37 node [fontcolor=red]
38 fontcolor=red
39 label="new application (WRITE?) requests blocked\lwhile bitmap is exchanged"
40
41 WFBitMapT [ label=WFBitMapT ]
42 WFSyncUUID [ label=WFSyncUUID ]
43 WFBitMapS [ label=WFBitMapS ]
44 }
45
46 node [fontcolor=blue]
47
48 cluster_resync [ shape=record,label="{<any>resynchronisation process running\l'concurrent' application requests allowed|{{<T>PausedSyncT\nSyncTarget}|{<S>PausedSyncS\nSyncSource}}}" ]
49
50 node [shape=box,fontcolor=black]
51
52 // drbdadm [label="drbdadm connect"]
53 // handshake [label="drbd_connect()\ndrbd_do_handshake\ndrbd_sync_handshake() etc."]
54 // comm_error [label="communication trouble"]
55
56 //
57 // edges
58 // --------------------------------------
59
60 StandAlone -> Unconnected [ label="drbdadm connect" ]
61 Unconnected -> StandAlone [ label="drbdadm disconnect\lor serious communication trouble" ]
62 Unconnected -> WFConnection [ label="receiver thread is started" ]
63 WFConnection -> WFReportParams [ headlabel="accept()\land/or \lconnect()\l" ]
64
65 WFReportParams -> StandAlone [ label="during handshake\lpeers do not agree\labout something essential" ]
66 WFReportParams -> Connected [ label="data identical\lno sync needed",color=green,fontcolor=green ]
67
68 WFReportParams -> WFBitMapS
69 WFReportParams -> WFBitMapT
70 WFBitMapT -> WFSyncUUID [minlen=0.1,constraint=false]
71
72 WFBitMapS -> cluster_resync:S
73 WFSyncUUID -> cluster_resync:T
74
75 edge [color=green]
76 cluster_resync:any -> Connected [ label="resnyc done",fontcolor=green ]
77
78 edge [color=red]
79 WFReportParams -> CommTrouble
80 Connected -> CommTrouble
81 cluster_resync:any -> CommTrouble
82 edge [color=black]
83 CommTrouble -> Unconnected [label="receiver thread is stopped" ]
84
85}
diff --git a/Documentation/admin-guide/blockdev/drbd/figures.rst b/Documentation/admin-guide/blockdev/drbd/figures.rst
new file mode 100644
index 000000000000..3e3fd4b8a478
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/figures.rst
@@ -0,0 +1,28 @@
1.. The here included files are intended to help understand the implementation
2
3Data flows that Relate some functions, and write packets
4========================================================
5
6.. kernel-figure:: DRBD-8.3-data-packets.svg
7 :alt: DRBD-8.3-data-packets.svg
8 :align: center
9
10.. kernel-figure:: DRBD-data-packets.svg
11 :alt: DRBD-data-packets.svg
12 :align: center
13
14
15Sub graphs of DRBD's state transitions
16======================================
17
18.. kernel-figure:: conn-states-8.dot
19 :alt: conn-states-8.dot
20 :align: center
21
22.. kernel-figure:: disk-states-8.dot
23 :alt: disk-states-8.dot
24 :align: center
25
26.. kernel-figure:: node-states-8.dot
27 :alt: node-states-8.dot
28 :align: center
diff --git a/Documentation/admin-guide/blockdev/drbd/index.rst b/Documentation/admin-guide/blockdev/drbd/index.rst
new file mode 100644
index 000000000000..68ecd5c113e9
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/index.rst
@@ -0,0 +1,19 @@
1==========================================
2Distributed Replicated Block Device - DRBD
3==========================================
4
5Description
6===========
7
8 DRBD is a shared-nothing, synchronously replicated block device. It
9 is designed to serve as a building block for high availability
10 clusters and in this context, is a "drop-in" replacement for shared
11 storage. Simplistically, you could see it as a network RAID 1.
12
13 Please visit http://www.drbd.org to find out more.
14
15.. toctree::
16 :maxdepth: 1
17
18 data-structure-v9
19 figures
diff --git a/Documentation/admin-guide/blockdev/drbd/node-states-8.dot b/Documentation/admin-guide/blockdev/drbd/node-states-8.dot
new file mode 100644
index 000000000000..bfa54e1f8016
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/node-states-8.dot
@@ -0,0 +1,13 @@
1digraph node_states {
2 Secondary -> Primary [ label = "ioctl_set_state()" ]
3 Primary -> Secondary [ label = "ioctl_set_state()" ]
4}
5
6digraph peer_states {
7 Secondary -> Primary [ label = "recv state packet" ]
8 Primary -> Secondary [ label = "recv state packet" ]
9 Primary -> Unknown [ label = "connection lost" ]
10 Secondary -> Unknown [ label = "connection lost" ]
11 Unknown -> Primary [ label = "connected" ]
12 Unknown -> Secondary [ label = "connected" ]
13}
diff --git a/Documentation/admin-guide/blockdev/floppy.rst b/Documentation/admin-guide/blockdev/floppy.rst
new file mode 100644
index 000000000000..4a8f31cf4139
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/floppy.rst
@@ -0,0 +1,255 @@
1=============
2Floppy Driver
3=============
4
5FAQ list:
6=========
7
8A FAQ list may be found in the fdutils package (see below), and also
9at <http://fdutils.linux.lu/faq.html>.
10
11
12LILO configuration options (Thinkpad users, read this)
13======================================================
14
15The floppy driver is configured using the 'floppy=' option in
16lilo. This option can be typed at the boot prompt, or entered in the
17lilo configuration file.
18
19Example: If your kernel is called linux-2.6.9, type the following line
20at the lilo boot prompt (if you have a thinkpad)::
21
22 linux-2.6.9 floppy=thinkpad
23
24You may also enter the following line in /etc/lilo.conf, in the description
25of linux-2.6.9::
26
27 append = "floppy=thinkpad"
28
29Several floppy related options may be given, example::
30
31 linux-2.6.9 floppy=daring floppy=two_fdc
32 append = "floppy=daring floppy=two_fdc"
33
34If you give options both in the lilo config file and on the boot
35prompt, the option strings of both places are concatenated, the boot
36prompt options coming last. That's why there are also options to
37restore the default behavior.
38
39
40Module configuration options
41============================
42
43If you use the floppy driver as a module, use the following syntax::
44
45 modprobe floppy floppy="<options>"
46
47Example::
48
49 modprobe floppy floppy="omnibook messages"
50
51If you need certain options enabled every time you load the floppy driver,
52you can put::
53
54 options floppy floppy="omnibook messages"
55
56in a configuration file in /etc/modprobe.d/.
57
58
59The floppy driver related options are:
60
61 floppy=asus_pci
62 Sets the bit mask to allow only units 0 and 1. (default)
63
64 floppy=daring
65 Tells the floppy driver that you have a well behaved floppy controller.
66 This allows more efficient and smoother operation, but may fail on
67 certain controllers. This may speed up certain operations.
68
69 floppy=0,daring
70 Tells the floppy driver that your floppy controller should be used
71 with caution.
72
73 floppy=one_fdc
74 Tells the floppy driver that you have only one floppy controller.
75 (default)
76
77 floppy=two_fdc / floppy=<address>,two_fdc
78 Tells the floppy driver that you have two floppy controllers.
79 The second floppy controller is assumed to be at <address>.
80 This option is not needed if the second controller is at address
81 0x370, and if you use the 'cmos' option.
82
83 floppy=thinkpad
84 Tells the floppy driver that you have a Thinkpad. Thinkpads use an
85 inverted convention for the disk change line.
86
87 floppy=0,thinkpad
88 Tells the floppy driver that you don't have a Thinkpad.
89
90 floppy=omnibook / floppy=nodma
91 Tells the floppy driver not to use Dma for data transfers.
92 This is needed on HP Omnibooks, which don't have a workable
93 DMA channel for the floppy driver. This option is also useful
94 if you frequently get "Unable to allocate DMA memory" messages.
95 Indeed, dma memory needs to be continuous in physical memory,
96 and is thus harder to find, whereas non-dma buffers may be
97 allocated in virtual memory. However, I advise against this if
98 you have an FDC without a FIFO (8272A or 82072). 82072A and
99 later are OK. You also need at least a 486 to use nodma.
100 If you use nodma mode, I suggest you also set the FIFO
101 threshold to 10 or lower, in order to limit the number of data
102 transfer interrupts.
103
104 If you have a FIFO-able FDC, the floppy driver automatically
105 falls back on non DMA mode if no DMA-able memory can be found.
106 If you want to avoid this, explicitly ask for 'yesdma'.
107
108 floppy=yesdma
109 Tells the floppy driver that a workable DMA channel is available.
110 (default)
111
112 floppy=nofifo
113 Disables the FIFO entirely. This is needed if you get "Bus
114 master arbitration error" messages from your Ethernet card (or
115 from other devices) while accessing the floppy.
116
117 floppy=usefifo
118 Enables the FIFO. (default)
119
120 floppy=<threshold>,fifo_depth
121 Sets the FIFO threshold. This is mostly relevant in DMA
122 mode. If this is higher, the floppy driver tolerates more
123 interrupt latency, but it triggers more interrupts (i.e. it
124 imposes more load on the rest of the system). If this is
125 lower, the interrupt latency should be lower too (faster
126 processor). The benefit of a lower threshold is less
127 interrupts.
128
129 To tune the fifo threshold, switch on over/underrun messages
130 using 'floppycontrol --messages'. Then access a floppy
131 disk. If you get a huge amount of "Over/Underrun - retrying"
132 messages, then the fifo threshold is too low. Try with a
133 higher value, until you only get an occasional Over/Underrun.
134 It is a good idea to compile the floppy driver as a module
135 when doing this tuning. Indeed, it allows to try different
136 fifo values without rebooting the machine for each test. Note
137 that you need to do 'floppycontrol --messages' every time you
138 re-insert the module.
139
140 Usually, tuning the fifo threshold should not be needed, as
141 the default (0xa) is reasonable.
142
143 floppy=<drive>,<type>,cmos
144 Sets the CMOS type of <drive> to <type>. This is mandatory if
145 you have more than two floppy drives (only two can be
146 described in the physical CMOS), or if your BIOS uses
147 non-standard CMOS types. The CMOS types are:
148
149 == ==================================
150 0 Use the value of the physical CMOS
151 1 5 1/4 DD
152 2 5 1/4 HD
153 3 3 1/2 DD
154 4 3 1/2 HD
155 5 3 1/2 ED
156 6 3 1/2 ED
157 16 unknown or not installed
158 == ==================================
159
160 (Note: there are two valid types for ED drives. This is because 5 was
161 initially chosen to represent floppy *tapes*, and 6 for ED drives.
162 AMI ignored this, and used 5 for ED drives. That's why the floppy
163 driver handles both.)
164
165 floppy=unexpected_interrupts
166 Print a warning message when an unexpected interrupt is received.
167 (default)
168
169 floppy=no_unexpected_interrupts / floppy=L40SX
170 Don't print a message when an unexpected interrupt is received. This
171 is needed on IBM L40SX laptops in certain video modes. (There seems
172 to be an interaction between video and floppy. The unexpected
173 interrupts affect only performance, and can be safely ignored.)
174
175 floppy=broken_dcl
176 Don't use the disk change line, but assume that the disk was
177 changed whenever the device node is reopened. Needed on some
178 boxes where the disk change line is broken or unsupported.
179 This should be regarded as a stopgap measure, indeed it makes
180 floppy operation less efficient due to unneeded cache
181 flushings, and slightly more unreliable. Please verify your
182 cable, connection and jumper settings if you have any DCL
183 problems. However, some older drives, and also some laptops
184 are known not to have a DCL.
185
186 floppy=debug
187 Print debugging messages.
188
189 floppy=messages
190 Print informational messages for some operations (disk change
191 notifications, warnings about over and underruns, and about
192 autodetection).
193
194 floppy=silent_dcl_clear
195 Uses a less noisy way to clear the disk change line (which
196 doesn't involve seeks). Implied by 'daring' option.
197
198 floppy=<nr>,irq
199 Sets the floppy IRQ to <nr> instead of 6.
200
201 floppy=<nr>,dma
202 Sets the floppy DMA channel to <nr> instead of 2.
203
204 floppy=slow
205 Use PS/2 stepping rate::
206
207 PS/2 floppies have much slower step rates than regular floppies.
208 It's been recommended that take about 1/4 of the default speed
209 in some more extreme cases.
210
211
212Supporting utilities and additional documentation:
213==================================================
214
215Additional parameters of the floppy driver can be configured at
216runtime. Utilities which do this can be found in the fdutils package.
217This package also contains a new version of mtools which allows to
218access high capacity disks (up to 1992K on a high density 3 1/2 disk!).
219It also contains additional documentation about the floppy driver.
220
221The latest version can be found at fdutils homepage:
222
223 http://fdutils.linux.lu
224
225The fdutils releases can be found at:
226
227 http://fdutils.linux.lu/download.html
228
229 http://www.tux.org/pub/knaff/fdutils/
230
231 ftp://metalab.unc.edu/pub/Linux/utils/disk-management/
232
233Reporting problems about the floppy driver
234==========================================
235
236If you have a question or a bug report about the floppy driver, mail
237me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use
238comp.os.linux.hardware. As the volume in these groups is rather high,
239be sure to include the word "floppy" (or "FLOPPY") in the subject
240line. If the reported problem happens when mounting floppy disks, be
241sure to mention also the type of the filesystem in the subject line.
242
243Be sure to read the FAQ before mailing/posting any bug reports!
244
245Alain
246
247Changelog
248=========
249
25010-30-2004 :
251 Cleanup, updating, add reference to module configuration.
252 James Nelson <james4765@gmail.com>
253
2546-3-2000 :
255 Original Document
diff --git a/Documentation/admin-guide/blockdev/index.rst b/Documentation/admin-guide/blockdev/index.rst
new file mode 100644
index 000000000000..20a738d9d047
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/index.rst
@@ -0,0 +1,14 @@
1===========================
2The Linux RapidIO Subsystem
3===========================
4
5.. toctree::
6 :maxdepth: 1
7
8 floppy
9 nbd
10 paride
11 ramdisk
12 zram
13
14 drbd/index
diff --git a/Documentation/admin-guide/blockdev/nbd.rst b/Documentation/admin-guide/blockdev/nbd.rst
new file mode 100644
index 000000000000..d78dfe559dcf
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/nbd.rst
@@ -0,0 +1,31 @@
1==================================
2Network Block Device (TCP version)
3==================================
4
51) Overview
6-----------
7
8What is it: With this compiled in the kernel (or as a module), Linux
9can use a remote server as one of its block devices. So every time
10the client computer wants to read, e.g., /dev/nb0, it sends a
11request over TCP to the server, which will reply with the data read.
12This can be used for stations with low disk space (or even diskless)
13to borrow disk space from another computer.
14Unlike NFS, it is possible to put any filesystem on it, etc.
15
16For more information, or to download the nbd-client and nbd-server
17tools, go to http://nbd.sf.net/.
18
19The nbd kernel module need only be installed on the client
20system, as the nbd-server is completely in userspace. In fact,
21the nbd-server has been successfully ported to other operating
22systems, including Windows.
23
24A) NBD parameters
25-----------------
26
27max_part
28 Number of partitions per device (default: 0).
29
30nbds_max
31 Number of block devices that should be initialized (default: 16).
diff --git a/Documentation/admin-guide/blockdev/paride.rst b/Documentation/admin-guide/blockdev/paride.rst
new file mode 100644
index 000000000000..87b4278bf314
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/paride.rst
@@ -0,0 +1,439 @@
1===================================
2Linux and parallel port IDE devices
3===================================
4
5PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net>
6
71. Introduction
8===============
9
10Owing to the simplicity and near universality of the parallel port interface
11to personal computers, many external devices such as portable hard-disk,
12CD-ROM, LS-120 and tape drives use the parallel port to connect to their
13host computer. While some devices (notably scanners) use ad-hoc methods
14to pass commands and data through the parallel port interface, most
15external devices are actually identical to an internal model, but with
16a parallel-port adapter chip added in. Some of the original parallel port
17adapters were little more than mechanisms for multiplexing a SCSI bus.
18(The Iomega PPA-3 adapter used in the ZIP drives is an example of this
19approach). Most current designs, however, take a different approach.
20The adapter chip reproduces a small ISA or IDE bus in the external device
21and the communication protocol provides operations for reading and writing
22device registers, as well as data block transfer functions. Sometimes,
23the device being addressed via the parallel cable is a standard SCSI
24controller like an NCR 5380. The "ditto" family of external tape
25drives use the ISA replicator to interface a floppy disk controller,
26which is then connected to a floppy-tape mechanism. The vast majority
27of external parallel port devices, however, are now based on standard
28IDE type devices, which require no intermediate controller. If one
29were to open up a parallel port CD-ROM drive, for instance, one would
30find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
31that interconnected a standard PC parallel port cable and a standard
32IDE cable. It is usually possible to exchange the CD-ROM device with
33any other device using the IDE interface.
34
35The document describes the support in Linux for parallel port IDE
36devices. It does not cover parallel port SCSI devices, "ditto" tape
37drives or scanners. Many different devices are supported by the
38parallel port IDE subsystem, including:
39
40 - MicroSolutions backpack CD-ROM
41 - MicroSolutions backpack PD/CD
42 - MicroSolutions backpack hard-drives
43 - MicroSolutions backpack 8000t tape drive
44 - SyQuest EZ-135, EZ-230 & SparQ drives
45 - Avatar Shark
46 - Imation Superdisk LS-120
47 - Maxell Superdisk LS-120
48 - FreeCom Power CD
49 - Hewlett-Packard 5GB and 8GB tape drives
50 - Hewlett-Packard 7100 and 7200 CD-RW drives
51
52as well as most of the clone and no-name products on the market.
53
54To support such a wide range of devices, PARIDE, the parallel port IDE
55subsystem, is actually structured in three parts. There is a base
56paride module which provides a registry and some common methods for
57accessing the parallel ports. The second component is a set of
58high-level drivers for each of the different types of supported devices:
59
60 === =============
61 pd IDE disk
62 pcd ATAPI CD-ROM
63 pf ATAPI disk
64 pt ATAPI tape
65 pg ATAPI generic
66 === =============
67
68(Currently, the pg driver is only used with CD-R drives).
69
70The high-level drivers function according to the relevant standards.
71The third component of PARIDE is a set of low-level protocol drivers
72for each of the parallel port IDE adapter chips. Thanks to the interest
73and encouragement of Linux users from many parts of the world,
74support is available for almost all known adapter protocols:
75
76 ==== ====================================== ====
77 aten ATEN EH-100 (HK)
78 bpck Microsolutions backpack (US)
79 comm DataStor (old-type) "commuter" adapter (TW)
80 dstr DataStor EP-2000 (TW)
81 epat Shuttle EPAT (UK)
82 epia Shuttle EPIA (UK)
83 fit2 FIT TD-2000 (US)
84 fit3 FIT TD-3000 (US)
85 friq Freecom IQ cable (DE)
86 frpw Freecom Power (DE)
87 kbic KingByte KBIC-951A and KBIC-971A (TW)
88 ktti KT Technology PHd adapter (SG)
89 on20 OnSpec 90c20 (US)
90 on26 OnSpec 90c26 (US)
91 ==== ====================================== ====
92
93
942. Using the PARIDE subsystem
95=============================
96
97While configuring the Linux kernel, you may choose either to build
98the PARIDE drivers into your kernel, or to build them as modules.
99
100In either case, you will need to select "Parallel port IDE device support"
101as well as at least one of the high-level drivers and at least one
102of the parallel port communication protocols. If you do not know
103what kind of parallel port adapter is used in your drive, you could
104begin by checking the file names and any text files on your DOS
105installation floppy. Alternatively, you can look at the markings on
106the adapter chip itself. That's usually sufficient to identify the
107correct device.
108
109You can actually select all the protocol modules, and allow the PARIDE
110subsystem to try them all for you.
111
112For the "brand-name" products listed above, here are the protocol
113and high-level drivers that you would use:
114
115 ================ ============ ====== ========
116 Manufacturer Model Driver Protocol
117 ================ ============ ====== ========
118 MicroSolutions CD-ROM pcd bpck
119 MicroSolutions PD drive pf bpck
120 MicroSolutions hard-drive pd bpck
121 MicroSolutions 8000t tape pt bpck
122 SyQuest EZ, SparQ pd epat
123 Imation Superdisk pf epat
124 Maxell Superdisk pf friq
125 Avatar Shark pd epat
126 FreeCom CD-ROM pcd frpw
127 Hewlett-Packard 5GB Tape pt epat
128 Hewlett-Packard 7200e (CD) pcd epat
129 Hewlett-Packard 7200e (CD-R) pg epat
130 ================ ============ ====== ========
131
1322.1 Configuring built-in drivers
133---------------------------------
134
135We recommend that you get to know how the drivers work and how to
136configure them as loadable modules, before attempting to compile a
137kernel with the drivers built-in.
138
139If you built all of your PARIDE support directly into your kernel,
140and you have just a single parallel port IDE device, your kernel should
141locate it automatically for you. If you have more than one device,
142you may need to give some command line options to your bootloader
143(eg: LILO), how to do that is beyond the scope of this document.
144
145The high-level drivers accept a number of command line parameters, all
146of which are documented in the source files in linux/drivers/block/paride.
147By default, each driver will automatically try all parallel ports it
148can find, and all protocol types that have been installed, until it finds
149a parallel port IDE adapter. Once it finds one, the probe stops. So,
150if you have more than one device, you will need to tell the drivers
151how to identify them. This requires specifying the port address, the
152protocol identification number and, for some devices, the drive's
153chain ID. While your system is booting, a number of messages are
154displayed on the console. Like all such messages, they can be
155reviewed with the 'dmesg' command. Among those messages will be
156some lines like::
157
158 paride: bpck registered as protocol 0
159 paride: epat registered as protocol 1
160
161The numbers will always be the same until you build a new kernel with
162different protocol selections. You should note these numbers as you
163will need them to identify the devices.
164
165If you happen to be using a MicroSolutions backpack device, you will
166also need to know the unit ID number for each drive. This is usually
167the last two digits of the drive's serial number (but read MicroSolutions'
168documentation about this).
169
170As an example, let's assume that you have a MicroSolutions PD/CD drive
171with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
172EZ-135 connected to the chained port on the PD/CD drive and also an
173Imation Superdisk connected to port 0x278. You could give the following
174options on your boot command::
175
176 pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36
177
178In the last option, pf.drive1 configures device /dev/pf1, the 0x378
179is the parallel port base address, the 0 is the protocol registration
180number and 36 is the chain ID.
181
182Please note: while PARIDE will work both with and without the
183PARPORT parallel port sharing system that is included by the
184"Parallel port support" option, PARPORT must be included and enabled
185if you want to use chains of devices on the same parallel port.
186
1872.2 Loading and configuring PARIDE as modules
188----------------------------------------------
189
190It is much faster and simpler to get to understand the PARIDE drivers
191if you use them as loadable kernel modules.
192
193Note 1:
194 using these drivers with the "kerneld" automatic module loading
195 system is not recommended for beginners, and is not documented here.
196
197Note 2:
198 if you build PARPORT support as a loadable module, PARIDE must
199 also be built as loadable modules, and PARPORT must be loaded before
200 the PARIDE modules.
201
202To use PARIDE, you must begin by::
203
204 insmod paride
205
206this loads a base module which provides a registry for the protocols,
207among other tasks.
208
209Then, load as many of the protocol modules as you think you might need.
210As you load each module, it will register the protocols that it supports,
211and print a log message to your kernel log file and your console. For
212example::
213
214 # insmod epat
215 paride: epat registered as protocol 0
216 # insmod kbic
217 paride: k951 registered as protocol 1
218 paride: k971 registered as protocol 2
219
220Finally, you can load high-level drivers for each kind of device that
221you have connected. By default, each driver will autoprobe for a single
222device, but you can support up to four similar devices by giving their
223individual co-ordinates when you load the driver.
224
225For example, if you had two no-name CD-ROM drives both using the
226KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
227you could give the following command::
228
229 # insmod pcd drive0=0x378,1 drive1=0x3bc,1
230
231For most adapters, giving a port address and protocol number is sufficient,
232but check the source files in linux/drivers/block/paride for more
233information. (Hopefully someone will write some man pages one day !).
234
235As another example, here's what happens when PARPORT is installed, and
236a SyQuest EZ-135 is attached to port 0x378::
237
238 # insmod paride
239 paride: version 1.0 installed
240 # insmod epat
241 paride: epat registered as protocol 0
242 # insmod pd
243 pd: pd version 1.0, major 45, cluster 64, nice 0
244 pda: Sharing parport1 at 0x378
245 pda: epat 1.0, Shuttle EPAT chip c3 at 0x378, mode 5 (EPP-32), delay 1
246 pda: SyQuest EZ135A, 262144 blocks [128M], (512/16/32), removable media
247 pda: pda1
248
249Note that the last line is the output from the generic partition table
250scanner - in this case it reports that it has found a disk with one partition.
251
2522.3 Using a PARIDE device
253--------------------------
254
255Once the drivers have been loaded, you can access PARIDE devices in the
256same way as their traditional counterparts. You will probably need to
257create the device "special files". Here is a simple script that you can
258cut to a file and execute::
259
260 #!/bin/bash
261 #
262 # mkd -- a script to create the device special files for the PARIDE subsystem
263 #
264 function mkdev {
265 mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
266 }
267 #
268 function pd {
269 D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
270 mkdev pd$D b 45 $[ $1 * 16 ]
271 for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
272 do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
273 done
274 }
275 #
276 cd /dev
277 #
278 for u in 0 1 2 3 ; do pd $u ; done
279 for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done
280 for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done
281 for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done
282 for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done
283 for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done
284 #
285 # end of mkd
286
287With the device files and drivers in place, you can access PARIDE devices
288like any other Linux device. For example, to mount a CD-ROM in pcd0, use::
289
290 mount /dev/pcd0 /cdrom
291
292If you have a fresh Avatar Shark cartridge, and the drive is pda, you
293might do something like::
294
295 fdisk /dev/pda -- make a new partition table with
296 partition 1 of type 83
297
298 mke2fs /dev/pda1 -- to build the file system
299
300 mkdir /shark -- make a place to mount the disk
301
302 mount /dev/pda1 /shark
303
304Devices like the Imation superdisk work in the same way, except that
305they do not have a partition table. For example to make a 120MB
306floppy that you could share with a DOS system::
307
308 mkdosfs /dev/pf0
309 mount /dev/pf0 /mnt
310
311
3122.4 The pf driver
313------------------
314
315The pf driver is intended for use with parallel port ATAPI disk
316devices. The most common devices in this category are PD drives
317and LS-120 drives. Traditionally, media for these devices are not
318partitioned. Consequently, the pf driver does not support partitioned
319media. This may be changed in a future version of the driver.
320
3212.5 Using the pt driver
322------------------------
323
324The pt driver for parallel port ATAPI tape drives is a minimal driver.
325It does not yet support many of the standard tape ioctl operations.
326For best performance, a block size of 32KB should be used. You will
327probably want to set the parallel port delay to 0, if you can.
328
3292.6 Using the pg driver
330------------------------
331
332The pg driver can be used in conjunction with the cdrecord program
333to create CD-ROMs. Please get cdrecord version 1.6.1 or later
334from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media
335your parallel port should ideally be set to EPP mode, and the "port delay"
336should be set to 0. With those settings it is possible to record at 2x
337speed without any buffer underruns. If you cannot get the driver to work
338in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.
339
340
3413. Troubleshooting
342==================
343
3443.1 Use EPP mode if you can
345----------------------------
346
347The most common problems that people report with the PARIDE drivers
348concern the parallel port CMOS settings. At this time, none of the
349PARIDE protocol modules support ECP mode, or any ECP combination modes.
350If you are able to do so, please set your parallel port into EPP mode
351using your CMOS setup procedure.
352
3533.2 Check the port delay
354-------------------------
355
356Some parallel ports cannot reliably transfer data at full speed. To
357offset the errors, the PARIDE protocol modules introduce a "port
358delay" between each access to the i/o ports. Each protocol sets
359a default value for this delay. In most cases, the user can override
360the default and set it to 0 - resulting in somewhat higher transfer
361rates. In some rare cases (especially with older 486 systems) the
362default delays are not long enough. if you experience corrupt data
363transfers, or unexpected failures, you may wish to increase the
364port delay. The delay can be programmed using the "driveN" parameters
365to each of the high-level drivers. Please see the notes above, or
366read the comments at the beginning of the driver source files in
367linux/drivers/block/paride.
368
3693.3 Some drives need a printer reset
370-------------------------------------
371
372There appear to be a number of "noname" external drives on the market
373that do not always power up correctly. We have noticed this with some
374drives based on OnSpec and older Freecom adapters. In these rare cases,
375the adapter can often be reinitialised by issuing a "printer reset" on
376the parallel port. As the reset operation is potentially disruptive in
377multiple device environments, the PARIDE drivers will not do it
378automatically. You can however, force a printer reset by doing::
379
380 insmod lp reset=1
381 rmmod lp
382
383If you have one of these marginal cases, you should probably build
384your paride drivers as modules, and arrange to do the printer reset
385before loading the PARIDE drivers.
386
3873.4 Use the verbose option and dmesg if you need help
388------------------------------------------------------
389
390While a lot of testing has gone into these drivers to make them work
391as smoothly as possible, problems will arise. If you do have problems,
392please check all the obvious things first: does the drive work in
393DOS with the manufacturer's drivers ? If that doesn't yield any useful
394clues, then please make sure that only one drive is hooked to your system,
395and that either (a) PARPORT is enabled or (b) no other device driver
396is using your parallel port (check in /proc/ioports). Then, load the
397appropriate drivers (you can load several protocol modules if you want)
398as in::
399
400 # insmod paride
401 # insmod epat
402 # insmod bpck
403 # insmod kbic
404 ...
405 # insmod pd verbose=1
406
407(using the correct driver for the type of device you have, of course).
408The verbose=1 parameter will cause the drivers to log a trace of their
409activity as they attempt to locate your drive.
410
411Use 'dmesg' to capture a log of all the PARIDE messages (any messages
412beginning with paride:, a protocol module's name or a driver's name) and
413include that with your bug report. You can submit a bug report in one
414of two ways. Either send it directly to the author of the PARIDE suite,
415by e-mail to grant@torque.net, or join the linux-parport mailing list
416and post your report there.
417
4183.5 For more information or help
419---------------------------------
420
421You can join the linux-parport mailing list by sending a mail message
422to:
423
424 linux-parport-request@torque.net
425
426with the single word::
427
428 subscribe
429
430in the body of the mail message (not in the subject line). Please be
431sure that your mail program is correctly set up when you do this, as
432the list manager is a robot that will subscribe you using the reply
433address in your mail headers. REMOVE any anti-spam gimmicks you may
434have in your mail headers, when sending mail to the list server.
435
436You might also find some useful information on the linux-parport
437web pages (although they are not always up to date) at
438
439 http://web.archive.org/web/%2E/http://www.torque.net/parport/
diff --git a/Documentation/admin-guide/blockdev/ramdisk.rst b/Documentation/admin-guide/blockdev/ramdisk.rst
new file mode 100644
index 000000000000..b7c2268f8dec
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/ramdisk.rst
@@ -0,0 +1,177 @@
1==========================================
2Using the RAM disk block device with Linux
3==========================================
4
5.. Contents:
6
7 1) Overview
8 2) Kernel Command Line Parameters
9 3) Using "rdev -r"
10 4) An Example of Creating a Compressed RAM Disk
11
12
131) Overview
14-----------
15
16The RAM disk driver is a way to use main system memory as a block device. It
17is required for initrd, an initial filesystem used if you need to load modules
18in order to access the root filesystem (see Documentation/admin-guide/initrd.rst). It can
19also be used for a temporary filesystem for crypto work, since the contents
20are erased on reboot.
21
22The RAM disk dynamically grows as more space is required. It does this by using
23RAM from the buffer cache. The driver marks the buffers it is using as dirty
24so that the VM subsystem does not try to reclaim them later.
25
26The RAM disk supports up to 16 RAM disks by default, and can be reconfigured
27to support an unlimited number of RAM disks (at your own risk). Just change
28the configuration symbol BLK_DEV_RAM_COUNT in the Block drivers config menu
29and (re)build the kernel.
30
31To use RAM disk support with your system, run './MAKEDEV ram' from the /dev
32directory. RAM disks are all major number 1, and start with minor number 0
33for /dev/ram0, etc. If used, modern kernels use /dev/ram0 for an initrd.
34
35The new RAM disk also has the ability to load compressed RAM disk images,
36allowing one to squeeze more programs onto an average installation or
37rescue floppy disk.
38
39
402) Parameters
41---------------------------------
42
432a) Kernel Command Line Parameters
44
45 ramdisk_size=N
46 Size of the ramdisk.
47
48This parameter tells the RAM disk driver to set up RAM disks of N k size. The
49default is 4096 (4 MB).
50
512b) Module parameters
52
53 rd_nr
54 /dev/ramX devices created.
55
56 max_part
57 Maximum partition number.
58
59 rd_size
60 See ramdisk_size.
61
623) Using "rdev -r"
63------------------
64
65The usage of the word (two bytes) that "rdev -r" sets in the kernel image is
66as follows. The low 11 bits (0 -> 10) specify an offset (in 1 k blocks) of up
67to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit
6814 indicates that a RAM disk is to be loaded, and bit 15 indicates whether a
69prompt/wait sequence is to be given before trying to read the RAM disk. Since
70the RAM disk dynamically grows as data is being written into it, a size field
71is not required. Bits 11 to 13 are not currently used and may as well be zero.
72These numbers are no magical secrets, as seen below::
73
74 ./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF
75 ./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000
76 ./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000
77
78Consider a typical two floppy disk setup, where you will have the
79kernel on disk one, and have already put a RAM disk image onto disk #2.
80
81Hence you want to set bits 0 to 13 as 0, meaning that your RAM disk
82starts at an offset of 0 kB from the beginning of the floppy.
83The command line equivalent is: "ramdisk_start=0"
84
85You want bit 14 as one, indicating that a RAM disk is to be loaded.
86The command line equivalent is: "load_ramdisk=1"
87
88You want bit 15 as one, indicating that you want a prompt/keypress
89sequence so that you have a chance to switch floppy disks.
90The command line equivalent is: "prompt_ramdisk=1"
91
92Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word.
93So to create disk one of the set, you would do::
94
95 /usr/src/linux# cat arch/x86/boot/zImage > /dev/fd0
96 /usr/src/linux# rdev /dev/fd0 /dev/fd0
97 /usr/src/linux# rdev -r /dev/fd0 49152
98
99If you make a boot disk that has LILO, then for the above, you would use::
100
101 append = "ramdisk_start=0 load_ramdisk=1 prompt_ramdisk=1"
102
103Since the default start = 0 and the default prompt = 1, you could use::
104
105 append = "load_ramdisk=1"
106
107
1084) An Example of Creating a Compressed RAM Disk
109-----------------------------------------------
110
111To create a RAM disk image, you will need a spare block device to
112construct it on. This can be the RAM disk device itself, or an
113unused disk partition (such as an unmounted swap partition). For this
114example, we will use the RAM disk device, "/dev/ram0".
115
116Note: This technique should not be done on a machine with less than 8 MB
117of RAM. If using a spare disk partition instead of /dev/ram0, then this
118restriction does not apply.
119
120a) Decide on the RAM disk size that you want. Say 2 MB for this example.
121 Create it by writing to the RAM disk device. (This step is not currently
122 required, but may be in the future.) It is wise to zero out the
123 area (esp. for disks) so that maximal compression is achieved for
124 the unused blocks of the image that you are about to create::
125
126 dd if=/dev/zero of=/dev/ram0 bs=1k count=2048
127
128b) Make a filesystem on it. Say ext2fs for this example::
129
130 mke2fs -vm0 /dev/ram0 2048
131
132c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...)
133 and unmount it again.
134
135d) Compress the contents of the RAM disk. The level of compression
136 will be approximately 50% of the space used by the files. Unused
137 space on the RAM disk will compress to almost nothing::
138
139 dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz
140
141e) Put the kernel onto the floppy::
142
143 dd if=zImage of=/dev/fd0 bs=1k
144
145f) Put the RAM disk image onto the floppy, after the kernel. Use an offset
146 that is slightly larger than the kernel, so that you can put another
147 (possibly larger) kernel onto the same floppy later without overlapping
148 the RAM disk image. An offset of 400 kB for kernels about 350 kB in
149 size would be reasonable. Make sure offset+size of ram_image.gz is
150 not larger than the total space on your floppy (usually 1440 kB)::
151
152 dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400
153
154g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
155 For prompt_ramdisk=1, load_ramdisk=1, ramdisk_start=400, one would
156 have 2^15 + 2^14 + 400 = 49552::
157
158 rdev /dev/fd0 /dev/fd0
159 rdev -r /dev/fd0 49552
160
161That is it. You now have your boot/root compressed RAM disk floppy. Some
162users may wish to combine steps (d) and (f) by using a pipe.
163
164
165 Paul Gortmaker 12/95
166
167Changelog:
168----------
169
17010-22-04 :
171 Updated to reflect changes in command line options, remove
172 obsolete references, general cleanup.
173 James Nelson (james4765@gmail.com)
174
175
17612-95 :
177 Original Document
diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst
new file mode 100644
index 000000000000..6eccf13219ff
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/zram.rst
@@ -0,0 +1,422 @@
1========================================
2zram: Compressed RAM based block devices
3========================================
4
5Introduction
6============
7
8The zram module creates RAM based block devices named /dev/zram<id>
9(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
10in memory itself. These disks allow very fast I/O and compression provides
11good amounts of memory savings. Some of the usecases include /tmp storage,
12use as swap disks, various caches under /var and maybe many more :)
13
14Statistics for individual zram devices are exported through sysfs nodes at
15/sys/block/zram<id>/
16
17Usage
18=====
19
20There are several ways to configure and manage zram device(-s):
21
22a) using zram and zram_control sysfs attributes
23b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
24
25In this document we will describe only 'manual' zram configuration steps,
26IOW, zram and zram_control sysfs attributes.
27
28In order to get a better idea about zramctl please consult util-linux
29documentation, zramctl man-page or `zramctl --help`. Please be informed
30that zram maintainers do not develop/maintain util-linux or zramctl, should
31you have any questions please contact util-linux@vger.kernel.org
32
33Following shows a typical sequence of steps for using zram.
34
35WARNING
36=======
37
38For the sake of simplicity we skip error checking parts in most of the
39examples below. However, it is your sole responsibility to handle errors.
40
41zram sysfs attributes always return negative values in case of errors.
42The list of possible return codes:
43
44======== =============================================================
45-EBUSY an attempt to modify an attribute that cannot be changed once
46 the device has been initialised. Please reset device first;
47-ENOMEM zram was not able to allocate enough memory to fulfil your
48 needs;
49-EINVAL invalid input has been provided.
50======== =============================================================
51
52If you use 'echo', the returned value that is changed by 'echo' utility,
53and, in general case, something like::
54
55 echo 3 > /sys/block/zram0/max_comp_streams
56 if [ $? -ne 0 ];
57 handle_error
58 fi
59
60should suffice.
61
621) Load Module
63==============
64
65::
66
67 modprobe zram num_devices=4
68 This creates 4 devices: /dev/zram{0,1,2,3}
69
70num_devices parameter is optional and tells zram how many devices should be
71pre-created. Default: 1.
72
732) Set max number of compression streams
74========================================
75
76Regardless the value passed to this attribute, ZRAM will always
77allocate multiple compression streams - one per online CPUs - thus
78allowing several concurrent compression operations. The number of
79allocated compression streams goes down when some of the CPUs
80become offline. There is no single-compression-stream mode anymore,
81unless you are running a UP system or has only 1 CPU online.
82
83To find out how many streams are currently available::
84
85 cat /sys/block/zram0/max_comp_streams
86
873) Select compression algorithm
88===============================
89
90Using comp_algorithm device attribute one can see available and
91currently selected (shown in square brackets) compression algorithms,
92change selected compression algorithm (once the device is initialised
93there is no way to change compression algorithm).
94
95Examples::
96
97 #show supported compression algorithms
98 cat /sys/block/zram0/comp_algorithm
99 lzo [lz4]
100
101 #select lzo compression algorithm
102 echo lzo > /sys/block/zram0/comp_algorithm
103
104For the time being, the `comp_algorithm` content does not necessarily
105show every compression algorithm supported by the kernel. We keep this
106list primarily to simplify device configuration and one can configure
107a new device with a compression algorithm that is not listed in
108`comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API
109and, if some of the algorithms were built as modules, it's impossible
110to list all of them using, for instance, /proc/crypto or any other
111method. This, however, has an advantage of permitting the usage of
112custom crypto compression modules (implementing S/W or H/W compression).
113
1144) Set Disksize
115===============
116
117Set disk size by writing the value to sysfs node 'disksize'.
118The value can be either in bytes or you can use mem suffixes.
119Examples::
120
121 # Initialize /dev/zram0 with 50MB disksize
122 echo $((50*1024*1024)) > /sys/block/zram0/disksize
123
124 # Using mem suffixes
125 echo 256K > /sys/block/zram0/disksize
126 echo 512M > /sys/block/zram0/disksize
127 echo 1G > /sys/block/zram0/disksize
128
129Note:
130There is little point creating a zram of greater than twice the size of memory
131since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
132size of the disk when not in use so a huge zram is wasteful.
133
1345) Set memory limit: Optional
135=============================
136
137Set memory limit by writing the value to sysfs node 'mem_limit'.
138The value can be either in bytes or you can use mem suffixes.
139In addition, you could change the value in runtime.
140Examples::
141
142 # limit /dev/zram0 with 50MB memory
143 echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
144
145 # Using mem suffixes
146 echo 256K > /sys/block/zram0/mem_limit
147 echo 512M > /sys/block/zram0/mem_limit
148 echo 1G > /sys/block/zram0/mem_limit
149
150 # To disable memory limit
151 echo 0 > /sys/block/zram0/mem_limit
152
1536) Activate
154===========
155
156::
157
158 mkswap /dev/zram0
159 swapon /dev/zram0
160
161 mkfs.ext4 /dev/zram1
162 mount /dev/zram1 /tmp
163
1647) Add/remove zram devices
165==========================
166
167zram provides a control interface, which enables dynamic (on-demand) device
168addition and removal.
169
170In order to add a new /dev/zramX device, perform read operation on hot_add
171attribute. This will return either new device's device id (meaning that you
172can use /dev/zram<id>) or error code.
173
174Example::
175
176 cat /sys/class/zram-control/hot_add
177 1
178
179To remove the existing /dev/zramX device (where X is a device id)
180execute::
181
182 echo X > /sys/class/zram-control/hot_remove
183
1848) Stats
185========
186
187Per-device statistics are exported as various nodes under /sys/block/zram<id>/
188
189A brief description of exported device attributes. For more details please
190read Documentation/ABI/testing/sysfs-block-zram.
191
192====================== ====== ===============================================
193Name access description
194====================== ====== ===============================================
195disksize RW show and set the device's disk size
196initstate RO shows the initialization state of the device
197reset WO trigger device reset
198mem_used_max WO reset the `mem_used_max` counter (see later)
199mem_limit WO specifies the maximum amount of memory ZRAM can
200 use to store the compressed data
201writeback_limit WO specifies the maximum amount of write IO zram
202 can write out to backing device as 4KB unit
203writeback_limit_enable RW show and set writeback_limit feature
204max_comp_streams RW the number of possible concurrent compress
205 operations
206comp_algorithm RW show and change the compression algorithm
207compact WO trigger memory compaction
208debug_stat RO this file is used for zram debugging purposes
209backing_dev RW set up backend storage for zram to write out
210idle WO mark allocated slot as idle
211====================== ====== ===============================================
212
213
214User space is advised to use the following files to read the device statistics.
215
216File /sys/block/zram<id>/stat
217
218Represents block layer statistics. Read Documentation/block/stat.rst for
219details.
220
221File /sys/block/zram<id>/io_stat
222
223The stat file represents device's I/O statistics not accounted by block
224layer and, thus, not available in zram<id>/stat file. It consists of a
225single line of text and contains the following stats separated by
226whitespace:
227
228 ============= =============================================================
229 failed_reads The number of failed reads
230 failed_writes The number of failed writes
231 invalid_io The number of non-page-size-aligned I/O requests
232 notify_free Depending on device usage scenario it may account
233
234 a) the number of pages freed because of swap slot free
235 notifications
236 b) the number of pages freed because of
237 REQ_OP_DISCARD requests sent by bio. The former ones are
238 sent to a swap block device when a swap slot is freed,
239 which implies that this disk is being used as a swap disk.
240
241 The latter ones are sent by filesystem mounted with
242 discard option, whenever some data blocks are getting
243 discarded.
244 ============= =============================================================
245
246File /sys/block/zram<id>/mm_stat
247
248The stat file represents device's mm statistics. It consists of a single
249line of text and contains the following stats separated by whitespace:
250
251 ================ =============================================================
252 orig_data_size uncompressed size of data stored in this disk.
253 This excludes same-element-filled pages (same_pages) since
254 no memory is allocated for them.
255 Unit: bytes
256 compr_data_size compressed size of data stored in this disk
257 mem_used_total the amount of memory allocated for this disk. This
258 includes allocator fragmentation and metadata overhead,
259 allocated for this disk. So, allocator space efficiency
260 can be calculated using compr_data_size and this statistic.
261 Unit: bytes
262 mem_limit the maximum amount of memory ZRAM can use to store
263 the compressed data
264 mem_used_max the maximum amount of memory zram have consumed to
265 store the data
266 same_pages the number of same element filled pages written to this disk.
267 No memory is allocated for such pages.
268 pages_compacted the number of pages freed during compaction
269 huge_pages the number of incompressible pages
270 ================ =============================================================
271
272File /sys/block/zram<id>/bd_stat
273
274The stat file represents device's backing device statistics. It consists of
275a single line of text and contains the following stats separated by whitespace:
276
277 ============== =============================================================
278 bd_count size of data written in backing device.
279 Unit: 4K bytes
280 bd_reads the number of reads from backing device
281 Unit: 4K bytes
282 bd_writes the number of writes to backing device
283 Unit: 4K bytes
284 ============== =============================================================
285
2869) Deactivate
287=============
288
289::
290
291 swapoff /dev/zram0
292 umount /dev/zram1
293
29410) Reset
295=========
296
297 Write any positive value to 'reset' sysfs node::
298
299 echo 1 > /sys/block/zram0/reset
300 echo 1 > /sys/block/zram1/reset
301
302 This frees all the memory allocated for the given device and
303 resets the disksize to zero. You must set the disksize again
304 before reusing the device.
305
306Optional Feature
307================
308
309writeback
310---------
311
312With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
313to backing storage rather than keeping it in memory.
314To use the feature, admin should set up backing device via::
315
316 echo /dev/sda5 > /sys/block/zramX/backing_dev
317
318before disksize setting. It supports only partition at this moment.
319If admin want to use incompressible page writeback, they could do via::
320
321 echo huge > /sys/block/zramX/write
322
323To use idle page writeback, first, user need to declare zram pages
324as idle::
325
326 echo all > /sys/block/zramX/idle
327
328From now on, any pages on zram are idle pages. The idle mark
329will be removed until someone request access of the block.
330IOW, unless there is access request, those pages are still idle pages.
331
332Admin can request writeback of those idle pages at right timing via::
333
334 echo idle > /sys/block/zramX/writeback
335
336With the command, zram writeback idle pages from memory to the storage.
337
338If there are lots of write IO with flash device, potentially, it has
339flash wearout problem so that admin needs to design write limitation
340to guarantee storage health for entire product life.
341
342To overcome the concern, zram supports "writeback_limit" feature.
343The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
344any writeback. IOW, if admin want to apply writeback budget, he should
345enable writeback_limit_enable via::
346
347 $ echo 1 > /sys/block/zramX/writeback_limit_enable
348
349Once writeback_limit_enable is set, zram doesn't allow any writeback
350until admin set the budget via /sys/block/zramX/writeback_limit.
351
352(If admin doesn't enable writeback_limit_enable, writeback_limit's value
353assigned via /sys/block/zramX/writeback_limit is meaninless.)
354
355If admin want to limit writeback as per-day 400M, he could do it
356like below::
357
358 $ MB_SHIFT=20
359 $ 4K_SHIFT=12
360 $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
361 /sys/block/zram0/writeback_limit.
362 $ echo 1 > /sys/block/zram0/writeback_limit_enable
363
364If admin want to allow further write again once the bugdet is exausted,
365he could do it like below::
366
367 $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
368 /sys/block/zram0/writeback_limit
369
370If admin want to see remaining writeback budget since he set::
371
372 $ cat /sys/block/zramX/writeback_limit
373
374If admin want to disable writeback limit, he could do::
375
376 $ echo 0 > /sys/block/zramX/writeback_limit_enable
377
378The writeback_limit count will reset whenever you reset zram(e.g.,
379system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
380writeback happened until you reset the zram to allocate extra writeback
381budget in next setting is user's job.
382
383If admin want to measure writeback count in a certain period, he could
384know it via /sys/block/zram0/bd_stat's 3rd column.
385
386memory tracking
387===============
388
389With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
390zram block. It could be useful to catch cold or incompressible
391pages of the process with*pagemap.
392
393If you enable the feature, you could see block state via
394/sys/kernel/debug/zram/zram0/block_state". The output is as follows::
395
396 300 75.033841 .wh.
397 301 63.806904 s...
398 302 63.806919 ..hi
399
400First column
401 zram's block index.
402Second column
403 access time since the system was booted
404Third column
405 state of the block:
406
407 s:
408 same page
409 w:
410 written page to backing store
411 h:
412 huge page
413 i:
414 idle page
415
416First line of above example says 300th block is accessed at 75.033841sec
417and the block's state is huge so it is written back to the backing
418storage. It's a debugging feature so anyone shouldn't rely on it to work
419properly.
420
421Nitin Gupta
422ngupta@vflare.org
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 5b63182ceb5f..9228fbf5ce4e 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -73,6 +73,7 @@ configure specific aspects of kernel behavior to your liking.
73 java 73 java
74 ras 74 ras
75 bcache 75 bcache
76 blockdev/index
76 ext4 77 ext4
77 binderfs 78 binderfs
78 pm/index 79 pm/index
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index e645b3ab4b6f..78576aa45cce 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1249,7 +1249,7 @@
1249 See also Documentation/fault-injection/. 1249 See also Documentation/fault-injection/.
1250 1250
1251 floppy= [HW] 1251 floppy= [HW]
1252 See Documentation/blockdev/floppy.rst. 1252 See Documentation/admin-guide/blockdev/floppy.rst.
1253 1253
1254 force_pal_cache_flush 1254 force_pal_cache_flush
1255 [IA-64] Avoid check_sal_cache_flush which may hang on 1255 [IA-64] Avoid check_sal_cache_flush which may hang on
@@ -2234,7 +2234,7 @@
2234 memblock=debug [KNL] Enable memblock debug messages. 2234 memblock=debug [KNL] Enable memblock debug messages.
2235 2235
2236 load_ramdisk= [RAM] List of ramdisks to load from floppy 2236 load_ramdisk= [RAM] List of ramdisks to load from floppy
2237 See Documentation/blockdev/ramdisk.rst. 2237 See Documentation/admin-guide/blockdev/ramdisk.rst.
2238 2238
2239 lockd.nlm_grace_period=P [NFS] Assign grace period. 2239 lockd.nlm_grace_period=P [NFS] Assign grace period.
2240 Format: <integer> 2240 Format: <integer>
@@ -3268,7 +3268,7 @@
3268 3268
3269 pcd. [PARIDE] 3269 pcd. [PARIDE]
3270 See header of drivers/block/paride/pcd.c. 3270 See header of drivers/block/paride/pcd.c.
3271 See also Documentation/blockdev/paride.rst. 3271 See also Documentation/admin-guide/blockdev/paride.rst.
3272 3272
3273 pci=option[,option...] [PCI] various PCI subsystem options. 3273 pci=option[,option...] [PCI] various PCI subsystem options.
3274 3274
@@ -3512,7 +3512,7 @@
3512 needed on a platform with proper driver support. 3512 needed on a platform with proper driver support.
3513 3513
3514 pd. [PARIDE] 3514 pd. [PARIDE]
3515 See Documentation/blockdev/paride.rst. 3515 See Documentation/admin-guide/blockdev/paride.rst.
3516 3516
3517 pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at 3517 pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at
3518 boot time. 3518 boot time.
@@ -3527,10 +3527,10 @@
3527 and performance comparison. 3527 and performance comparison.
3528 3528
3529 pf. [PARIDE] 3529 pf. [PARIDE]
3530 See Documentation/blockdev/paride.rst. 3530 See Documentation/admin-guide/blockdev/paride.rst.
3531 3531
3532 pg. [PARIDE] 3532 pg. [PARIDE]
3533 See Documentation/blockdev/paride.rst. 3533 See Documentation/admin-guide/blockdev/paride.rst.
3534 3534
3535 pirq= [SMP,APIC] Manual mp-table setup 3535 pirq= [SMP,APIC] Manual mp-table setup
3536 See Documentation/x86/i386/IO-APIC.rst. 3536 See Documentation/x86/i386/IO-APIC.rst.
@@ -3642,7 +3642,7 @@
3642 3642
3643 prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk 3643 prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk
3644 before loading. 3644 before loading.
3645 See Documentation/blockdev/ramdisk.rst. 3645 See Documentation/admin-guide/blockdev/ramdisk.rst.
3646 3646
3647 psi= [KNL] Enable or disable pressure stall information 3647 psi= [KNL] Enable or disable pressure stall information
3648 tracking. 3648 tracking.
@@ -3664,7 +3664,7 @@
3664 pstore.backend= Specify the name of the pstore backend to use 3664 pstore.backend= Specify the name of the pstore backend to use
3665 3665
3666 pt. [PARIDE] 3666 pt. [PARIDE]
3667 See Documentation/blockdev/paride.rst. 3667 See Documentation/admin-guide/blockdev/paride.rst.
3668 3668
3669 pti= [X86_64] Control Page Table Isolation of user and 3669 pti= [X86_64] Control Page Table Isolation of user and
3670 kernel address spaces. Disabling this feature 3670 kernel address spaces. Disabling this feature
@@ -3693,7 +3693,7 @@
3693 See Documentation/admin-guide/md.rst. 3693 See Documentation/admin-guide/md.rst.
3694 3694
3695 ramdisk_size= [RAM] Sizes of RAM disks in kilobytes 3695 ramdisk_size= [RAM] Sizes of RAM disks in kilobytes
3696 See Documentation/blockdev/ramdisk.rst. 3696 See Documentation/admin-guide/blockdev/ramdisk.rst.
3697 3697
3698 random.trust_cpu={on,off} 3698 random.trust_cpu={on,off}
3699 [KNL] Enable or disable trusting the use of the 3699 [KNL] Enable or disable trusting the use of the
generated by cgit v1.2.2 (git 2.25.0) at 2025-02-05 14:07:17 -0500