xe_guard.h

  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 */
 21struct 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 */
 45static 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 */
 65static 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 */
 92static 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 */
114static inline const char *xe_guard_mode_str(bool lockdown)
115{
116	return lockdown ? "lockdown" : "exclusive";
117}
118
119#endif