Revert "revocable: Revocable resource management" (21bab791) · Commits · git / linux-net

Documentation/driver-api/driver-model/index.rst

+0 −1

Original line number	Diff line number	Diff line
		@@ -14,7 +14,6 @@ Driver Model
		overview
		platform
		porting
		revocable

		.. only:: subproject and html

Documentation/driver-api/driver-model/revocable.rst

deleted100644 → 0

+0 −149

Original line number	Diff line number	Diff line
		.. SPDX-License-Identifier: GPL-2.0

		==============================
		Revocable Resource Management
		==============================

		Overview
		========

		.. kernel-doc:: drivers/base/revocable.c
		:doc: Overview

		Revocable vs. Devres (devm)
		===========================

		It's important to understand the distinct roles of the Revocable and Devres,
		and how they can complement each other. They address different problems in
		resource management:

		* Devres: Primarily address resource leaks. The lifetime of the
		resources is tied to the lifetime of the device. The resource is
		automatically freed when the device is unbound. This cleanup happens
		irrespective of any potential active users.

		* Revocable: Primarily addresses invalid memory access,
		such as Use-After-Free (UAF). It's an independent synchronization
		primitive that decouples consumer access from the resource's actual
		presence. Consumers interact with a "revocable object" (an intermediary),
		not the underlying resource directly. This revocable object persists as
		long as there are active references to it from consumer handles.

		Key Distinctions & How They Complement Each Other:

		1. Reference Target: Consumers of a resource managed by the Revocable
		mechanism hold a reference to the revocable object, not the
		encapsulated resource itself.

		2. Resource Lifetime vs. Access: The underlying resource's lifetime is
		independent of the number of references to the revocable object. The
		resource can be freed at any point. A common scenario is the resource
		being freed by `devres` when the providing device is unbound.

		3. Safe Access: Revocable provides a safe way to attempt access. Before
		using the resource, a consumer uses the Revocable API (e.g.,
		revocable_try_access()). This function checks if the resource is still
		valid. It returns a pointer to the resource only if it hasn't been
		revoked; otherwise, it returns NULL. This prevents UAF by providing a
		clear signal that the resource is gone.

		4. Complementary Usage: `devres` and Revocable work well together.
		`devres` can handle the automatic allocation and deallocation of a
		resource tied to a device. The Revocable mechanism can be layered on top
		to provide safe access for consumers whose lifetimes might extend beyond
		the provider device's lifetime. For instance, a userspace program might
		keep a character device file open even after the physical device has been
		removed. In this case:

		* `devres` frees the device-specific resource upon unbinding.
		* The Revocable mechanism ensures that any subsequent operations on the
		open file handle, which attempt to access the now-freed resource,
		will fail gracefully (e.g., revocable_try_access() returns NULL)
		instead of causing a UAF.

		In summary, `devres` ensures resources are released to prevent leaks, while
		the Revocable mechanism ensures that attempts to access these resources are
		done safely, even if the resource has been released.

		API and Usage
		=============

		For Resource Providers
		----------------------
		.. kernel-doc:: drivers/base/revocable.c
		:identifiers: revocable_provider

		.. kernel-doc:: drivers/base/revocable.c
		:identifiers: revocable_provider_alloc

		.. kernel-doc:: drivers/base/revocable.c
		:identifiers: revocable_provider_revoke

		For Resource Consumers
		----------------------
		.. kernel-doc:: include/linux/revocable.h
		:identifiers: revocable

		.. kernel-doc:: drivers/base/revocable.c
		:identifiers: revocable_init

		.. kernel-doc:: drivers/base/revocable.c
		:identifiers: revocable_deinit

		.. kernel-doc:: drivers/base/revocable.c
		:identifiers: revocable_try_access

		.. kernel-doc:: drivers/base/revocable.c
		:identifiers: revocable_withdraw_access

		.. kernel-doc:: include/linux/revocable.h
		:identifiers: REVOCABLE_TRY_ACCESS_WITH

		Example Usage
		~~~~~~~~~~~~~

		.. code-block:: c

		void consumer_use_resource(struct revocable_provider *rp)
		{
		struct foo_resource *res;

		REVOCABLE_TRY_ACCESS_WITH(rp, res);
		// Always check if the resource is valid.
		if (!res) {
		pr_warn("Resource is not available\n");
		return;
		}

		// At this point, 'res' is guaranteed to be valid until
		// this block exits.
		do_something_with(res);

		} // revocable_withdraw_access() is automatically called here.

		.. kernel-doc:: include/linux/revocable.h
		:identifiers: REVOCABLE_TRY_ACCESS_SCOPED

		Example Usage
		~~~~~~~~~~~~~

		.. code-block:: c

		void consumer_use_resource(struct revocable_provider *rp)
		{
		struct foo_resource *res;

		REVOCABLE_TRY_ACCESS_SCOPED(rp, res) {
		// Always check if the resource is valid.
		if (!res) {
		pr_warn("Resource is not available\n");
		return;
		}

		// At this point, 'res' is guaranteed to be valid until
		// this block exits.
		do_something_with(res);
		}

		// revocable_withdraw_access() is automatically called here.
		}

MAINTAINERS

+0 −7

Original line number	Diff line number	Diff line
		@@ -22385,13 +22385,6 @@ F: include/uapi/linux/rseq.h
		F: kernel/rseq.c
		F: tools/testing/selftests/rseq/

		REVOCABLE RESOURCE MANAGEMENT
		M: Tzung-Bi Shih <tzungbi@kernel.org>
		L: linux-kernel@vger.kernel.org
		S: Maintained
		F: drivers/base/revocable.c
		F: include/linux/revocable.h

		RFKILL
		M: Johannes Berg <johannes@sipsolutions.net>
		L: linux-wireless@vger.kernel.org

drivers/base/revocable.c

deleted100644 → 0

+0 −225

Original line number	Diff line number	Diff line
		// SPDX-License-Identifier: GPL-2.0
		/*
		* Copyright 2026 Google LLC
		*
		* Revocable resource management
		*/

		#include <linux/device.h>
		#include <linux/kref.h>
		#include <linux/revocable.h>
		#include <linux/slab.h>
		#include <linux/srcu.h>

		/**
		* DOC: Overview
		*
		* The "revocable" mechanism is a synchronization primitive designed to manage
		* safe access to resources that can be asynchronously removed or invalidated.
		* Its primary purpose is to prevent Use-After-Free (UAF) errors when
		* interacting with resources whose lifetimes are not guaranteed to outlast
		* their consumers.
		*
		* This is particularly useful in systems where resources can disappear
		* unexpectedly, such as those provided by hot-pluggable devices like USB.
		* When a consumer holds a reference to such a resource, the underlying device
		* might be removed, causing the resource's memory to be freed. Subsequent
		* access attempts by the consumer would then lead to UAF errors.
		*
		* Revocable addresses this by providing a form of "weak reference" and a
		* controlled access method. It allows a resource consumer to safely attempt to
		* access the resource. The mechanism guarantees that any access granted is
		* valid for the duration of its use. If the resource has already been
		* revoked (i.e., freed), the access attempt will fail safely, typically by
		* returning NULL, instead of causing a crash.
		*
		* The implementation uses a provider/consumer model built on Sleepable
		* RCU (SRCU) to guarantee safe memory access:
		*
		* - A resource provider, such as a driver for a hot-pluggable device,
		* allocates a struct revocable_provider and initializes it with a pointer
		* to the resource.
		*
		* - A resource consumer that wants to access the resource allocates a
		* struct revocable which acts as a handle containing a reference to the
		* provider.
		*
		* - To access the resource, the consumer uses revocable_try_access().
		* This function enters an SRCU read-side critical section and returns
		* the pointer to the resource. If the provider has already freed the
		* resource, it returns NULL. After use, the consumer calls
		* revocable_withdraw_access() to exit the SRCU critical section. The
		* REVOCABLE_TRY_ACCESS_WITH() and REVOCABLE_TRY_ACCESS_SCOPED() are
		* convenient helpers for doing that.
		*
		* - When the provider needs to remove the resource, it calls
		* revocable_provider_revoke(). This function sets the internal resource
		* pointer to NULL and then calls synchronize_srcu() to wait for all
		* current readers to finish before the resource can be completely torn
		* down.
		*/

		/**
		* struct revocable_provider - A handle for resource provider.
		* @srcu: The SRCU to protect the resource.
		* @res: The pointer of resource. It can point to anything.
		* @kref: The refcount for this handle.
		* @rcu: The RCU to protect pointer to itself.
		*/
		struct revocable_provider {
		struct srcu_struct srcu;
		void __rcu *res;
		struct kref kref;
		struct rcu_head rcu;
		};

		/**
		* revocable_provider_alloc() - Allocate struct revocable_provider.
		* @res: The pointer of resource.
		*
		* This holds an initial refcount to the struct.
		*
		* Return: The pointer of struct revocable_provider. NULL on errors.
		* It enforces the caller handles the returned pointer in RCU ways.
		*/
		struct revocable_provider __rcu revocable_provider_alloc(void res)
		{
		struct revocable_provider *rp;

		rp = kzalloc(sizeof(*rp), GFP_KERNEL);
		if (!rp)
		return NULL;

		init_srcu_struct(&rp->srcu);
		RCU_INIT_POINTER(rp->res, res);
		kref_init(&rp->kref);

		return (struct revocable_provider __rcu *)rp;
		}
		EXPORT_SYMBOL_GPL(revocable_provider_alloc);

		static void revocable_provider_release(struct kref *kref)
		{
		struct revocable_provider *rp = container_of(kref,
		struct revocable_provider, kref);

		cleanup_srcu_struct(&rp->srcu);
		kfree_rcu(rp, rcu);
		}

		/**
		* revocable_provider_revoke() - Revoke the managed resource.
		* @rp_ptr: The pointer of pointer of resource provider.
		*
		* This sets the resource `(struct revocable_provider *)->res` to NULL to
		* indicate the resource has gone.
		*
		* This drops the refcount to the resource provider. If it is the final
		* reference, revocable_provider_release() will be called to free the struct.
		*
		* It enforces the caller to pass a pointer of pointer of resource provider so
		* that it sets \*rp_ptr to NULL to prevent from keeping a dangling pointer.
		*/
		void revocable_provider_revoke(struct revocable_provider __rcu **rp_ptr)
		{
		struct revocable_provider *rp;

		rp = rcu_replace_pointer(*rp_ptr, NULL, 1);
		if (!rp)
		return;

		rcu_assign_pointer(rp->res, NULL);
		synchronize_srcu(&rp->srcu);
		kref_put(&rp->kref, revocable_provider_release);
		}
		EXPORT_SYMBOL_GPL(revocable_provider_revoke);

		/**
		* revocable_init() - Initialize struct revocable.
		* @_rp: The pointer of resource provider.
		* @rev: The pointer of resource consumer.
		*
		* This holds a refcount to the resource provider.
		*
		* Return: 0 on success, -errno otherwise.
		*/
		int revocable_init(struct revocable_provider __rcu _rp, struct revocable rev)
		{
		struct revocable_provider *rp;

		if (!_rp)
		return -ENODEV;

		/*
		* Enter a read-side critical section.
		*
		* This prevents kfree_rcu() from freeing the struct revocable_provider
		* memory, for the duration of this scope.
		*/
		scoped_guard(rcu) {
		rp = rcu_dereference(_rp);
		if (!rp)
		/* The revocable provider has been revoked. */
		return -ENODEV;

		if (!kref_get_unless_zero(&rp->kref))
		/*
		* The revocable provider is releasing (i.e.,
		* revocable_provider_release() has been called).
		*/
		return -ENODEV;
		}
		/* At this point, `rp` is safe to access as holding a kref of it */

		rev->rp = rp;
		return 0;
		}
		EXPORT_SYMBOL_GPL(revocable_init);

		/**
		* revocable_deinit() - Deinitialize struct revocable.
		* @rev: The pointer of struct revocable.
		*
		* This drops a refcount to the resource provider. If it is the final
		* reference, revocable_provider_release() will be called to free the struct.
		*/
		void revocable_deinit(struct revocable *rev)
		{
		struct revocable_provider *rp = rev->rp;

		kref_put(&rp->kref, revocable_provider_release);
		}
		EXPORT_SYMBOL_GPL(revocable_deinit);

		/**
		* revocable_try_access() - Try to access the resource.
		* @rev: The pointer of struct revocable.
		*
		* This tries to de-reference to the resource and enters a RCU critical
		* section.
		*
		* Return: The pointer to the resource. NULL if the resource has gone.
		*/
		void revocable_try_access(struct revocable rev) __acquires(&rev->rp->srcu)
		{
		struct revocable_provider *rp = rev->rp;

		rev->idx = srcu_read_lock(&rp->srcu);
		return srcu_dereference(rp->res, &rp->srcu);
		}
		EXPORT_SYMBOL_GPL(revocable_try_access);

		/**
		* revocable_withdraw_access() - Stop accessing to the resource.
		* @rev: The pointer of struct revocable.
		*
		* Call this function to indicate the resource is no longer used. It exits
		* the RCU critical section.
		*/
		void revocable_withdraw_access(struct revocable *rev) __releases(&rev->rp->srcu)
		{
		struct revocable_provider *rp = rev->rp;

		srcu_read_unlock(&rp->srcu, rev->idx);
		}
		EXPORT_SYMBOL_GPL(revocable_withdraw_access);

include/linux/revocable.h

deleted100644 → 0

+0 −89

Original line number	Diff line number	Diff line
		/* SPDX-License-Identifier: GPL-2.0 */
		/*
		* Copyright 2026 Google LLC
		*/

		#ifndef __LINUX_REVOCABLE_H
		#define __LINUX_REVOCABLE_H

		#include <linux/compiler.h>
		#include <linux/cleanup.h>

		struct device;
		struct revocable_provider;

		/**
		* struct revocable - A handle for resource consumer.
		* @rp: The pointer of resource provider.
		* @idx: The index for the RCU critical section.
		*/
		struct revocable {
		struct revocable_provider *rp;
		int idx;
		};

		struct revocable_provider __rcu revocable_provider_alloc(void res);
		void revocable_provider_revoke(struct revocable_provider __rcu **rp);

		int revocable_init(struct revocable_provider __rcu rp, struct revocable rev);
		void revocable_deinit(struct revocable *rev);
		void revocable_try_access(struct revocable rev) __acquires(&rev->rp->srcu);
		void revocable_withdraw_access(struct revocable *rev) __releases(&rev->rp->srcu);

		DEFINE_FREE(access_rev, struct revocable *, {
		if ((_T)->idx != -1)
		revocable_withdraw_access(_T);
		if ((_T)->rp)
		revocable_deinit(_T);
		})

		#define _REVOCABLE_TRY_ACCESS_WITH(_rp, _rev, _res) \
		struct revocable _rev = {.rp = NULL, .idx = -1}; \
		struct revocable *__UNIQUE_ID(name) __free(access_rev) = &_rev; \
		_res = revocable_init(_rp, &_rev) ? NULL : revocable_try_access(&_rev)

		/**
		* REVOCABLE_TRY_ACCESS_WITH() - A helper for accessing revocable resource
		* @_rp: The provider's ``struct revocable_provider *`` handle.
		* @_res: A pointer variable that will be assigned the resource.
		*
		* The macro simplifies the access-release cycle for consumers, ensuring that
		* corresponding revocable_withdraw_access() and revocable_deinit() are called,
		* even in the case of an early exit.
		*
		* It creates a local variable in the current scope. @_res is populated with
		* the result of revocable_try_access(). The consumer code must check if
		* @_res is ``NULL`` before using it. The revocable_withdraw_access() function
		* is automatically called when the scope is exited.
		*
		* Note: It shares the same issue with guard() in cleanup.h. No goto statements
		* are allowed before the helper. Otherwise, the compiler fails with
		* "jump bypasses initialization of variable with __attribute__((cleanup))".
		*/
		#define REVOCABLE_TRY_ACCESS_WITH(_rp, _res) \
		_REVOCABLE_TRY_ACCESS_WITH(_rp, __UNIQUE_ID(name), _res)

		#define _REVOCABLE_TRY_ACCESS_SCOPED(_rp, _rev, _label, _res) \
		for (struct revocable _rev = {.rp = NULL, .idx = -1}, \
		*__UNIQUE_ID(name) __free(access_rev) = &_rev; \
		(_res = revocable_init(_rp, &_rev) ? NULL : \
		revocable_try_access(&_rev)) \|\| true; \
		({ goto _label; })) \
		if (0) { \
		_label: \
		break; \
		} else

		/**
		* REVOCABLE_TRY_ACCESS_SCOPED() - A helper for accessing revocable resource
		* @_rp: The provider's ``struct revocable_provider *`` handle.
		* @_res: A pointer variable that will be assigned the resource.
		*
		* Similar to REVOCABLE_TRY_ACCESS_WITH() but with an explicit scope from a
		* temporary ``for`` loop.
		*/
		#define REVOCABLE_TRY_ACCESS_SCOPED(_rp, _res) \
		_REVOCABLE_TRY_ACCESS_SCOPED(_rp, __UNIQUE_ID(name), \
		__UNIQUE_ID(label), _res)

		#endif /* __LINUX_REVOCABLE_H */