David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 1 | /****************************************************************************** |
| 2 | ******************************************************************************* |
| 3 | ** |
| 4 | ** Copyright (C) Sistina Software, Inc. 1997-2003 All rights reserved. |
David Teigland | 3ae1acf | 2007-05-18 08:59:31 -0500 | [diff] [blame] | 5 | ** Copyright (C) 2004-2007 Red Hat, Inc. All rights reserved. |
David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 6 | ** |
| 7 | ** This copyrighted material is made available to anyone wishing to use, |
| 8 | ** modify, copy, or redistribute it subject to the terms and conditions |
| 9 | ** of the GNU General Public License v.2. |
| 10 | ** |
| 11 | ******************************************************************************* |
| 12 | ******************************************************************************/ |
| 13 | |
| 14 | #ifndef __DLM_DOT_H__ |
| 15 | #define __DLM_DOT_H__ |
| 16 | |
| 17 | /* |
| 18 | * Interface to Distributed Lock Manager (DLM) |
| 19 | * routines and structures to use DLM lockspaces |
| 20 | */ |
| 21 | |
| 22 | /* |
| 23 | * Lock Modes |
| 24 | */ |
| 25 | |
| 26 | #define DLM_LOCK_IV -1 /* invalid */ |
| 27 | #define DLM_LOCK_NL 0 /* null */ |
| 28 | #define DLM_LOCK_CR 1 /* concurrent read */ |
| 29 | #define DLM_LOCK_CW 2 /* concurrent write */ |
| 30 | #define DLM_LOCK_PR 3 /* protected read */ |
| 31 | #define DLM_LOCK_PW 4 /* protected write */ |
| 32 | #define DLM_LOCK_EX 5 /* exclusive */ |
| 33 | |
| 34 | /* |
| 35 | * Maximum size in bytes of a dlm_lock name |
| 36 | */ |
| 37 | |
| 38 | #define DLM_RESNAME_MAXLEN 64 |
| 39 | |
| 40 | /* |
| 41 | * Flags to dlm_lock |
| 42 | * |
| 43 | * DLM_LKF_NOQUEUE |
| 44 | * |
| 45 | * Do not queue the lock request on the wait queue if it cannot be granted |
| 46 | * immediately. If the lock cannot be granted because of this flag, DLM will |
| 47 | * either return -EAGAIN from the dlm_lock call or will return 0 from |
| 48 | * dlm_lock and -EAGAIN in the lock status block when the AST is executed. |
| 49 | * |
| 50 | * DLM_LKF_CANCEL |
| 51 | * |
| 52 | * Used to cancel a pending lock request or conversion. A converting lock is |
| 53 | * returned to its previously granted mode. |
| 54 | * |
| 55 | * DLM_LKF_CONVERT |
| 56 | * |
| 57 | * Indicates a lock conversion request. For conversions the name and namelen |
| 58 | * are ignored and the lock ID in the LKSB is used to identify the lock. |
| 59 | * |
| 60 | * DLM_LKF_VALBLK |
| 61 | * |
| 62 | * Requests DLM to return the current contents of the lock value block in the |
| 63 | * lock status block. When this flag is set in a lock conversion from PW or EX |
| 64 | * modes, DLM assigns the value specified in the lock status block to the lock |
| 65 | * value block of the lock resource. The LVB is a DLM_LVB_LEN size array |
| 66 | * containing application-specific information. |
| 67 | * |
| 68 | * DLM_LKF_QUECVT |
| 69 | * |
| 70 | * Force a conversion request to be queued, even if it is compatible with |
| 71 | * the granted modes of other locks on the same resource. |
| 72 | * |
| 73 | * DLM_LKF_IVVALBLK |
| 74 | * |
| 75 | * Invalidate the lock value block. |
| 76 | * |
| 77 | * DLM_LKF_CONVDEADLK |
| 78 | * |
| 79 | * Allows the dlm to resolve conversion deadlocks internally by demoting the |
| 80 | * granted mode of a converting lock to NL. The DLM_SBF_DEMOTED flag is |
| 81 | * returned for a conversion that's been effected by this. |
| 82 | * |
| 83 | * DLM_LKF_PERSISTENT |
| 84 | * |
| 85 | * Only relevant to locks originating in userspace. A persistent lock will not |
| 86 | * be removed if the process holding the lock exits. |
| 87 | * |
David Teigland | c85d65e | 2007-05-18 09:01:26 -0500 | [diff] [blame^] | 88 | * DLM_LKF_NODLCKWT |
| 89 | * |
| 90 | * Do not cancel the lock if it gets into conversion deadlock. |
| 91 | * Exclude this lock from being monitored due to DLM_LSFL_TIMEWARN. |
| 92 | * |
David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 93 | * DLM_LKF_NODLCKBLK |
| 94 | * |
| 95 | * net yet implemented |
| 96 | * |
| 97 | * DLM_LKF_EXPEDITE |
| 98 | * |
| 99 | * Used only with new requests for NL mode locks. Tells the lock manager |
| 100 | * to grant the lock, ignoring other locks in convert and wait queues. |
| 101 | * |
| 102 | * DLM_LKF_NOQUEUEBAST |
| 103 | * |
| 104 | * Send blocking AST's before returning -EAGAIN to the caller. It is only |
| 105 | * used along with the NOQUEUE flag. Blocking AST's are not sent for failed |
| 106 | * NOQUEUE requests otherwise. |
| 107 | * |
| 108 | * DLM_LKF_HEADQUE |
| 109 | * |
| 110 | * Add a lock to the head of the convert or wait queue rather than the tail. |
| 111 | * |
| 112 | * DLM_LKF_NOORDER |
| 113 | * |
| 114 | * Disregard the standard grant order rules and grant a lock as soon as it |
| 115 | * is compatible with other granted locks. |
| 116 | * |
| 117 | * DLM_LKF_ORPHAN |
| 118 | * |
| 119 | * not yet implemented |
| 120 | * |
| 121 | * DLM_LKF_ALTPR |
| 122 | * |
| 123 | * If the requested mode cannot be granted immediately, try to grant the lock |
| 124 | * in PR mode instead. If this alternate mode is granted instead of the |
| 125 | * requested mode, DLM_SBF_ALTMODE is returned in the lksb. |
| 126 | * |
| 127 | * DLM_LKF_ALTCW |
| 128 | * |
| 129 | * The same as ALTPR, but the alternate mode is CW. |
| 130 | * |
| 131 | * DLM_LKF_FORCEUNLOCK |
| 132 | * |
| 133 | * Unlock the lock even if it is converting or waiting or has sublocks. |
| 134 | * Only really for use by the userland device.c code. |
| 135 | * |
| 136 | */ |
| 137 | |
| 138 | #define DLM_LKF_NOQUEUE 0x00000001 |
| 139 | #define DLM_LKF_CANCEL 0x00000002 |
| 140 | #define DLM_LKF_CONVERT 0x00000004 |
| 141 | #define DLM_LKF_VALBLK 0x00000008 |
| 142 | #define DLM_LKF_QUECVT 0x00000010 |
| 143 | #define DLM_LKF_IVVALBLK 0x00000020 |
| 144 | #define DLM_LKF_CONVDEADLK 0x00000040 |
| 145 | #define DLM_LKF_PERSISTENT 0x00000080 |
| 146 | #define DLM_LKF_NODLCKWT 0x00000100 |
| 147 | #define DLM_LKF_NODLCKBLK 0x00000200 |
| 148 | #define DLM_LKF_EXPEDITE 0x00000400 |
| 149 | #define DLM_LKF_NOQUEUEBAST 0x00000800 |
| 150 | #define DLM_LKF_HEADQUE 0x00001000 |
| 151 | #define DLM_LKF_NOORDER 0x00002000 |
| 152 | #define DLM_LKF_ORPHAN 0x00004000 |
| 153 | #define DLM_LKF_ALTPR 0x00008000 |
| 154 | #define DLM_LKF_ALTCW 0x00010000 |
| 155 | #define DLM_LKF_FORCEUNLOCK 0x00020000 |
David Teigland | 3ae1acf | 2007-05-18 08:59:31 -0500 | [diff] [blame] | 156 | #define DLM_LKF_TIMEOUT 0x00040000 |
David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 157 | |
| 158 | /* |
| 159 | * Some return codes that are not in errno.h |
| 160 | */ |
| 161 | |
| 162 | #define DLM_ECANCEL 0x10001 |
| 163 | #define DLM_EUNLOCK 0x10002 |
| 164 | |
| 165 | typedef void dlm_lockspace_t; |
| 166 | |
| 167 | /* |
David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 168 | * Lock status block |
| 169 | * |
| 170 | * Use this structure to specify the contents of the lock value block. For a |
| 171 | * conversion request, this structure is used to specify the lock ID of the |
| 172 | * lock. DLM writes the status of the lock request and the lock ID assigned |
| 173 | * to the request in the lock status block. |
| 174 | * |
| 175 | * sb_lkid: the returned lock ID. It is set on new (non-conversion) requests. |
| 176 | * It is available when dlm_lock returns. |
| 177 | * |
| 178 | * sb_lvbptr: saves or returns the contents of the lock's LVB according to rules |
| 179 | * shown for the DLM_LKF_VALBLK flag. |
| 180 | * |
| 181 | * sb_flags: DLM_SBF_DEMOTED is returned if in the process of promoting a lock, |
| 182 | * it was first demoted to NL to avoid conversion deadlock. |
| 183 | * DLM_SBF_VALNOTVALID is returned if the resource's LVB is marked invalid. |
| 184 | * |
| 185 | * sb_status: the returned status of the lock request set prior to AST |
| 186 | * execution. Possible return values: |
| 187 | * |
| 188 | * 0 if lock request was successful |
| 189 | * -EAGAIN if request would block and is flagged DLM_LKF_NOQUEUE |
| 190 | * -ENOMEM if there is no memory to process request |
| 191 | * -EINVAL if there are invalid parameters |
| 192 | * -DLM_EUNLOCK if unlock request was successful |
| 193 | * -DLM_ECANCEL if a cancel completed successfully |
| 194 | */ |
| 195 | |
| 196 | #define DLM_SBF_DEMOTED 0x01 |
| 197 | #define DLM_SBF_VALNOTVALID 0x02 |
| 198 | #define DLM_SBF_ALTMODE 0x04 |
| 199 | |
| 200 | struct dlm_lksb { |
| 201 | int sb_status; |
| 202 | uint32_t sb_lkid; |
| 203 | char sb_flags; |
| 204 | char * sb_lvbptr; |
| 205 | }; |
| 206 | |
David Teigland | 3ae1acf | 2007-05-18 08:59:31 -0500 | [diff] [blame] | 207 | #define DLM_LSFL_NODIR 0x00000001 |
| 208 | #define DLM_LSFL_TIMEWARN 0x00000002 |
David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 209 | |
| 210 | #ifdef __KERNEL__ |
| 211 | |
David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 212 | /* |
| 213 | * dlm_new_lockspace |
| 214 | * |
| 215 | * Starts a lockspace with the given name. If the named lockspace exists in |
| 216 | * the cluster, the calling node joins it. |
| 217 | */ |
| 218 | |
| 219 | int dlm_new_lockspace(char *name, int namelen, dlm_lockspace_t **lockspace, |
| 220 | uint32_t flags, int lvblen); |
| 221 | |
| 222 | /* |
| 223 | * dlm_release_lockspace |
| 224 | * |
| 225 | * Stop a lockspace. |
| 226 | */ |
| 227 | |
| 228 | int dlm_release_lockspace(dlm_lockspace_t *lockspace, int force); |
| 229 | |
| 230 | /* |
| 231 | * dlm_lock |
| 232 | * |
| 233 | * Make an asyncronous request to acquire or convert a lock on a named |
| 234 | * resource. |
| 235 | * |
| 236 | * lockspace: context for the request |
| 237 | * mode: the requested mode of the lock (DLM_LOCK_) |
| 238 | * lksb: lock status block for input and async return values |
| 239 | * flags: input flags (DLM_LKF_) |
| 240 | * name: name of the resource to lock, can be binary |
| 241 | * namelen: the length in bytes of the resource name (MAX_RESNAME_LEN) |
| 242 | * parent: the lock ID of a parent lock or 0 if none |
| 243 | * lockast: function DLM executes when it completes processing the request |
| 244 | * astarg: argument passed to lockast and bast functions |
| 245 | * bast: function DLM executes when this lock later blocks another request |
| 246 | * |
| 247 | * Returns: |
| 248 | * 0 if request is successfully queued for processing |
| 249 | * -EINVAL if any input parameters are invalid |
| 250 | * -EAGAIN if request would block and is flagged DLM_LKF_NOQUEUE |
| 251 | * -ENOMEM if there is no memory to process request |
| 252 | * -ENOTCONN if there is a communication error |
| 253 | * |
| 254 | * If the call to dlm_lock returns an error then the operation has failed and |
| 255 | * the AST routine will not be called. If dlm_lock returns 0 it is still |
| 256 | * possible that the lock operation will fail. The AST routine will be called |
| 257 | * when the locking is complete and the status is returned in the lksb. |
| 258 | * |
| 259 | * If the AST routines or parameter are passed to a conversion operation then |
| 260 | * they will overwrite those values that were passed to a previous dlm_lock |
| 261 | * call. |
| 262 | * |
| 263 | * AST routines should not block (at least not for long), but may make |
| 264 | * any locking calls they please. |
| 265 | */ |
| 266 | |
| 267 | int dlm_lock(dlm_lockspace_t *lockspace, |
| 268 | int mode, |
| 269 | struct dlm_lksb *lksb, |
| 270 | uint32_t flags, |
| 271 | void *name, |
| 272 | unsigned int namelen, |
| 273 | uint32_t parent_lkid, |
| 274 | void (*lockast) (void *astarg), |
| 275 | void *astarg, |
David Teigland | 3bcd368 | 2006-02-23 09:56:38 +0000 | [diff] [blame] | 276 | void (*bast) (void *astarg, int mode)); |
David Teigland | e7fd417 | 2006-01-18 09:30:29 +0000 | [diff] [blame] | 277 | |
| 278 | /* |
| 279 | * dlm_unlock |
| 280 | * |
| 281 | * Asynchronously release a lock on a resource. The AST routine is called |
| 282 | * when the resource is successfully unlocked. |
| 283 | * |
| 284 | * lockspace: context for the request |
| 285 | * lkid: the lock ID as returned in the lksb |
| 286 | * flags: input flags (DLM_LKF_) |
| 287 | * lksb: if NULL the lksb parameter passed to last lock request is used |
| 288 | * astarg: the arg used with the completion ast for the unlock |
| 289 | * |
| 290 | * Returns: |
| 291 | * 0 if request is successfully queued for processing |
| 292 | * -EINVAL if any input parameters are invalid |
| 293 | * -ENOTEMPTY if the lock still has sublocks |
| 294 | * -EBUSY if the lock is waiting for a remote lock operation |
| 295 | * -ENOTCONN if there is a communication error |
| 296 | */ |
| 297 | |
| 298 | int dlm_unlock(dlm_lockspace_t *lockspace, |
| 299 | uint32_t lkid, |
| 300 | uint32_t flags, |
| 301 | struct dlm_lksb *lksb, |
| 302 | void *astarg); |
| 303 | |
| 304 | #endif /* __KERNEL__ */ |
| 305 | |
| 306 | #endif /* __DLM_DOT_H__ */ |
| 307 | |