← Documents Documentation/block/pr.rst GitHub 원문 ↗

Linux 6.18.37 · Block

Block layer support for Persistent Reservations

shared storage에서 initiator 접근을 제한하는 Persistent Reservations type과 block ioctl 동작을 설명합니다.

Source pathDocumentation/block/pr.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

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

1. 요약·해설

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

요약과 해설

pr.rst:1-119

Linux의 Persistent Reservations interface는 SCSI 계열 shared block device의 접근 소유권을 userspace에서 관리합니다. 등록 key를 기반으로 read·write 권한을 제한하며 reservation은 전원 손실과 multi-path connection 전체에서 유지되어야 합니다.

일반 흐름은 `IOC_PR_REGISTER`로 key를 등록하고 `IOC_PR_RESERVE`로 reservation type을 적용한 뒤, `IOC_PR_RELEASE` 또는 `IOC_PR_CLEAR`로 해제하는 것입니다. `IOC_PR_PREEMPT` 계열은 기존 소유권을 새 key로 교체하며 ABORT variant는 기존 connection의 outstanding command도 중단합니다.

`PR_FL_IGNORE_KEY` 지원 범위는 구현별로 다를 수 있고, kernel은 지원하지 않는 flag를 `-EOPNOTSUPP`로 거부합니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 ===============================================
2 Block layer support for Persistent Reservations
3 ===============================================
4
5 The Linux kernel supports a user space interface for simplified
6 Persistent Reservations which map to block devices that support
7 these (like SCSI). Persistent Reservations allow restricting
8 access to block devices to specific initiators in a shared storage
9 setup.
10
11 This document gives a general overview of the support ioctl commands.
12 For a more detailed reference please refer to the SCSI Primary
13 Commands standard, specifically the section on Reservations and the
14 "PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands.
15
16 All implementations are expected to ensure the reservations survive
17 a power loss and cover all connections in a multi path environment.
18 These behaviors are optional in SPC but will be automatically applied
19 by Linux.
20
21
22 The following types of reservations are supported:
23 --------------------------------------------------
24
25 - PR_WRITE_EXCLUSIVE
26 Only the initiator that owns the reservation can write to the
27 device. Any initiator can read from the device.
28
29 - PR_EXCLUSIVE_ACCESS
30 Only the initiator that owns the reservation can access the
31 device.
32
33 - PR_WRITE_EXCLUSIVE_REG_ONLY
34 Only initiators with a registered key can write to the device,
35 Any initiator can read from the device.
36
37 - PR_EXCLUSIVE_ACCESS_REG_ONLY
38 Only initiators with a registered key can access the device.
39
40 - PR_WRITE_EXCLUSIVE_ALL_REGS
41
42 Only initiators with a registered key can write to the device,
43 Any initiator can read from the device.
44 All initiators with a registered key are considered reservation
45 holders.
46 Please reference the SPC spec on the meaning of a reservation
47 holder if you want to use this type.
48
49 - PR_EXCLUSIVE_ACCESS_ALL_REGS
50 Only initiators with a registered key can access the device.
51 All initiators with a registered key are considered reservation
52 holders.
53 Please reference the SPC spec on the meaning of a reservation
54 holder if you want to use this type.
55
56
57 The following ioctl are supported:
58 ----------------------------------
59
60 1. IOC_PR_REGISTER
61 ^^^^^^^^^^^^^^^^^^
62
63 This ioctl command registers a new reservation if the new_key argument
64 is non-null. If no existing reservation exists old_key must be zero,
65 if an existing reservation should be replaced old_key must contain
66 the old reservation key.
67
68 If the new_key argument is 0 it unregisters the existing reservation passed
69 in old_key.
70
71
72 2. IOC_PR_RESERVE
73 ^^^^^^^^^^^^^^^^^
74
75 This ioctl command reserves the device and thus restricts access for other
76 devices based on the type argument. The key argument must be the existing
77 reservation key for the device as acquired by the IOC_PR_REGISTER,
78 IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
79
80
81 3. IOC_PR_RELEASE
82 ^^^^^^^^^^^^^^^^^
83
84 This ioctl command releases the reservation specified by key and flags
85 and thus removes any access restriction implied by it.
86
87
88 4. IOC_PR_PREEMPT
89 ^^^^^^^^^^^^^^^^^
90
91 This ioctl command releases the existing reservation referred to by
92 old_key and replaces it with a new reservation of type for the
93 reservation key new_key.
94
95
96 5. IOC_PR_PREEMPT_ABORT
97 ^^^^^^^^^^^^^^^^^^^^^^^
98
99 This ioctl command works like IOC_PR_PREEMPT except that it also aborts
100 any outstanding command sent over a connection identified by old_key.
101
102 6. IOC_PR_CLEAR
103 ^^^^^^^^^^^^^^^
104
105 This ioctl command unregisters both key and any other reservation key
106 registered with the device and drops any existing reservation.
107
108
109 Flags
110 -----
111
112 All the ioctls have a flag field. Currently only one flag is supported:
113
114 - PR_FL_IGNORE_KEY
115 Ignore the existing reservation key. This is commonly supported for
116 IOC_PR_REGISTER, and some implementation may support the flag for
117 IOC_PR_RESERVE.
118
119 For all unknown flags the kernel will return -EOPNOTSUPP.
120

3. 한국어 전문 번역

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

Persistent Reservations 지원 개요

1-19

Linux kernel은 SCSI처럼 Persistent Reservations를 지원하는 block device에 대응하는 간소화된 userspace interface를 제공합니다. Persistent Reservations를 사용하면 shared storage 구성에서 특정 initiator만 block device에 access하도록 제한할 수 있습니다.

이 문서는 지원되는 ioctl command를 전반적으로 설명합니다. 자세한 reference는 SCSI Primary Commands(SPC) 표준의 Reservations 절과 `PERSISTENT RESERVE IN`, `PERSISTENT RESERVE OUT` command를 참조하십시오.

모든 구현은 reservation이 power loss 뒤에도 유지되고 multi path 환경의 모든 connection에 적용되도록 보장해야 합니다. SPC에서는 이 동작이 선택 사항이지만 Linux는 자동으로 적용합니다.

지원하는 reservation type

20-54
  • `PR_WRITE_EXCLUSIVE`: reservation을 소유한 initiator만 device에 write할 수 있습니다. 모든 initiator가 device를 read할 수 있습니다.
  • `PR_EXCLUSIVE_ACCESS`: reservation을 소유한 initiator만 device에 access할 수 있습니다.
  • `PR_WRITE_EXCLUSIVE_REG_ONLY`: 등록된 key가 있는 initiator만 device에 write할 수 있습니다. 모든 initiator가 device를 read할 수 있습니다.
  • `PR_EXCLUSIVE_ACCESS_REG_ONLY`: 등록된 key가 있는 initiator만 device에 access할 수 있습니다.
  • `PR_WRITE_EXCLUSIVE_ALL_REGS`: 등록된 key가 있는 initiator만 device에 write할 수 있고 모든 initiator가 read할 수 있습니다. 등록된 key가 있는 모든 initiator를 reservation holder로 간주합니다. 이 type을 사용하려면 reservation holder의 의미를 SPC specification에서 확인하십시오.
  • `PR_EXCLUSIVE_ACCESS_ALL_REGS`: 등록된 key가 있는 initiator만 device에 access할 수 있습니다. 등록된 key가 있는 모든 initiator를 reservation holder로 간주합니다. 이 type을 사용하려면 reservation holder의 의미를 SPC specification에서 확인하십시오.

1. IOC_PR_REGISTER

55-69

`IOC_PR_REGISTER` ioctl command는 `new_key` argument가 null이 아니면 새 reservation을 등록합니다. 기존 reservation이 없으면 `old_key`는 `0`이어야 하고, 기존 reservation을 교체하려면 `old_key`에 이전 reservation key를 넣어야 합니다.

`new_key` argument가 `0`이면 `old_key`로 전달한 기존 reservation의 등록을 해제합니다.

2. IOC_PR_RESERVE

70-79

`IOC_PR_RESERVE` ioctl command는 device를 reserve하고 `type` argument에 따라 다른 device의 access를 제한합니다. `key` argument는 `IOC_PR_REGISTER`, `IOC_PR_REGISTER_IGNORE`, `IOC_PR_PREEMPT` 또는 `IOC_PR_PREEMPT_ABORT` command로 얻은 해당 device의 기존 reservation key여야 합니다.

3. IOC_PR_RELEASE

80-86

`IOC_PR_RELEASE` ioctl command는 `key`와 `flags`로 지정한 reservation을 release해 그 reservation이 부여한 access restriction을 제거합니다.

4-5. PREEMPT와 PREEMPT_ABORT

87-100

`IOC_PR_PREEMPT` ioctl command는 `old_key`가 가리키는 기존 reservation을 release하고, `new_key` reservation key에 대해 `type`으로 지정한 새 reservation으로 교체합니다.

`IOC_PR_PREEMPT_ABORT` ioctl command는 `IOC_PR_PREEMPT`처럼 동작하면서 `old_key`로 식별되는 connection을 통해 전송된 outstanding command도 모두 abort합니다.

6. IOC_PR_CLEAR

101-106

`IOC_PR_CLEAR` ioctl command는 `key`와 device에 등록된 다른 모든 reservation key의 등록을 해제하고, 기존 reservation도 모두 제거합니다.

Flags

107-119

모든 ioctl에는 flag field가 있습니다. 현재 지원하는 flag는 `PR_FL_IGNORE_KEY` 하나뿐입니다.

  • `PR_FL_IGNORE_KEY`: 기존 reservation key를 무시합니다. 일반적으로 `IOC_PR_REGISTER`가 이 flag를 지원하며, 일부 구현은 `IOC_PR_RESERVE`에도 이 flag를 지원할 수 있습니다.

알 수 없는 모든 flag에 대해 kernel은 `-EOPNOTSUPP`를 반환합니다.