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 */
xe_guard_init(struct xe_guard * guard,const char * name)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 */
xe_guard_arm(struct xe_guard * guard,bool lockdown,void * who)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 */
xe_guard_disarm(struct xe_guard * guard,bool lockdown)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 */
xe_guard_mode_str(bool lockdown)114 static inline const char *xe_guard_mode_str(bool lockdown)
115 {
116 return lockdown ? "lockdown" : "exclusive";
117 }
118
119 #endif
120