/* SPDX-License-Identifier: MIT */
/*
 * Copyright © 2025 Intel Corporation
 */

#ifndef _XE_GUARD_H_
#define _XE_GUARD_H_

#include <linux/spinlock.h>

/**
 * struct xe_guard - Simple logic to protect a feature.
 *
 * Implements simple semaphore-like logic that can be used to lockdown the
 * feature unless it is already in use.  Allows enabling of the otherwise
 * incompatible features, where we can't follow the strict owner semantics
 * required by the &rw_semaphore.
 *
 * NOTE! It shouldn't be used to protect a data, use &rw_semaphore instead.
 */
struct xe_guard {
        /**
         * @counter: implements simple exclusive/lockdown logic:
         *           if == 0 then guard/feature is idle/not in use,
         *           if < 0 then feature is active and can't be locked-down,
         *           if > 0 then feature is lockded-down and can't be activated.
         */
        int counter;

        /** @name: the name of the guard (useful for debug) */
        const char *name;

        /** @owner: the info about the last owner of the guard (for debug) */
        void *owner;

        /** @lock: protects guard's data */
        spinlock_t lock;
};

/**
 * xe_guard_init() - Initialize the guard.
 * @guard: the &xe_guard to init
 * @name: name of the guard
 */
static inline void xe_guard_init(struct xe_guard *guard, const char *name)
{
        spin_lock_init(&guard->lock);
        guard->counter = 0;
        guard->name = name;
}

/**
 * xe_guard_arm() - Arm the guard for the exclusive/lockdown mode.
 * @guard: the &xe_guard to arm
 * @lockdown: arm for lockdown(true) or exclusive(false) mode
 * @who: optional owner info (for debug only)
 *
 * Multiple lockdown requests are allowed.
 * Only single exclusive access can be granted.
 * Will fail if the guard is already in exclusive mode.
 * On success, must call the xe_guard_disarm() to release.
 *
 * Return: 0 on success or a negative error code on failure.
 */
static inline int xe_guard_arm(struct xe_guard *guard, bool lockdown, void *who)
{
        guard(spinlock)(&guard->lock);

        if (lockdown) {
                if (guard->counter < 0)
                        return -EBUSY;
                guard->counter++;
        } else {
                if (guard->counter > 0)
                        return -EPERM;
                if (guard->counter < 0)
                        return -EUSERS;
                guard->counter--;
        }

        guard->owner = who;
        return 0;
}

/**
 * xe_guard_disarm() - Disarm the guard from exclusive/lockdown mode.
 * @guard: the &xe_guard to disarm
 * @lockdown: disarm from lockdown(true) or exclusive(false) mode
 *
 * Return: true if successfully disarmed or false in case of mismatch.
 */
static inline bool xe_guard_disarm(struct xe_guard *guard, bool lockdown)
{
        guard(spinlock)(&guard->lock);

        if (lockdown) {
                if (guard->counter <= 0)
                        return false;
                guard->counter--;
        } else {
                if (guard->counter != -1)
                        return false;
                guard->counter++;
        }
        return true;
}

/**
 * xe_guard_mode_str() - Convert guard mode into a string.
 * @lockdown: flag used to select lockdown or exclusive mode
 *
 * Return: "lockdown" or "exclusive" string.
 */
static inline const char *xe_guard_mode_str(bool lockdown)
{
        return lockdown ? "lockdown" : "exclusive";
}

#endif