Documentation/block/pr.txt

   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 the 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
  27         Only the initiator that owns the reservation can write to the
  28         device.  Any initiator can read from the device.
  29
  30  - PR_EXCLUSIVE_ACCESS
  31
  32         Only the initiator that owns the reservation can access the
  33         device.
  34
  35  - PR_WRITE_EXCLUSIVE_REG_ONLY
  36
  37         Only initiators with a registered key can write to the device,
  38         Any initiator can read from the device.
  39
  40  - PR_EXCLUSIVE_ACCESS_REG_ONLY
  41
  42         Only initiators with a registered key can access the device.
  43
  44  - PR_WRITE_EXCLUSIVE_ALL_REGS
  45
  46         Only initiators with a registered key can write to the device,
  47         Any initiator can read from the device.
  48         All initiators with a registered key are considered reservation
  49         holders.
  50         Please reference the SPC spec on the meaning of a reservation
  51         holder if you want to use this type.
  52
  53  - PR_EXCLUSIVE_ACCESS_ALL_REGS
  54
  55         Only initiators with a registered key can access the device.
  56         All initiators with a registered key are considered reservation
  57         holders.
  58         Please reference the SPC spec on the meaning of a reservation
  59         holder if you want to use this type.
  60
  61
  62 The following ioctl are supported:
  63 ----------------------------------
  64
  65 1. IOC_PR_REGISTER
  66
  67 This ioctl command registers a new reservation if the new_key argument
  68 is non-null.  If no existing reservation exists old_key must be zero,
  69 if an existing reservation should be replaced old_key must contain
  70 the old reservation key.
  71
  72 If the new_key argument is 0 it unregisters the existing reservation passed
  73 in old_key.
  74
  75
  76 2. IOC_PR_RESERVE
  77
  78 This ioctl command reserves the device and thus restricts access for other
  79 devices based on the type argument.  The key argument must be the existing
  80 reservation key for the device as acquired by the IOC_PR_REGISTER,
  81 IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
  82
  83
  84 3. IOC_PR_RELEASE
  85
  86 This ioctl command releases the reservation specified by key and flags
  87 and thus removes any access restriction implied by it.
  88
  89
  90 4. IOC_PR_PREEMPT
  91
  92 This ioctl command releases the existing reservation referred to by
  93 old_key and replaces it with a new reservation of type for the
  94 reservation key new_key.
  95
  96
  97 5. IOC_PR_PREEMPT_ABORT
  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 This ioctl command unregisters both key and any other reservation key
 105 registered with the device and drops any existing reservation.
 106
 107
 108 Flags
 109 -----
 110
 111 All the ioctls have a flag field.  Currently only one flag is supported:
 112
 113  - PR_FL_IGNORE_KEY
 114
 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.