1 /* SPDX-License-Identifier: MIT */ 2 /* 3 * Copyright © 2025 Intel Corporation 4 */ 5 6 #ifndef _XE_GUARD_H_ 7 #define _XE_GUARD_H_ 8 9 #include <linux/spinlock.h> 10 11 /** 12 * struct xe_guard - Simple logic to protect a feature. 13 * 14 * Implements simple semaphore-like logic that can be used to lockdown the 15 * feature unless it is already in use. Allows enabling of the otherwise 16 * incompatible features, where we can't follow the strict owner semantics 17 * required by the &rw_semaphore. 18 * 19 * NOTE! It shouldn't be used to protect a data, use &rw_semaphore instead. 20 */ 21 struct xe_guard { 22 /** 23 * @counter: implements simple exclusive/lockdown logic: 24 * if == 0 then guard/feature is idle/not in use, 25 * if < 0 then feature is active and can't be locked-down, 26 * if > 0 then feature is lockded-down and can't be activated. 27 */ 28 int counter; 29 30 /** @name: the name of the guard (useful for debug) */ 31 const char *name; 32 33 /** @owner: the info about the last owner of the guard (for debug) */ 34 void *owner; 35 36 /** @lock: protects guard's data */ 37 spinlock_t lock; 38 }; 39 40 /** 41 * xe_guard_init() - Initialize the guard. 42 * @guard: the &xe_guard to init 43 * @name: name of the guard 44 */ 45 static inline void xe_guard_init(struct xe_guard *guard, const char *name) 46 { 47 spin_lock_init(&guard->lock); 48 guard->counter = 0; 49 guard->name = name; 50 } 51 52 /** 53 * xe_guard_arm() - Arm the guard for the exclusive/lockdown mode. 54 * @guard: the &xe_guard to arm 55 * @lockdown: arm for lockdown(true) or exclusive(false) mode 56 * @who: optional owner info (for debug only) 57 * 58 * Multiple lockdown requests are allowed. 59 * Only single exclusive access can be granted. 60 * Will fail if the guard is already in exclusive mode. 61 * On success, must call the xe_guard_disarm() to release. 62 * 63 * Return: 0 on success or a negative error code on failure. 64 */ 65 static inline int xe_guard_arm(struct xe_guard *guard, bool lockdown, void *who) 66 { 67 guard(spinlock)(&guard->lock); 68 69 if (lockdown) { 70 if (guard->counter < 0) 71 return -EBUSY; 72 guard->counter++; 73 } else { 74 if (guard->counter > 0) 75 return -EPERM; 76 if (guard->counter < 0) 77 return -EUSERS; 78 guard->counter--; 79 } 80 81 guard->owner = who; 82 return 0; 83 } 84 85 /** 86 * xe_guard_disarm() - Disarm the guard from exclusive/lockdown mode. 87 * @guard: the &xe_guard to disarm 88 * @lockdown: disarm from lockdown(true) or exclusive(false) mode 89 * 90 * Return: true if successfully disarmed or false in case of mismatch. 91 */ 92 static inline bool xe_guard_disarm(struct xe_guard *guard, bool lockdown) 93 { 94 guard(spinlock)(&guard->lock); 95 96 if (lockdown) { 97 if (guard->counter <= 0) 98 return false; 99 guard->counter--; 100 } else { 101 if (guard->counter != -1) 102 return false; 103 guard->counter++; 104 } 105 return true; 106 } 107 108 /** 109 * xe_guard_mode_str() - Convert guard mode into a string. 110 * @lockdown: flag used to select lockdown or exclusive mode 111 * 112 * Return: "lockdown" or "exclusive" string. 113 */ 114 static inline const char *xe_guard_mode_str(bool lockdown) 115 { 116 return lockdown ? "lockdown" : "exclusive"; 117 } 118 119 #endif 120