Skip to contentSkip to conversation

hazptrtorture: Fix hazptr ownership issue

PATCH In review Mathieu Desnoyers 3 participants 20 messages Jul 9 – Jul 14 RCU

lore
Share & tools
lore

Mathieu Desnoyers

author reviewer
#0 lore raw

PATCH 1/2 hazptrtorture: Fix hazptr ownership issue

hazptr_torture_acquire is invoked from IPI on remote CPUs. It needs to immediately detach the hazptr from its local task so it can be released from other tasks.

Without this fix, the hazptrtorture test fails loudly with a OOPS. It passes with the fix applied.

[ This applies on top of linux-rcu dev branch at
commit e5ee2ea2d00ae5a0ca53ccf9c9100f2357e1bd08 ]

---
 kernel/rcu/hazptrtorture.c | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)
kernel/rcu/hazptrtorture.c +13 -1
index 5e7cb594f9e0..4507d0f09b8c 100644
@@ -370,6 +370,11 @@ static void hazptr_torture_acquire(void *hppp_in)
 	struct hazptr_pending *hppp = hppp_in;
 
 	hppp->hpp_htp = cur_ops->readlock(&hppp->hpp_hc);
+	/*
+	 * Acquiring a hazard pointer from a remote CPU.
+	 * Detach hazptr from its task so it can be released by another task.
+	 */
+	hazptr_detach_from_task(&hppp->hpp_hc);
 	atomic_long_inc(per_cpu_ptr(&hazptr_torture_acquires_irq, raw_smp_processor_id()));
 }
 
@@ -411,6 +416,10 @@ hazptr_torture_reader_tail(struct hazptr_pending *hppp, struct torture_random_st
 	preempt_enable();
 	if (irq_release && !(torture_random(trsp) % irq_release)) {
 		guard(preempt)();
+		/*
+		 * Handling release from a remote CPU.
+		 * Detach hazptr from its task so it can be released by another task.
+		 */
 		hazptr_detach_from_task(&hppp->hpp_hc);
 		cpu = cpumask_next_wrap(smp_processor_id(), cpu_online_mask);
 		smp_call_function_single(cpu, hazptr_torture_release, hppp, 1);
@@ -428,8 +437,11 @@ static void hazptr_torture_defer(struct hazptr_pending *hppp, struct torture_ran
 	int cpu = torture_random(trsp) % nr_cpu_ids;
 	struct llist_head *llhp;
 
-	hazptr_detach_from_task(&hppp->hpp_hc);
 	guard(preempt)();
+	/*
+	 * Handling release from a remote CPU.
+	 * Detach hazptr from its task so it can be released by another task.
+	 */
 	hazptr_detach_from_task(&hppp->hpp_hc);
 	cpu = cpumask_next_wrap(cpu, cpu_online_mask);
 	llhp = per_cpu_ptr(&hazptr_pending, cpu);
Signature · 1 line
2.43.0
author reviewer
#1 lore raw

PATCH 2/2 hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Introduce Hazard Pointers debug assert, which detects misuse of hazard pointers, namely failure to detach the hazard pointer from its owner thread before releasing it from a different thread.

Prints the following to the console when a failure is detected:

Hazard Pointer (addr=000000006885a05f) released on remote task without being detached from task. Acquire: caller=hazptr_torture_read_lock+0x43/0xa0 [hazptrtorture], pid=3727, cpu=1. Release: pid=3725, cpu=139.

WARNING: ./include/linux/hazptr.h:225 at hazptr_torture_read_unlock+0x68/0xf0 [hazptrtorture], CPU#139: hazptr_torture_/3725
Modules linked in: hazptrtorture torture nft_masq nft_chain_nat nf_nat nf_conntrack nf_defrag_ipv6 nf_defrag_ipv4 nf_tables nfnetlink
CPU: 139 UID: 0 PID: 3725 Comm: hazptr_torture_ Not tainted 7.1.0-rc4+ #9 PREEMPT(full)
Hardware name: QEMU Standard PC (Q35 + ICH9, 2009), BIOS 1.16.3-debian-1.16.3-2 04/01/2014
RIP: 0010:hazptr_torture_read_unlock+0x74/0xf0 [hazptrtorture]
Code: 74 31 8b 4f 40 4c 8b 43 48 49 c7 c2 22 c9 56 c0 48 c7 c7 3b c9 56 c0 4c 8d 1d b8 32 f1 ff 52 48 89 fa 4c 89 df 50 51 4c 89 d1 <67> 48 0f b9 3a 48 83 c4 18 48 8b 03 48 8d 53 18 48 c7 00 00 00 00
RSP: 0018:ff621a2a479b3de0 EFLAGS: 00010293
RAX: 0000000000000e8d RBX: ff12ea30d3913488 RCX: ffffffffc056c922
RDX: ffffffffc056c93b RSI: ffffffffc0562280 RDI: ffffffffc0562030
RBP: ff621a2a479b3e50 R08: ffffffffc064ee53 R09: 0000000000000e8f
R10: ffffffffc056c922 R11: ffffffffc0562030 R12: 0000000000000000
R13: ffffffffc0562280 R14: ff12ea30d3913488 R15: ff621a2a479b3e50
FS:  0000000000000000(0000) GS:ff12ea5011a84000(0000) knlGS:0000000000000000
CS:  0010 DS: 0000 ES: 0000 CR0: 0000000080050033
CR2: 00007f39b6e4b010 CR3: 0000000114c6e005 CR4: 0000000000771ef0
PKRU: 55555554
Call Trace:
 <TASK>
 hazptr_torture_reader_tail+0x8e/0x210 [hazptrtorture]
 hazptr_torture_reader+0x145/0xb30 [hazptrtorture]
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? set_cpus_allowed_ptr+0x36/0x60
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? __pfx_hazptr_torture_reader+0x10/0x10 [hazptrtorture]
 kthread+0xdf/0x120
 ? __pfx_kthread+0x10/0x10
 ret_from_fork+0x216/0x2d0
 ? __pfx_kthread+0x10/0x10
 ret_from_fork_asm+0x1a/0x30
 </TASK>
---[ end trace 0000000000000000 ]---
---
 include/linux/hazptr.h   | 38 ++++++++++++++++++++++++++++++++++++++
 kernel/rcu/Kconfig.debug |  9 +++++++++
 2 files changed, 47 insertions(+)
include/linux/hazptr.h +38 -0
index d96414575739..c5aa4fb03b11 100644
@@ -51,6 +51,11 @@ struct hazptr_ctx {
 	/* Backup slot in case all per-CPU slots are used. */
 	struct hazptr_backup_slot backup_slot;
 	struct hlist_node preempt_node;
+#ifdef CONFIG_HAZPTR_DEBUG
+	bool detach_task, detach_cpu;	/* Whether the ctx has been detached from task/cpu. */
+	int acquire_pid, acquire_cpu;	/* Note the task and cpu number at acquire. */
+	unsigned long acquire_caller;	/* Acquire instruction pointer. */
+#endif
 };
 
 struct hazptr_slot_ctx {
@@ -127,6 +132,9 @@ void hazptr_detach_from_task(struct hazptr_ctx *ctx)
 	struct hazptr_slot *slot;
 
 	guard(preempt)();
+#ifdef CONFIG_HAZPTR_DEBUG
+	ctx->detach_task = ctx->detach_cpu = true;
+#endif
 	slot = ctx->slot;
 	if (unlikely(hazptr_slot_is_backup(ctx, slot)))
 		return;
@@ -145,6 +153,9 @@ void hazptr_note_context_switch(void)
 
 		if (!slot->addr)
 			continue;
+#ifdef CONFIG_HAZPTR_DEBUG
+		item->ctx.ctx->detach_cpu = true;
+#endif
 		hazptr_promote_to_backup_slot(item->ctx.ctx, slot);
 	}
 }
@@ -173,6 +184,12 @@ void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
 	percpu_slots = this_cpu_ptr(&hazptr_percpu_slots);
 	slot_item = &percpu_slots->items[0];
 	slot = &slot_item->slot;
+#ifdef CONFIG_HAZPTR_DEBUG
+	ctx->detach_cpu = ctx->detach_task = false;
+	ctx->acquire_pid = current->pid;
+	ctx->acquire_cpu = smp_processor_id();
+	ctx->acquire_caller = _THIS_IP_;
+#endif
 	if (unlikely(slot->addr))
 		return __hazptr_acquire(ctx, addr_p);
 	WRITE_ONCE(slot->addr, HAZPTR_WILDCARD);	/* Store B */
@@ -196,6 +213,26 @@ void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
 	return addr;
 }
 
+#ifdef CONFIG_HAZPTR_DEBUG
+/* Called with preemption disabled. */
+static inline
+void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
+{
+	int pid = current->pid, cpu = smp_processor_id();
+	bool warn_remote_cpu = !ctx->detach_cpu && ctx->acquire_cpu != cpu,
+	     warn_remote_task = !ctx->detach_task && ctx->acquire_pid != pid;
+
+	WARN_ONCE(warn_remote_cpu || warn_remote_task,
+		"Hazard Pointer (addr=%p) released on remote %s without %s. Acquire: caller=%pS, pid=%d, cpu=%d. Release: pid=%d, cpu=%d.",
+		addr,
+		warn_remote_task ? "task" : "cpu",
+		warn_remote_task ? "being detached from task" : "context switch",
+		(void *) ctx->acquire_caller, ctx->acquire_pid, ctx->acquire_cpu, pid, cpu);
+}
+#else
+static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
+#endif
+
 /* Release the protected hazard pointer from @slot. */
 static inline
 void hazptr_release(struct hazptr_ctx *ctx, void *addr)
@@ -205,6 +242,7 @@ void hazptr_release(struct hazptr_ctx *ctx, void *addr)
 	if (!addr)
 		return;
 	guard(preempt)();
+	hazptr_release_debug(ctx, addr);
 	slot = ctx->slot;
 	smp_store_release(&slot->addr, NULL);
 	if (unlikely(hazptr_slot_is_backup(ctx, slot)))
kernel/rcu/Kconfig.debug +9 -0
index 7629c345b0b6..57fec4444a97 100644
@@ -264,4 +264,13 @@ config TRIVIAL_PREEMPT_RCU
 
 	  This has no value for production and is only for testing.
 
+config HAZPTR_DEBUG
+	bool "Provide debugging asserts for Hazard Pointers"
+	depends on DEBUG_KERNEL
+	default n
+	help
+	  This option provides consistency checks for Hazard pointers.
+
+	  Say Y here if you want to enable those assert, N otherwise.
+
 endmenu # "RCU Debugging"
Signature · 1 line
2.43.0
maintainer
#2 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 5 lines · Mathieu Desnoyers

Introduce Hazard Pointers debug assert, which detects misuse of hazard pointers, namely failure to detach the hazard pointer from its owner thread before releasing it from a different thread.

Prints the following to the console when a failure is detected:

Thank you, Mathieu!

I am testing this one first to verify the debugging, and then I will test the patch 1/2 hazptrtorture.c changes to verify the fix.

We are going to need to carefully document the hazard-pointer handling rules! ;-)

Thanx, Paul

Quoted 145 lines

Hazard Pointer (addr=000000006885a05f) released on remote task without being detached from task. Acquire: caller=hazptr_torture_read_lock+0x43/0xa0 [hazptrtorture], pid=3727, cpu=1. Release: pid=3725, cpu=139.

WARNING: ./include/linux/hazptr.h:225 at hazptr_torture_read_unlock+0x68/0xf0 [hazptrtorture], CPU#139: hazptr_torture_/3725
Modules linked in: hazptrtorture torture nft_masq nft_chain_nat nf_nat nf_conntrack nf_defrag_ipv6 nf_defrag_ipv4 nf_tables nfnetlink
CPU: 139 UID: 0 PID: 3725 Comm: hazptr_torture_ Not tainted 7.1.0-rc4+ #9 PREEMPT(full)
Hardware name: QEMU Standard PC (Q35 + ICH9, 2009), BIOS 1.16.3-debian-1.16.3-2 04/01/2014
RIP: 0010:hazptr_torture_read_unlock+0x74/0xf0 [hazptrtorture]
Code: 74 31 8b 4f 40 4c 8b 43 48 49 c7 c2 22 c9 56 c0 48 c7 c7 3b c9 56 c0 4c 8d 1d b8 32 f1 ff 52 48 89 fa 4c 89 df 50 51 4c 89 d1 <67> 48 0f b9 3a 48 83 c4 18 48 8b 03 48 8d 53 18 48 c7 00 00 00 00
RSP: 0018:ff621a2a479b3de0 EFLAGS: 00010293
RAX: 0000000000000e8d RBX: ff12ea30d3913488 RCX: ffffffffc056c922
RDX: ffffffffc056c93b RSI: ffffffffc0562280 RDI: ffffffffc0562030
RBP: ff621a2a479b3e50 R08: ffffffffc064ee53 R09: 0000000000000e8f
R10: ffffffffc056c922 R11: ffffffffc0562030 R12: 0000000000000000
R13: ffffffffc0562280 R14: ff12ea30d3913488 R15: ff621a2a479b3e50
FS:  0000000000000000(0000) GS:ff12ea5011a84000(0000) knlGS:0000000000000000
CS:  0010 DS: 0000 ES: 0000 CR0: 0000000080050033
CR2: 00007f39b6e4b010 CR3: 0000000114c6e005 CR4: 0000000000771ef0
PKRU: 55555554
Call Trace:
 <TASK>
 hazptr_torture_reader_tail+0x8e/0x210 [hazptrtorture]
 hazptr_torture_reader+0x145/0xb30 [hazptrtorture]
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? set_cpus_allowed_ptr+0x36/0x60
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? __pfx_hazptr_torture_reader+0x10/0x10 [hazptrtorture]
 kthread+0xdf/0x120
 ? __pfx_kthread+0x10/0x10
 ret_from_fork+0x216/0x2d0
 ? __pfx_kthread+0x10/0x10
 ret_from_fork_asm+0x1a/0x30
 </TASK>
---[ end trace 0000000000000000 ]---
---
 include/linux/hazptr.h   | 38 ++++++++++++++++++++++++++++++++++++++
 kernel/rcu/Kconfig.debug |  9 +++++++++
 2 files changed, 47 insertions(+)
include/linux/hazptr.h +38 -0
index d96414575739..c5aa4fb03b11 100644
@@ -51,6 +51,11 @@ struct hazptr_ctx {
 	/* Backup slot in case all per-CPU slots are used. */
 	struct hazptr_backup_slot backup_slot;
 	struct hlist_node preempt_node;
+#ifdef CONFIG_HAZPTR_DEBUG
+	bool detach_task, detach_cpu;	/* Whether the ctx has been detached from task/cpu. */
+	int acquire_pid, acquire_cpu;	/* Note the task and cpu number at acquire. */
+	unsigned long acquire_caller;	/* Acquire instruction pointer. */
+#endif
 };
 
 struct hazptr_slot_ctx {
@@ -127,6 +132,9 @@ void hazptr_detach_from_task(struct hazptr_ctx *ctx)
 	struct hazptr_slot *slot;
 
 	guard(preempt)();
+#ifdef CONFIG_HAZPTR_DEBUG
+	ctx->detach_task = ctx->detach_cpu = true;
+#endif
 	slot = ctx->slot;
 	if (unlikely(hazptr_slot_is_backup(ctx, slot)))
 		return;
@@ -145,6 +153,9 @@ void hazptr_note_context_switch(void)
 
 		if (!slot->addr)
 			continue;
+#ifdef CONFIG_HAZPTR_DEBUG
+		item->ctx.ctx->detach_cpu = true;
+#endif
 		hazptr_promote_to_backup_slot(item->ctx.ctx, slot);
 	}
 }
@@ -173,6 +184,12 @@ void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
 	percpu_slots = this_cpu_ptr(&hazptr_percpu_slots);
 	slot_item = &percpu_slots->items[0];
 	slot = &slot_item->slot;
+#ifdef CONFIG_HAZPTR_DEBUG
+	ctx->detach_cpu = ctx->detach_task = false;
+	ctx->acquire_pid = current->pid;
+	ctx->acquire_cpu = smp_processor_id();
+	ctx->acquire_caller = _THIS_IP_;
+#endif
 	if (unlikely(slot->addr))
 		return __hazptr_acquire(ctx, addr_p);
 	WRITE_ONCE(slot->addr, HAZPTR_WILDCARD);	/* Store B */
@@ -196,6 +213,26 @@ void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
 	return addr;
 }
 
+#ifdef CONFIG_HAZPTR_DEBUG
+/* Called with preemption disabled. */
+static inline
+void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
+{
+	int pid = current->pid, cpu = smp_processor_id();
+	bool warn_remote_cpu = !ctx->detach_cpu && ctx->acquire_cpu != cpu,
+	     warn_remote_task = !ctx->detach_task && ctx->acquire_pid != pid;
+
+	WARN_ONCE(warn_remote_cpu || warn_remote_task,
+		"Hazard Pointer (addr=%p) released on remote %s without %s. Acquire: caller=%pS, pid=%d, cpu=%d. Release: pid=%d, cpu=%d.",
+		addr,
+		warn_remote_task ? "task" : "cpu",
+		warn_remote_task ? "being detached from task" : "context switch",
+		(void *) ctx->acquire_caller, ctx->acquire_pid, ctx->acquire_cpu, pid, cpu);
+}
+#else
+static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
+#endif
+
 /* Release the protected hazard pointer from @slot. */
 static inline
 void hazptr_release(struct hazptr_ctx *ctx, void *addr)
@@ -205,6 +242,7 @@ void hazptr_release(struct hazptr_ctx *ctx, void *addr)
 	if (!addr)
 		return;
 	guard(preempt)();
+	hazptr_release_debug(ctx, addr);
 	slot = ctx->slot;
 	smp_store_release(&slot->addr, NULL);
 	if (unlikely(hazptr_slot_is_backup(ctx, slot)))
kernel/rcu/Kconfig.debug +9 -0
index 7629c345b0b6..57fec4444a97 100644
@@ -264,4 +264,13 @@ config TRIVIAL_PREEMPT_RCU
 
 	  This has no value for production and is only for testing.
 
+config HAZPTR_DEBUG
+	bool "Provide debugging asserts for Hazard Pointers"
+	depends on DEBUG_KERNEL
+	default n
+	help
+	  This option provides consistency checks for Hazard pointers.
+
+	  Say Y here if you want to enable those assert, N otherwise.
+
 endmenu # "RCU Debugging"
Signature · 1 line
2.43.0
author reviewer
#3 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 7 lines · Paul E. McKenney
Quoted 5 lines · Mathieu Desnoyers

Introduce Hazard Pointers debug assert, which detects misuse of hazard pointers, namely failure to detach the hazard pointer from its owner thread before releasing it from a different thread.

Prints the following to the console when a failure is detected:

Quoted 7 lines

Thank you, Mathieu!

I am testing this one first to verify the debugging, and then I will test the patch 1/2 hazptrtorture.c changes to verify the fix.

We are going to need to carefully document the hazard-pointer handling rules! ;-)

Good point!

So the general rule for the hazptr API is that the hazptr context is attached to the task that does the hazptr acquire.

The scheduler integration is responsible for ensuring that the hazptr context is moved to a backup slot in case of context switch, which takes care of handling task migrations without user intervention.

The case for which the user needs to explicitly invoke "detach from task" is when the hazptr context is handed off to a _different_ task. In that case the scheduler really cannot help, so it needs to be done explicitly.

The debug code I proposed here discovers two scenarios:

- Release vs acquire are done on different tasks without explicit detach from task (user error),
- Release vs acquire are done on different CPUs, without scheduler context switch in between. This could happen if the user has a confused hazptr context ownership model.

Thanks,

Mathieu

Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#4 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 30 lines · Mathieu Desnoyers
Quoted 7 lines · Paul E. McKenney
Quoted 5 lines · Mathieu Desnoyers

Introduce Hazard Pointers debug assert, which detects misuse of hazard pointers, namely failure to detach the hazard pointer from its owner thread before releasing it from a different thread.

Prints the following to the console when a failure is detected:

Quoted 7 lines

Thank you, Mathieu!

I am testing this one first to verify the debugging, and then I will test the patch 1/2 hazptrtorture.c changes to verify the fix.

We are going to need to carefully document the hazard-pointer handling rules! ;-)

Good point!

So the general rule for the hazptr API is that the hazptr context is attached to the task that does the hazptr acquire.

The scheduler integration is responsible for ensuring that the hazptr context is moved to a backup slot in case of context switch, which takes care of handling task migrations without user intervention.

The case for which the user needs to explicitly invoke "detach from task" is when the hazptr context is handed off to a _different_ task. In that case the scheduler really cannot help, so it needs to be done explicitly.

Quoted 7 lines

The debug code I proposed here discovers two scenarios:

- Release vs acquire are done on different tasks without explicit detach from task (user error),
- Release vs acquire are done on different CPUs, without scheduler context switch in between. This could happen if the user has a confused hazptr context ownership model.

Or if they do hazptr_acquire() in one interrupt handler on one CPU and hazptr_release() in another on some other CPU. Which, as you say, requires that the first interrupt handler invoke hazptr_detach_from_task() before making the hazptr_ctx structure available to the other CPU's handler.

Do the kernel-doc headers below accurately capture the rules of the hazard-pointer road?

I am sure that I am confused on at least a few points, but we have to start somewhere! ;-)

Thanx, Paul

------------------------------------------------------------------------

commit 64241bf30d2cea1be8114f5be3ceb16b2db38d5f

Author: Paul E. McKenney <[email protected]>
Date:   Thu Jul 9 13:39:09 2026 -0700

hazptr: Upgrade kernel-doc headers

Upgrade the kernel-doc headers for hazptr_acquire(), hazptr_release(), and hazptr_detach_from_task().

Cc Mathieu Desnoyers <[email protected]>
Cc Boqun Feng <[email protected]>
include/linux/hazptr.h +50 -5
index c5aa4fb03b11cf..8b6c0c8cdfb987 100644
@@ -126,6 +126,24 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
 	ctx->slot = backup_slot;
 }
 
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in the context of a single task.  When you
+ * need to acquire a hazard pointer in one task and release it in another,
+ * you must first invoke hazptr_detach_from_task() on that hazard pointer's
+ * context.  It is permissible to invoke hazptr_detach_from_task() multiple
+ * times on the same @ctx while it is protecting the same pointer.
+ *
+ * For example, if a hazard pointer is acquired by a task and released
+ * by a timer handler, that task would need to pass the hazard pointer's
+ * context to hazptr_detach_from_task() after the hazptr_acquire() and
+ * before arming the timer (or at least before the handler had a chance
+ * to execute).
+ */
 static inline
 void hazptr_detach_from_task(struct hazptr_ctx *ctx)
 {
@@ -160,17 +178,29 @@ void hazptr_note_context_switch(void)
 	}
 }
 
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
  *
  * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter.
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
  *
  * Returns a non-NULL protected address if the loaded pointer is non-NULL.
  * Returns NULL if the loaded pointer is NULL.
  *
  * On success the protected hazptr slot is stored in @ctx->slot.
+ *
+ * By default, the call to hazptr_release() must be running in the context
+ * of the same task that executed hazptr_acquire().  When it is necessary
+ * to instead call hazptr_release() from the context of some other task,
+ * pass @ctx to hazptr_detach_from_task() after invoking hazptr_acquire()
+ * but before making the hazard pointer available to that other task.
+ * Please note that "in the context of some other task" includes things
+ * like interrupt handlers.
  */
 static inline
 void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
@@ -233,7 +263,22 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
 static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
 #endif
 
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the context of the
+ * same task that executed the corresponding hazptr_acquire(), but
+ * please see hazptr_detach_from_task().
+ *
+ * It is permissible (though likely unwise from a maintainability
+ * viewpoint) to invoke hazptr_release() twice on the same @ctx without
+ * an intervening hazptr_acquire().
+ */
 static inline
 void hazptr_release(struct hazptr_ctx *ctx, void *addr)
 {
author reviewer
#5 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

On 2026-07-09 16:44, Paul E. McKenney wrote:
[...]

Quoted 5 lines

Do the kernel-doc headers below accurately capture the rules of the hazard-pointer road?

I am sure that I am confused on at least a few points, but we have to start somewhere! ;-)

Comments inline,

Quoted 31 lines

------------------------------------------------------------------------

commit 64241bf30d2cea1be8114f5be3ceb16b2db38d5f

Author: Paul E. McKenney <[email protected]>
Date:   Thu Jul 9 13:39:09 2026 -0700

hazptr: Upgrade kernel-doc headers

Upgrade the kernel-doc headers for hazptr_acquire(), hazptr_release(), and hazptr_detach_from_task().

Cc Mathieu Desnoyers <[email protected]>
Cc Boqun Feng <[email protected]>
include/linux/hazptr.h +7 -0
index c5aa4fb03b11cf..8b6c0c8cdfb987 100644
@@ -126,6 +126,24 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
  	ctx->slot = backup_slot;
  }
 
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in the context of a single task.  When you

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 145

Quoted 10 lines
include/linux/hazptr.h +10 -0
+ * need to acquire a hazard pointer in one task and release it in another,
+ * you must first invoke hazptr_detach_from_task() on that hazard pointer's
+ * context.  It is permissible to invoke hazptr_detach_from_task() multiple
+ * times on the same @ctx while it is protecting the same pointer.
+ *
+ * For example, if a hazard pointer is acquired by a task and released
+ * by a timer handler, that task would need to pass the hazard pointer's
+ * context to hazptr_detach_from_task() after the hazptr_acquire() and
+ * before arming the timer (or at least before the handler had a chance
+ * to execute).

Important note: the "detach" must be called from the context of the thread "owning" the hazptr ctx (except when it's already been detached).

Quoted 9 lines
include/linux/hazptr.h +1 -1
+ */
  static inline
  void hazptr_detach_from_task(struct hazptr_ctx *ctx)
  {
@@ -160,17 +178,29 @@ void hazptr_note_context_switch(void)
  	}
  }
 
-/*

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 168

Quoted 10 lines
include/linux/hazptr.h +5 -3
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
   *
   * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.

I see that you removed wording of a major constraint here which allowed use of hazptr locally in a interrupt handler: the need to pair the acquire/release within the handler.

We'll need to think it through carefully. AFAIR it was OK to have an hazptr acquire in thread context interrupted (it's only disabling preemption, not interrupts), and another hazptr acquire in interrupt context nested on top. This was OK as long as the IRQ handler restores the state of the per-cpu hazptr slots to their original content, which is what motivated this requirement pairing acquire with release in the handler.

Now I think the slightly relaxed rule should be: either the release happens within the interrupt handler (so we're back to the original state on irq return), OR the interrupt handler calls "detach form task" before returning, which has the same effect of restoring the per-cpu hazptr slot to its original state.

So naming this "detach from execution context" rather than detach from task would probably be a better fit. I'm open to suggestions.

Quoted 6 lines
include/linux/hazptr.h +3 -0
+ * This protection is roughly similar to that of a reference counter.
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
   *
   * Returns a non-NULL protected address if the loaded pointer is non-NULL.
   * Returns NULL if the loaded pointer is NULL.

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 203

Quoted 10 lines
include/linux/hazptr.h +8 -0
   *
   * On success the protected hazptr slot is stored in @ctx->slot.
+ *
+ * By default, the call to hazptr_release() must be running in the context
+ * of the same task that executed hazptr_acquire().  When it is necessary
+ * to instead call hazptr_release() from the context of some other task,
+ * pass @ctx to hazptr_detach_from_task() after invoking hazptr_acquire()
+ * but before making the hazard pointer available to that other task.
+ * Please note that "in the context of some other task" includes things
+ * like interrupt handlers.

My earlier comments apply to this paragraph as well.

Quoted 8 lines
include/linux/hazptr.h +0 -1
   */
  static inline
  void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
@@ -233,7 +263,22 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
  static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
  #endif
 
-/* Release the protected hazard pointer from @slot. */

include/linux/hazptr.h void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) · line 275

Quoted 10 lines
include/linux/hazptr.h +10 -0
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the context of the
+ * same task that executed the corresponding hazptr_acquire(), but

same comment about interrupt context requirements.

Thanks!

Mathieu

Quoted 9 lines
include/linux/hazptr.h +6 -0
+ * please see hazptr_detach_from_task().
+ *
+ * It is permissible (though likely unwise from a maintainability
+ * viewpoint) to invoke hazptr_release() twice on the same @ctx without
+ * an intervening hazptr_acquire().
+ */
  static inline
  void hazptr_release(struct hazptr_ctx *ctx, void *addr)
  {
Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#6 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 44 lines · Mathieu Desnoyers

On 2026-07-09 16:44, Paul E. McKenney wrote:
[...]

Quoted 5 lines

Do the kernel-doc headers below accurately capture the rules of the hazard-pointer road?

I am sure that I am confused on at least a few points, but we have to start somewhere! ;-)

Comments inline,

Quoted 33 lines

------------------------------------------------------------------------

commit 64241bf30d2cea1be8114f5be3ceb16b2db38d5f

Author: Paul E. McKenney <[email protected]>
Date:   Thu Jul 9 13:39:09 2026 -0700

hazptr: Upgrade kernel-doc headers
Upgrade the kernel-doc headers for hazptr_acquire(), hazptr_release(), and hazptr_detach_from_task().

Cc Mathieu Desnoyers <[email protected]>
Cc Boqun Feng <[email protected]>
include/linux/hazptr.h +12 -0
index c5aa4fb03b11cf..8b6c0c8cdfb987 100644
@@ -126,6 +126,24 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
  	ctx->slot = backup_slot;
  }
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in the context of a single task.  When you
+ * need to acquire a hazard pointer in one task and release it in another,
+ * you must first invoke hazptr_detach_from_task() on that hazard pointer's
+ * context.  It is permissible to invoke hazptr_detach_from_task() multiple
+ * times on the same @ctx while it is protecting the same pointer.
+ *
Quoted 8 lines

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 144

Quoted 5 lines
include/linux/hazptr.h +5 -0
+ * For example, if a hazard pointer is acquired by a task and released
+ * by a timer handler, that task would need to pass the hazard pointer's
+ * context to hazptr_detach_from_task() after the hazptr_acquire() and
+ * before arming the timer (or at least before the handler had a chance
+ * to execute).

Important note: the "detach" must be called from the context of the thread "owning" the hazptr ctx (except when it's already been detached).

Good point, upgrading.

Quoted 14 lines
Quoted 14 lines
include/linux/hazptr.h +6 -2
+ */
  static inline
  void hazptr_detach_from_task(struct hazptr_ctx *ctx)
  {
@@ -160,17 +178,29 @@ void hazptr_note_context_switch(void)
  	}
  }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
Quoted 8 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 167

Quoted 4 lines
include/linux/hazptr.h +0 -2
   *
   * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.

I see that you removed wording of a major constraint here which allowed use of hazptr locally in a interrupt handler: the need to pair the acquire/release within the handler.

I did indeed remove that wording. You could do something like this:

	Task Context			IRQ Handler Interrupts Task
	------------			---------------------------
	preempt_disable();
	ihp = __this_cpu_read(irq_hc);	ihp = __this_cpu_read(irq_hc);
					p = hazptr_acquire(ihp, &gp);
	lp = xchg(p, NULL);
	if (lp) {
		do_something(lp);
		hazptr_release(ihp, lp);
	}
	preempt_enable();

If I understand the rules correctly (ha!), this is perfectly legal and does not require a hazptr_detach_from_task().

The actual code would need to be a bit more ornate to ensure that the irq handler knew that the task it interrupted was ready, willing, and able to release the hazard pointer before a context switch could occur.

Quoted 8 lines

We'll need to think it through carefully. AFAIR it was OK to have an hazptr acquire in thread context interrupted (it's only disabling preemption, not interrupts), and another hazptr acquire in interrupt context nested on top. This was OK as long as the IRQ handler restores the state of the per-cpu hazptr slots to their original content, which is what motivated this requirement pairing acquire with release in the handler.

Quoted 5 lines

Now I think the slightly relaxed rule should be: either the release happens within the interrupt handler (so we're back to the original state on irq return), OR the interrupt handler calls "detach form task" before returning, which has the same effect of restoring the per-cpu hazptr slot to its original state.

This would prohibit the pattern shown above. Which is quite possibly OK. But if we do prohibit this pattern, we need a diagnostic that checks for that pattern, correct? Especially in this new world of LLM-generated code.

I have not yet changed the comment (or the later ones) to prohibit this, as I await your verdict. If we do prohibit this, please note that executing on a given CPU does not constitute a context.

Quoted 2 lines

So naming this "detach from execution context" rather than detach from task would probably be a better fit. I'm open to suggestions.

I am OK with that name, expecially if we outlaw passing from a handler the the interrupted task without the benefit of an intervening hazptr_detach_from_task() or hazptr_detach_from_context(), as the case might be.

Quoted 30 lines
Quoted 6 lines
include/linux/hazptr.h +3 -0
+ * This protection is roughly similar to that of a reference counter.
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
   *
   * Returns a non-NULL protected address if the loaded pointer is non-NULL.
   * Returns NULL if the loaded pointer is NULL.

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 202

Quoted 10 lines
include/linux/hazptr.h +8 -0
   *
   * On success the protected hazptr slot is stored in @ctx->slot.
+ *
+ * By default, the call to hazptr_release() must be running in the context
+ * of the same task that executed hazptr_acquire().  When it is necessary
+ * to instead call hazptr_release() from the context of some other task,
+ * pass @ctx to hazptr_detach_from_task() after invoking hazptr_acquire()
+ * but before making the hazard pointer available to that other task.
+ * Please note that "in the context of some other task" includes things
+ * like interrupt handlers.

My earlier comments apply to this paragraph as well.

Quoted 11 lines
include/linux/hazptr.h +4 -1
   */
  static inline
  void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
@@ -233,7 +263,22 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
  static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
  #endif
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
Quoted 8 lines

include/linux/hazptr.h void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) · line 274

Quoted 6 lines
include/linux/hazptr.h +6 -0
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the context of the
+ * same task that executed the corresponding hazptr_acquire(), but

same comment about interrupt context requirements.

Please see below for an update. Again, this assumes that the task is the context, regardless of things like interrupts, and would need further changes to treat things like interrupt handlers as separate contexts.

Thanx, Paul

Quoted 13 lines

Thanks!

Mathieu

Quoted 9 lines
include/linux/hazptr.h +6 -0
+ * please see hazptr_detach_from_task().
+ *
+ * It is permissible (though likely unwise from a maintainability
+ * viewpoint) to invoke hazptr_release() twice on the same @ctx without
+ * an intervening hazptr_acquire().
+ */
  static inline
  void hazptr_release(struct hazptr_ctx *ctx, void *addr)
  {

------------------------------------------------------------------------

commit 6c17eb2a1bc4affc0963a40ddc52cac639800558

Author: Paul E. McKenney <[email protected]>
Date:   Thu Jul 9 13:39:09 2026 -0700

hazptr: Upgrade kernel-doc headers

Upgrade the kernel-doc headers for hazptr_acquire(), hazptr_release(), and hazptr_detach_from_task().

Cc Mathieu Desnoyers <[email protected]>
Cc Boqun Feng <[email protected]>
include/linux/hazptr.h +59 -5
index c5aa4fb03b11cf..de5afe0cce1d80 100644
@@ -126,6 +126,29 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
 	ctx->slot = backup_slot;
 }
 
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in the context of a single task.
+ * Please note that things like interrupt handlers execute in the
+ * context of the interrupted task.  When you have acquired a hazard
+ * pointer in one task and need to release it in another, you must
+ * invoke hazptr_detach_from_task() on that hazard pointer's context.
+ * It is permissible to invoke hazptr_detach_from_task() multiple times
+ * on the same @ctx while it is protecting the same pointer, however,
+ * the first invocation absolutely must be in the context of the task
+ * that did the hazptr_acquire(), and must take place after the return
+ * from that hazptr_acquire().
+ *
+ * For example, if a hazard pointer is acquired by a task and
+ * released by a timer handler, that task would need to pass the hazard
+ * pointer's context to hazptr_detach_from_task() after return from the
+ * hazptr_acquire() and before arming the timer (or at least before the
+ * handler had a chance to access that hazard-pointer context).
+ */
 static inline
 void hazptr_detach_from_task(struct hazptr_ctx *ctx)
 {
@@ -160,12 +183,26 @@ void hazptr_note_context_switch(void)
 	}
 }
 
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
  *
  * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a hazptr_release().
+ *
+ * By default, the call to hazptr_release() must be running in the context
+ * of the same task that executed hazptr_acquire().  When it is necessary
+ * to instead call hazptr_release() from the context of some other task,
+ * pass @ctx to hazptr_detach_from_task() after invoking hazptr_acquire()
+ * but before making the hazard pointer available to that other task.
+ * Please note that things like interrupt handlers execute in the context
+ * of the interrupted task.
+ *
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
  *
  * Returns a non-NULL protected address if the loaded pointer is non-NULL.
  * Returns NULL if the loaded pointer is NULL.
@@ -233,7 +270,24 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
 static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
 #endif
 
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the context of the
+ * same task that executed the corresponding hazptr_acquire(), but
+ * if this restriction is problematic for your use case, please see
+ * hazptr_detach_from_task().  Please note that things like interrupt
+ * handlers execute in the context of the interrupted task.
+ *
+ * It is permissible (though likely unwise from a maintainability
+ * viewpoint) to invoke hazptr_release() twice on the same @ctx without
+ * an intervening hazptr_acquire().
+ */
 static inline
 void hazptr_release(struct hazptr_ctx *ctx, void *addr)
 {
author reviewer
#7 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 1 line · Paul E. McKenney

On Thu, Jul 09, 2026 at 05:47:00PM -0400, Mathieu Desnoyers wrote:

[...]

Quoted 37 lines
Quoted 14 lines
Quoted 14 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

include/linux/hazptr.h +5 -2
@@ -160,17 +178,29 @@ void hazptr_note_context_switch(void)
   	}
   }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
Quoted 8 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 168

Quoted 4 lines
include/linux/hazptr.h +0 -2
    *
    * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.

I see that you removed wording of a major constraint here which allowed use of hazptr locally in a interrupt handler: the need to pair the acquire/release within the handler.

I did indeed remove that wording. You could do something like this:

	Task Context			IRQ Handler Interrupts Task
	------------			---------------------------
	preempt_disable();
	ihp = __this_cpu_read(irq_hc);	ihp = __this_cpu_read(irq_hc);
					p = hazptr_acquire(ihp, &gp);
	lp = xchg(p, NULL);
	if (lp) {
		do_something(lp);
		hazptr_release(ihp, lp);
	}
	preempt_enable();
Quoted 3 lines

If I understand the rules correctly (ha!), this is perfectly legal and does not require a hazptr_detach_from_task().

I am concerned about it, because I knowingly just used preempt disable to protect hazptr_acquire from the scheduler, but not from interrupt handlers, because it's faster than irqoff.

I am concerned that this use of hazptr_acquire could confuse the thread-level hazptr_acquire, let's dig:

void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)

{
        struct hazptr_percpu_slots *percpu_slots;
        struct hazptr_slot_item *slot_item;
        struct hazptr_slot *slot;
        void *addr;

        guard(preempt)();
        percpu_slots = this_cpu_ptr(&hazptr_percpu_slots);
        slot_item = &percpu_slots->items[0];
        slot = &slot_item->slot;

[...]

  from here --------------------
        if (unlikely(slot->addr))
                return __hazptr_acquire(ctx, addr_p);
        WRITE_ONCE(slot->addr, HAZPTR_WILDCARD);        /* Store B */
        /* Memory ordering: Store B before Load A. */
        smp_mb();

        /*
         * Load @addr_p after storing wildcard to the hazard pointer slot.
         */
        addr = READ_ONCE(*addr_p);      /* Load A */

        /*
         * We don't care about ordering of Store C. It will simply
         * replace the wildcard by a more specific address. If addr is
         * NULL, we simply store NULL into the slot.
         */
        WRITE_ONCE(slot->addr, addr);   /* Store C */

to here ----------------------------

I designed hazptr_acquire so a _nested_ interrupt which _brings back_ the slot addr to its original state will work. Now let's see if that's still OK if the interrupt handler leaves the slot->addr populated with an address.

And no. If the interrupt happens right before "Store B", its reserved slot address is overwritten by the thread. That's incorrect.

So as it is today, the irq handler needs to vacate the slot before it returns, either through a hazptr release or a detach.

That being said, this is the code as it is today. If someone finds a clever way to support this use-case and keep it fast and not too complex, I'm all ears! :)

One possible way to make it work would be to install the HAZPTR_WILDCARD with a local-cmpxchg expecting a NULL slot->addr. This would close this race window. But it comes at a non-null overhead price. Another alternative on x86 would be to use a lock prefixed cmpxchg, which has an implied smp_mb on success, which may be in the same ballpark as the sequence of WRITE_ONCE+ explicit smp_mb().

Thanks,

Mathieu

Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#8 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 99 lines · Mathieu Desnoyers
Quoted 1 line · Paul E. McKenney

On Thu, Jul 09, 2026 at 05:47:00PM -0400, Mathieu Desnoyers wrote:

[...]

Quoted 37 lines
Quoted 14 lines
Quoted 14 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

(quoted diff) +5 -2
@@ -160,17 +178,29 @@ void hazptr_note_context_switch(void)
   	}
   }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
Quoted 8 lines

Review void hazptr_note_context_switch(void) · line 167

Quoted 4 lines
(quoted diff) +0 -2
    *
    * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.

I see that you removed wording of a major constraint here which allowed use of hazptr locally in a interrupt handler: the need to pair the acquire/release within the handler.

I did indeed remove that wording. You could do something like this:

	Task Context			IRQ Handler Interrupts Task
	------------			---------------------------
	preempt_disable();
	ihp = __this_cpu_read(irq_hc);	ihp = __this_cpu_read(irq_hc);
					p = hazptr_acquire(ihp, &gp);
	lp = xchg(p, NULL);
	if (lp) {
		do_something(lp);
		hazptr_release(ihp, lp);
	}
	preempt_enable();
Quoted 3 lines

If I understand the rules correctly (ha!), this is perfectly legal and does not require a hazptr_detach_from_task().

I am concerned about it, because I knowingly just used preempt disable to protect hazptr_acquire from the scheduler, but not from interrupt handlers, because it's faster than irqoff.

I am concerned that this use of hazptr_acquire could confuse the thread-level hazptr_acquire, let's dig:

void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)

{
        struct hazptr_percpu_slots *percpu_slots;
        struct hazptr_slot_item *slot_item;
        struct hazptr_slot *slot;
        void *addr;

        guard(preempt)();
        percpu_slots = this_cpu_ptr(&hazptr_percpu_slots);
        slot_item = &percpu_slots->items[0];
        slot = &slot_item->slot;

[...]

  from here --------------------
        if (unlikely(slot->addr))
                return __hazptr_acquire(ctx, addr_p);
        WRITE_ONCE(slot->addr, HAZPTR_WILDCARD);        /* Store B */
        /* Memory ordering: Store B before Load A. */
        smp_mb();

        /*
         * Load @addr_p after storing wildcard to the hazard pointer slot.
         */
        addr = READ_ONCE(*addr_p);      /* Load A */

        /*
         * We don't care about ordering of Store C. It will simply
         * replace the wildcard by a more specific address. If addr is
         * NULL, we simply store NULL into the slot.
         */
        WRITE_ONCE(slot->addr, addr);   /* Store C */

to here ----------------------------

I designed hazptr_acquire so a _nested_ interrupt which _brings back_ the slot addr to its original state will work. Now let's see if that's still OK if the interrupt handler leaves the slot->addr populated with an address.

And no. If the interrupt happens right before "Store B", its reserved slot address is overwritten by the thread. That's incorrect.

So as it is today, the irq handler needs to vacate the slot before it returns, either through a hazptr release or a detach.

That being said, this is the code as it is today. If someone finds a clever way to support this use-case and keep it fast and not too complex, I'm all ears! :)

Quoted 6 lines

One possible way to make it work would be to install the HAZPTR_WILDCARD with a local-cmpxchg expecting a NULL slot->addr. This would close this race window. But it comes at a non-null overhead price. Another alternative on x86 would be to use a lock prefixed cmpxchg, which has an implied smp_mb on success, which may be in the same ballpark as the sequence of WRITE_ONCE+ explicit smp_mb().

Let's start by me correctly documenting the current rules. Calling hazptr_detach_from_task() should not be all that much of a burden, especially if the proper diagnostics are in place.

Please see below, and thank you for bearing with me!

Thanx, Paul

------------------------------------------------------------------------

commit b8de842c6708de99335e2f700d3668e18aeeb3eb

Author: Paul E. McKenney <[email protected]>
Date:   Thu Jul 9 13:39:09 2026 -0700

hazptr: Upgrade kernel-doc headers

Upgrade the kernel-doc headers for hazptr_acquire(), hazptr_release(), and hazptr_detach_from_task().

Cc Mathieu Desnoyers <[email protected]>
Cc Boqun Feng <[email protected]>
include/linux/hazptr.h +61 -5
index c5aa4fb03b11cf..dbaea42a68745b 100644
@@ -126,6 +126,29 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
 	ctx->slot = backup_slot;
 }
 
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in a single execution context, for example, the
+ * context of a single task or a single interrupt handler.  Please note that
+ * things like interrupt handlers execute in the context of the interrupted
+ * task.  When you have acquired a hazard pointer in one task and need
+ * to release it in another, you must invoke hazptr_detach_from_task()
+ * on that hazard pointer's context.  It is permissible to invoke
+ * hazptr_detach_from_task() multiple times on the same @ctx while it is
+ * protecting the same pointer, however, the first invocation absolutely
+ * must be in the context of the task that did the hazptr_acquire(),
+ * and must take place after the return from that hazptr_acquire().
+ *
+ * For example, if a hazard pointer is acquired by a task and
+ * released by a timer handler, that task would need to pass the hazard
+ * pointer's context to hazptr_detach_from_task() after return from the
+ * hazptr_acquire() and before arming the timer (or at least before the
+ * handler had a chance to access that hazard-pointer context).
+ */
 static inline
 void hazptr_detach_from_task(struct hazptr_ctx *ctx)
 {
@@ -160,12 +183,27 @@ void hazptr_note_context_switch(void)
 	}
 }
 
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
  *
  * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a hazptr_release().
+ *
+ * By default, the call to hazptr_release() must be running in the same
+ * execution context that executed the corresponding hazptr_acquire(), for
+ * example, within the same task or interrupt handler.  When it is necessary
+ * to instead call hazptr_release() from the context of some other task,
+ * pass @ctx to hazptr_detach_from_task() after invoking hazptr_acquire()
+ * but before making the hazard pointer available to that other task.
+ * Please note that things like interrupt handlers execute in the context
+ * of the interrupted task.
+ *
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
  *
  * Returns a non-NULL protected address if the loaded pointer is non-NULL.
  * Returns NULL if the loaded pointer is NULL.
@@ -233,7 +271,25 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
 static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
 #endif
 
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the same execution context
+ * that invoked the corresponding hazptr_acquire(), for example, within the
+ * same task or the same interrupt handler.  However, if this restriction
+ * is problematic for your use case, please see hazptr_detach_from_task().
+ * Please note that things like interrupt handlers execute in the context
+ * of the interrupted task.
+ *
+ * It is permissible (though likely unwise from a maintainability
+ * viewpoint) to invoke hazptr_release() twice on the same @ctx without
+ * an intervening hazptr_acquire().
+ */
 static inline
 void hazptr_release(struct hazptr_ctx *ctx, void *addr)
 {
author reviewer
#9 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

On 2026-07-09 19:48, Paul E. McKenney wrote:
[...]

Quoted 6 lines

Let's start by me correctly documenting the current rules. Calling hazptr_detach_from_task() should not be all that much of a burden, especially if the proper diagnostics are in place.

Please see below, and thank you for bearing with me!

Comments below,

Quoted 22 lines

Thanx, Paul

------------------------------------------------------------------------

commit b8de842c6708de99335e2f700d3668e18aeeb3eb

Author: Paul E. McKenney <[email protected]>
Date:   Thu Jul 9 13:39:09 2026 -0700

hazptr: Upgrade kernel-doc headers

Upgrade the kernel-doc headers for hazptr_acquire(), hazptr_release(), and hazptr_detach_from_task().

Cc Mathieu Desnoyers <[email protected]>
Cc Boqun Feng <[email protected]>
include/linux/hazptr.h +0 -0
index c5aa4fb03b11cf..dbaea42a68745b 100644

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 130

Quoted 5 lines
include/linux/hazptr.h +2 -0
@@ -126,6 +126,29 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
  	ctx->slot = backup_slot;
  }
 
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task

We should really rename this given that it detaches the hazptr ctx from the execution _context_ (irq handler or thread). Not sure how to name it though.

Quoted 5 lines
include/linux/hazptr.h +5 -0
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in a single execution context, for example, the

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 145

Quoted 10 lines
include/linux/hazptr.h +10 -0
+ * context of a single task or a single interrupt handler.  Please note that
+ * things like interrupt handlers execute in the context of the interrupted
+ * task.  When you have acquired a hazard pointer in one task and need
+ * to release it in another, you must invoke hazptr_detach_from_task()
+ * on that hazard pointer's context.  It is permissible to invoke
+ * hazptr_detach_from_task() multiple times on the same @ctx while it is
+ * protecting the same pointer, however, the first invocation absolutely
+ * must be in the context of the task that did the hazptr_acquire(),
+ * and must take place after the return from that hazptr_acquire().
+ *

The text above does not discuss the need to either release or detach before returning from interrupt handler. Or am I missing something ?

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 150

Quoted 5 lines
include/linux/hazptr.h +5 -0
+ * For example, if a hazard pointer is acquired by a task and
+ * released by a timer handler, that task would need to pass the hazard
+ * pointer's context to hazptr_detach_from_task() after return from the
+ * hazptr_acquire() and before arming the timer (or at least before the
+ * handler had a chance to access that hazard-pointer context).

ok

Quoted 20 lines
include/linux/hazptr.h +7 -4
+ */
  static inline
  void hazptr_detach_from_task(struct hazptr_ctx *ctx)
  {
@@ -160,12 +183,27 @@ void hazptr_note_context_switch(void)
  	}
  }
 
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
   *
   * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 203

Quoted 10 lines
include/linux/hazptr.h +10 -0
+ * ends with a hazptr_release().
+ *
+ * By default, the call to hazptr_release() must be running in the same
+ * execution context that executed the corresponding hazptr_acquire(), for
+ * example, within the same task or interrupt handler.  When it is necessary
+ * to instead call hazptr_release() from the context of some other task,
+ * pass @ctx to hazptr_detach_from_task() after invoking hazptr_acquire()
+ * but before making the hazard pointer available to that other task.
+ * Please note that things like interrupt handlers execute in the context
+ * of the interrupted task.

Same comment about use of detach before returning from irq.

Quoted 15 lines
include/linux/hazptr.h +7 -1
+ *
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
   *
   * Returns a non-NULL protected address if the loaded pointer is non-NULL.
   * Returns NULL if the loaded pointer is NULL.
@@ -233,7 +271,25 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
  static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
  #endif
 
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().

include/linux/hazptr.h void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) · line 287

Quoted 10 lines
include/linux/hazptr.h +10 -0
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the same execution context
+ * that invoked the corresponding hazptr_acquire(), for example, within the
+ * same task or the same interrupt handler.  However, if this restriction
+ * is problematic for your use case, please see hazptr_detach_from_task().
+ * Please note that things like interrupt handlers execute in the context
+ * of the interrupted task.

Again, this statement is misleading: one could think that they don't need to detach the ctx before returning to the _same task_. The naming of the detach helper is actively confusing here.

Maybe just call it hazptr_detach() ?

Thanks,

Mathieu

Quoted 8 lines
include/linux/hazptr.h +5 -0
+ *
+ * It is permissible (though likely unwise from a maintainability
+ * viewpoint) to invoke hazptr_release() twice on the same @ctx without
+ * an intervening hazptr_acquire().
+ */
  static inline
  void hazptr_release(struct hazptr_ctx *ctx, void *addr)
  {
Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#10 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 26 lines · Mathieu Desnoyers

On 2026-07-09 19:48, Paul E. McKenney wrote:
[...]

Quoted 6 lines

Let's start by me correctly documenting the current rules. Calling hazptr_detach_from_task() should not be all that much of a burden, especially if the proper diagnostics are in place.

Please see below, and thank you for bearing with me!

Comments below,

Quoted 15 lines

Thanx, Paul

------------------------------------------------------------------------

commit b8de842c6708de99335e2f700d3668e18aeeb3eb

Author: Paul E. McKenney <[email protected]>
Date:   Thu Jul 9 13:39:09 2026 -0700

hazptr: Upgrade kernel-doc headers
Upgrade the kernel-doc headers for hazptr_acquire(), hazptr_release(), and hazptr_detach_from_task().

Cc Mathieu Desnoyers <[email protected]>
Cc Boqun Feng <[email protected]>
Quoted 13 lines

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 129

Quoted 9 lines
include/linux/hazptr.h +2 -0
index c5aa4fb03b11cf..dbaea42a68745b 100644
@@ -126,6 +126,29 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
  	ctx->slot = backup_slot;
  }
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task

We should really rename this given that it detaches the hazptr ctx from the execution _context_ (irq handler or thread). Not sure how to name it though.

hazptr_detach_from_context()?

I am leaving this alone for the moment, easy to change later.

Quoted 16 lines
Quoted 5 lines
include/linux/hazptr.h +5 -0
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in a single execution context, for example, the

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 144

Quoted 10 lines
include/linux/hazptr.h +10 -0
+ * context of a single task or a single interrupt handler.  Please note that
+ * things like interrupt handlers execute in the context of the interrupted
+ * task.  When you have acquired a hazard pointer in one task and need
+ * to release it in another, you must invoke hazptr_detach_from_task()
+ * on that hazard pointer's context.  It is permissible to invoke
+ * hazptr_detach_from_task() multiple times on the same @ctx while it is
+ * protecting the same pointer, however, the first invocation absolutely
+ * must be in the context of the task that did the hazptr_acquire(),
+ * and must take place after the return from that hazptr_acquire().
+ *
Quoted 2 lines

The text above does not discuss the need to either release or detach before returning from interrupt handler. Or am I missing something ?

You miss nothing. It was late and I wasn't sufficiently alert. So this was my hint to back slowly away from the keyboard. ;-)

Update attached at the end.

Quoted 31 lines

include/linux/hazptr.h void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s · line 149

Quoted 5 lines
include/linux/hazptr.h +5 -0
+ * For example, if a hazard pointer is acquired by a task and
+ * released by a timer handler, that task would need to pass the hazard
+ * pointer's context to hazptr_detach_from_task() after return from the
+ * hazptr_acquire() and before arming the timer (or at least before the
+ * handler had a chance to access that hazard-pointer context).

ok

Quoted 23 lines
include/linux/hazptr.h +11 -4
+ */
  static inline
  void hazptr_detach_from_task(struct hazptr_ctx *ctx)
  {
@@ -160,12 +183,27 @@ void hazptr_note_context_switch(void)
  	}
  }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
   *
   * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a hazptr_release().
+ *
+ * By default, the call to hazptr_release() must be running in the same
+ * execution context that executed the corresponding hazptr_acquire(), for
Quoted 8 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 202

Quoted 6 lines
include/linux/hazptr.h +6 -0
+ * example, within the same task or interrupt handler.  When it is necessary
+ * to instead call hazptr_release() from the context of some other task,
+ * pass @ctx to hazptr_detach_from_task() after invoking hazptr_acquire()
+ * but before making the hazard pointer available to that other task.
+ * Please note that things like interrupt handlers execute in the context
+ * of the interrupted task.

Same comment about use of detach before returning from irq.

And same response. ;-)

Quoted 20 lines
Quoted 20 lines
include/linux/hazptr.h +13 -1
+ *
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
   *
   * Returns a non-NULL protected address if the loaded pointer is non-NULL.
   * Returns NULL if the loaded pointer is NULL.
@@ -233,7 +271,25 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
  static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
  #endif
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the same execution context
+ * that invoked the corresponding hazptr_acquire(), for example, within the
Quoted 8 lines

include/linux/hazptr.h void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) · line 286

Quoted 4 lines
include/linux/hazptr.h +4 -0
+ * same task or the same interrupt handler.  However, if this restriction
+ * is problematic for your use case, please see hazptr_detach_from_task().
+ * Please note that things like interrupt handlers execute in the context
+ * of the interrupted task.

Again, this statement is misleading: one could think that they don't need to detach the ctx before returning to the _same task_. The naming of the detach helper is actively confusing here.

I deleted this "Please note..." sentence from all three kernel-doc headers and adjusted to suit. Again, please see below.

Quoted 1 line

Maybe just call it hazptr_detach() ?

That would be your choice, not mine. ;-)

Thanx, Paul

Quoted 12 lines

Thanks,

Mathieu

Quoted 8 lines
include/linux/hazptr.h +5 -0
+ *
+ * It is permissible (though likely unwise from a maintainability
+ * viewpoint) to invoke hazptr_release() twice on the same @ctx without
+ * an intervening hazptr_acquire().
+ */
  static inline
  void hazptr_release(struct hazptr_ctx *ctx, void *addr)
  {

------------------------------------------------------------------------
diff rather than commit due to not-yet-rebased fixup in my -rcu tree.
------------------------------------------------------------------------

include/linux/hazptr.h +57 -5
index c5aa4fb03b11cf..57a7cb41df2015 100644
@@ -126,6 +126,28 @@ void hazptr_promote_to_backup_slot(struct hazptr_ctx *ctx, struct hazptr_slot *s
 	ctx->slot = backup_slot;
 }
 
+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in a single execution context, for example,
+ * the context of a single task or a single interrupt handler.  When you
+ * have acquired a hazard pointer in one context and need to release it
+ * in another, you must invoke hazptr_detach_from_task() on that hazard
+ * pointer's context.  It is permissible to invoke hazptr_detach_from_task()
+ * multiple times on the same @ctx while it is protecting the same pointer,
+ * however, the first invocation absolutely must be in the same context
+ * that did the hazptr_acquire(), and must take place after the return
+ * from that hazptr_acquire().
+ *
+ * For example, if a hazard pointer is acquired by a task and
+ * released by a timer handler, that task would need to pass the hazard
+ * pointer's context to hazptr_detach_from_task() after return from the
+ * hazptr_acquire() and before arming the timer (or at least before the
+ * handler had a chance to access that hazard-pointer context).
+ */
 static inline
 void hazptr_detach_from_task(struct hazptr_ctx *ctx)
 {
@@ -160,12 +182,26 @@ void hazptr_note_context_switch(void)
 	}
 }
 
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
  *
  * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a later call to hazptr_release().
+ *
+ * By default, the call to hazptr_release() must be running in the same
+ * execution context as the corresponding hazptr_acquire(), for example,
+ * within the same task or interrupt handler.  When it is necessary
+ * to instead call hazptr_release() from some other context, pass @ctx
+ * to hazptr_detach_from_task() in the original context after invoking
+ * hazptr_acquire() but before making the hazard pointer available to that
+ * other context.
+ *
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().
  *
  * Returns a non-NULL protected address if the loaded pointer is non-NULL.
  * Returns NULL if the loaded pointer is NULL.
@@ -233,7 +269,23 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
 static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
 #endif
 
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the same execution context
+ * that invoked the corresponding hazptr_acquire(), for example, within the
+ * same task or the same interrupt handler.  However, if this restriction
+ * is problematic for your use case, please see hazptr_detach_from_task().
+ *
+ * It is permissible (though unwise from a maintainability viewpoint)
+ * to invoke hazptr_release() twice on the same @ctx without an intervening
+ * hazptr_acquire().
+ */
 static inline
 void hazptr_release(struct hazptr_ctx *ctx, void *addr)
 {
author reviewer
#11 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 8 lines · Paul E. McKenney
Quoted 4 lines

We should really rename this given that it detaches the hazptr ctx from the execution _context_ (irq handler or thread). Not sure how to name it though.

hazptr_detach_from_context()?

I am leaving this alone for the moment, easy to change later.

I just wonder if that name brings confusion. Is "context" the execution context or the "hazptr ctx" context ? I fear this is really a good opportunity to confuse everyone.

[...]

Quoted 4 lines
Quoted 2 lines

Maybe just call it hazptr_detach() ?

That would be your choice, not mine. ;-)

I find that hazptr_detach is probably better here. It does not state it detaches "what", but at least there is no shortcut confusion with the overloaded "context" wording.

[...]

Quoted 14 lines

+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in a single execution context, for example,
+ * the context of a single task or a single interrupt handler. When you
+ * have acquired a hazard pointer in one context and need to release it
+ * in another, you must invoke hazptr_detach_from_task() on that hazard
+ * pointer's context. It is permissible to invoke hazptr_detach_from_task()
+ * multiple times on the same @ctx while it is protecting the same pointer,
+ * however, the first invocation absolutely must be in the same context

Quoted 8 lines

+ * that did the hazptr_acquire(), and must take place after the return
+ * from that hazptr_acquire().
+ *
+ * For example, if a hazard pointer is acquired by a task and
+ * released by a timer handler, that task would need to pass the hazard
+ * pointer's context to hazptr_detach_from_task() after return from the
+ * hazptr_acquire() and before arming the timer (or at least before the
+ * handler had a chance to access that hazard-pointer context).

good.

Quoted 11 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

include/linux/hazptr.h +1 -2
@@ -160,12 +182,26 @@ void hazptr_note_context_switch(void)
  	}
  }
 
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 193

Quoted 10 lines
include/linux/hazptr.h +6 -2
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
   *
   * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a later call to hazptr_release().

Perhaps worthwhile to hint at the vast performance/scalability/memory footprint/cache line footprint difference between hazptr and refcount to justify why both exist here ?

AFAIU there is partial overlap between refcount, hazptr, and RCU, each with their own strengths and weaknesses. We should prepare a summary table for the end users wondering which is the right tool for their use-case.

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 204

Quoted 11 lines
include/linux/hazptr.h +11 -0
+ *
+ * By default, the call to hazptr_release() must be running in the same
+ * execution context as the corresponding hazptr_acquire(), for example,
+ * within the same task or interrupt handler.  When it is necessary
+ * to instead call hazptr_release() from some other context, pass @ctx
+ * to hazptr_detach_from_task() in the original context after invoking
+ * hazptr_acquire() but before making the hazard pointer available to that
+ * other context.
+ *
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().

good

Quoted 14 lines
include/linux/hazptr.h +6 -1
   *
   * Returns a non-NULL protected address if the loaded pointer is non-NULL.
   * Returns NULL if the loaded pointer is NULL.
@@ -233,7 +269,23 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
  static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
  #endif
 
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *

include/linux/hazptr.h void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) · line 287

Quoted 10 lines
include/linux/hazptr.h +10 -0
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the same execution context
+ * that invoked the corresponding hazptr_acquire(), for example, within the
+ * same task or the same interrupt handler.  However, if this restriction
+ * is problematic for your use case, please see hazptr_detach_from_task().
+ *
+ * It is permissible (though unwise from a maintainability viewpoint)
+ * to invoke hazptr_release() twice on the same @ctx without an intervening
+ * hazptr_acquire().

Good!

Thanks,

Mathieu

Quoted 4 lines
include/linux/hazptr.h +1 -0
+ */
  static inline
  void hazptr_release(struct hazptr_ctx *ctx, void *addr)
  {
Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#12 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 17 lines · Mathieu Desnoyers
Quoted 8 lines · Paul E. McKenney
Quoted 4 lines

We should really rename this given that it detaches the hazptr ctx from the execution _context_ (irq handler or thread). Not sure how to name it though.

hazptr_detach_from_context()?

I am leaving this alone for the moment, easy to change later.

I just wonder if that name brings confusion. Is "context" the execution context or the "hazptr ctx" context ? I fear this is really a good opportunity to confuse everyone.

[...]

Quoted 1 line
Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Maybe just call it hazptr_detach() ?

That would be your choice, not mine. ;-)

I find that hazptr_detach is probably better here. It does not state it detaches "what", but at least there is no shortcut confusion with the overloaded "context" wording.

Fair enough.

Would you like me to make this change?

Quoted 42 lines

[...]

Quoted 13 lines

+/**
+ * hazptr_detach_from_task - Allow a hazard pointer to be released by some other task
+ *
+ * @ctx: The hazard-pointer context to be migrated.
+ *
+ * By default, a given hazptr_acquire() and the corresponding
+ * hazptr_release() must run in a single execution context, for example,
+ * the context of a single task or a single interrupt handler. When you
+ * have acquired a hazard pointer in one context and need to release it
+ * in another, you must invoke hazptr_detach_from_task() on that hazard
+ * pointer's context. It is permissible to invoke hazptr_detach_from_task()
+ * multiple times on the same @ctx while it is protecting the same pointer,
+ * however, the first invocation absolutely must be in the same context

Quoted 8 lines

+ * that did the hazptr_acquire(), and must take place after the return
+ * from that hazptr_acquire().
+ *
+ * For example, if a hazard pointer is acquired by a task and
+ * released by a timer handler, that task would need to pass the hazard
+ * pointer's context to hazptr_detach_from_task() after return from the
+ * hazptr_acquire() and before arming the timer (or at least before the
+ * handler had a chance to access that hazard-pointer context).

good.

Quoted 16 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

include/linux/hazptr.h +5 -2
@@ -160,12 +182,26 @@ void hazptr_note_context_switch(void)
  	}
  }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
   *
   * Load @addr_p, and protect the loaded pointer with hazard pointer.
Quoted 8 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 193

Quoted 4 lines
include/linux/hazptr.h +2 -2
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a later call to hazptr_release().

Perhaps worthwhile to hint at the vast performance/scalability/memory footprint/cache line footprint difference between hazptr and refcount to justify why both exist here ?

Like this?

* Load @addr_p, and protect the loaded pointer with hazard pointer.
* This protection is roughly similar to (but way faster than) that of a
* reference counter, and ends with a later call to hazptr_release()

Quoted 4 lines

AFAIU there is partial overlap between refcount, hazptr, and RCU, each with their own strengths and weaknesses. We should prepare a summary table for the end users wondering which is the right tool for their use-case.

We have lots of such tables of varying sizes and levels of detail in numerous C++ Working Papers, to say nothing of Section 9.6 of perfbook. ;-)

One short text distinguishing them is: "RCU is a fast and scalable replacement for many reader-writer locking use cases, hazard pointers is a fast and scalable replacement for many reference-counting use cases, reader-writer locking provides mutual exclusion, and reference counting provides instant notice when the counter reaches zero."

Quoted 31 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 204

Quoted 11 lines
include/linux/hazptr.h +11 -0
+ *
+ * By default, the call to hazptr_release() must be running in the same
+ * execution context as the corresponding hazptr_acquire(), for example,
+ * within the same task or interrupt handler.  When it is necessary
+ * to instead call hazptr_release() from some other context, pass @ctx
+ * to hazptr_detach_from_task() in the original context after invoking
+ * hazptr_acquire() but before making the hazard pointer available to that
+ * other context.
+ *
+ * It is not permissible to invoke hazptr_acquire() twice on the same @ctx
+ * without an intervening hazptr_release().

good

Quoted 17 lines
include/linux/hazptr.h +10 -1
   *
   * Returns a non-NULL protected address if the loaded pointer is non-NULL.
   * Returns NULL if the loaded pointer is NULL.
@@ -233,7 +269,23 @@ void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
  static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
  #endif
-/* Release the protected hazard pointer from @slot. */
+/**
+ * hazptr_release - Release the specified hazard pointer
+ *
+ * @ctx: The hazard-pointer context that was passed to hazptr_acquire().
+ * @addr_p: The pointer that is to be hazard-pointer unprotected.
+ *
+ * Release the protected hazard pointer recorded in @ctx.
+ *
+ * By default, hazptr_release() must execute in the same execution context
+ * that invoked the corresponding hazptr_acquire(), for example, within the
Quoted 8 lines

include/linux/hazptr.h void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) · line 287

Quoted 6 lines
include/linux/hazptr.h +6 -0
+ * same task or the same interrupt handler.  However, if this restriction
+ * is problematic for your use case, please see hazptr_detach_from_task().
+ *
+ * It is permissible (though unwise from a maintainability viewpoint)
+ * to invoke hazptr_release() twice on the same @ctx without an intervening
+ * hazptr_acquire().

Good!

We might actually be converging! ;-)

Thanx, Paul

author reviewer
#13 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 22 lines · Paul E. McKenney
Quoted 21 lines · Mathieu Desnoyers
Quoted 8 lines · Paul E. McKenney
Quoted 4 lines

We should really rename this given that it detaches the hazptr ctx from the execution _context_ (irq handler or thread). Not sure how to name it though.

hazptr_detach_from_context()?

I am leaving this alone for the moment, easy to change later.

I just wonder if that name brings confusion. Is "context" the execution context or the "hazptr ctx" context ? I fear this is really a good opportunity to confuse everyone.

[...]

Quoted 4 lines
Quoted 2 lines

Maybe just call it hazptr_detach() ?

That would be your choice, not mine. ;-)

Quoted 7 lines
Quoted 3 lines

I find that hazptr_detach is probably better here. It does not state it detaches "what", but at least there is no shortcut confusion with the overloaded "context" wording.

Fair enough.

Would you like me to make this change?

Since you're actively working in that area, please go ahead :)

Quoted 25 lines
Quoted 16 lines
Quoted 16 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

include/linux/hazptr.h +5 -2
@@ -160,12 +182,26 @@ void hazptr_note_context_switch(void)
   	}
   }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
    *
    * Load @addr_p, and protect the loaded pointer with hazard pointer.
Quoted 8 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 193

Quoted 4 lines
include/linux/hazptr.h +2 -2
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a later call to hazptr_release().

Perhaps worthwhile to hint at the vast performance/scalability/memory footprint/cache line footprint difference between hazptr and refcount to justify why both exist here ?

Quoted 5 lines

Like this?

* Load @addr_p, and protect the loaded pointer with hazard pointer.
* This protection is roughly similar to (but way faster than) that of a
* reference counter, and ends with a later call to hazptr_release()

works for me!

Quoted 6 lines
Quoted 5 lines

AFAIU there is partial overlap between refcount, hazptr, and RCU, each with their own strengths and weaknesses. We should prepare a summary table for the end users wondering which is the right tool for their use-case.

Quoted 8 lines

We have lots of such tables of varying sizes and levels of detail in numerous C++ Working Papers, to say nothing of Section 9.6 of perfbook. ;-)

One short text distinguishing them is: "RCU is a fast and scalable replacement for many reader-writer locking use cases, hazard pointers is a fast and scalable replacement for many reference-counting use cases, reader-writer locking provides mutual exclusion, and reference counting provides instant notice when the counter reaches zero."

lgtm

Thanks!

Mathieu

Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#14 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 27 lines · Mathieu Desnoyers
Quoted 26 lines · Paul E. McKenney
Quoted 24 lines · Mathieu Desnoyers
Quoted 8 lines · Paul E. McKenney
Quoted 4 lines

We should really rename this given that it detaches the hazptr ctx from the execution _context_ (irq handler or thread). Not sure how to name it though.

hazptr_detach_from_context()?

I am leaving this alone for the moment, easy to change later.

I just wonder if that name brings confusion. Is "context" the execution context or the "hazptr ctx" context ? I fear this is really a good opportunity to confuse everyone.

[...]

Quoted 4 lines
Quoted 2 lines

Maybe just call it hazptr_detach() ?

That would be your choice, not mine. ;-)

I find that hazptr_detach is probably better here. It does not state it detaches "what", but at least there is no shortcut confusion with the overloaded "context" wording.

Quoted 5 lines
Quoted 3 lines

Fair enough.

Would you like me to make this change?

Since you're actively working in that area, please go ahead :)

OK, rebasing. ;-)

Quoted 25 lines
Quoted 25 lines
Quoted 24 lines
Quoted 10 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

include/linux/hazptr.h +1 -2
@@ -160,12 +182,26 @@ void hazptr_note_context_switch(void)
   	}
   }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 192

Quoted 10 lines
include/linux/hazptr.h +6 -2
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
    *
    * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.
+ * This protection is roughly similar to that of a reference counter, and
+ * ends with a later call to hazptr_release().

Perhaps worthwhile to hint at the vast performance/scalability/memory footprint/cache line footprint difference between hazptr and refcount to justify why both exist here ?

Quoted 7 lines
Quoted 5 lines

Like this?

* Load @addr_p, and protect the loaded pointer with hazard pointer.
* This protection is roughly similar to (but way faster than) that of a
* reference counter, and ends with a later call to hazptr_release()

works for me!

Got it, thank you!

Quoted 8 lines
Quoted 8 lines
Quoted 4 lines

AFAIU there is partial overlap between refcount, hazptr, and RCU, each with their own strengths and weaknesses. We should prepare a summary table for the end users wondering which is the right tool for their use-case.

We have lots of such tables of varying sizes and levels of detail in numerous C++ Working Papers, to say nothing of Section 9.6 of perfbook. ;-)

Quoted 7 lines
Quoted 5 lines

One short text distinguishing them is: "RCU is a fast and scalable replacement for many reader-writer locking use cases, hazard pointers is a fast and scalable replacement for many reference-counting use cases, reader-writer locking provides mutual exclusion, and reference counting provides instant notice when the counter reaches zero."

lgtm

Fair enough! Put this in Documentation/RCU? As a header comment in include/linux/hazptr.h? Somewhere else?

Thanx, Paul

Quoted 8 lines

Thanks!

Mathieu

Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
author reviewer
#15 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

On 2026-07-14 16:54, Paul E. McKenney wrote:
[...]

Quoted 14 lines
Quoted 14 lines
Quoted 13 lines
Quoted 4 lines

AFAIU there is partial overlap between refcount, hazptr, and RCU, each with their own strengths and weaknesses. We should prepare a summary table for the end users wondering which is the right tool for their use-case.

We have lots of such tables of varying sizes and levels of detail in numerous C++ Working Papers, to say nothing of Section 9.6 of perfbook. ;-)

One short text distinguishing them is: "RCU is a fast and scalable replacement for many reader-writer locking use cases, hazard pointers is a fast and scalable replacement for many reference-counting use cases, reader-writer locking provides mutual exclusion, and reference counting provides instant notice when the counter reaches zero."

Quoted 5 lines
Quoted 1 line

lgtm

Fair enough! Put this in Documentation/RCU? As a header comment in include/linux/hazptr.h? Somewhere else?

I'm tempted to add the documentation into Documentation/RCU and a reference to it in the RCU, hazptr, and refcount headers so people stumbling on one of those three can be pointed to the higher level document which explains how each relate to one another.

But is referencing documentation from code even something we typically do ?

Also given this would discuss more than just RCU, I'm not sure Doc/RCU is the right home for it, but we don't have a Documentation/existence nor Documentation/synchronization. Thoughts ?

Thanks,

Mathieu

Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#16 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 27 lines · Mathieu Desnoyers

On 2026-07-14 16:54, Paul E. McKenney wrote:
[...]

Quoted 14 lines
Quoted 14 lines
Quoted 13 lines
Quoted 4 lines

AFAIU there is partial overlap between refcount, hazptr, and RCU, each with their own strengths and weaknesses. We should prepare a summary table for the end users wondering which is the right tool for their use-case.

We have lots of such tables of varying sizes and levels of detail in numerous C++ Working Papers, to say nothing of Section 9.6 of perfbook. ;-)

One short text distinguishing them is: "RCU is a fast and scalable replacement for many reader-writer locking use cases, hazard pointers is a fast and scalable replacement for many reference-counting use cases, reader-writer locking provides mutual exclusion, and reference counting provides instant notice when the counter reaches zero."

Quoted 5 lines
Quoted 1 line

lgtm

Fair enough! Put this in Documentation/RCU? As a header comment in include/linux/hazptr.h? Somewhere else?

I'm tempted to add the documentation into Documentation/RCU and a reference to it in the RCU, hazptr, and refcount headers so people stumbling on one of those three can be pointed to the higher level document which explains how each relate to one another.

Quoted 6 lines

But is referencing documentation from code even something we typically do ?

Also given this would discuss more than just RCU, I'm not sure Doc/RCU is the right home for it, but we don't have a Documentation/existence nor Documentation/synchronization. Thoughts ?

Rename kernel/rcu to kernel/defer and Documentation/RCU to Documentation/defer? I am sure that this would not be at all disruptive. ;-)

Thanx, Paul

maintainer
#17 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

In reply to Mathieu Desnoyers
Quoted 92 lines · Mathieu Desnoyers
Quoted 1 line · Paul E. McKenney

On Thu, Jul 09, 2026 at 05:47:00PM -0400, Mathieu Desnoyers wrote:

[...]

Quoted 37 lines
Quoted 14 lines
Quoted 14 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

include/linux/hazptr.h +5 -2
@@ -160,17 +178,29 @@ void hazptr_note_context_switch(void)
   	}
   }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
Quoted 8 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 168

Quoted 4 lines
include/linux/hazptr.h +0 -2
    *
    * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.

I see that you removed wording of a major constraint here which allowed use of hazptr locally in a interrupt handler: the need to pair the acquire/release within the handler.

I did indeed remove that wording. You could do something like this:

	Task Context			IRQ Handler Interrupts Task
	------------			---------------------------
	preempt_disable();
	ihp = __this_cpu_read(irq_hc);	ihp = __this_cpu_read(irq_hc);
					p = hazptr_acquire(ihp, &gp);
	lp = xchg(p, NULL);
	if (lp) {
		do_something(lp);
		hazptr_release(ihp, lp);
	}
	preempt_enable();
Quoted 3 lines

If I understand the rules correctly (ha!), this is perfectly legal and does not require a hazptr_detach_from_task().

I am concerned about it, because I knowingly just used preempt disable to protect hazptr_acquire from the scheduler, but not from interrupt handlers, because it's faster than irqoff.

I am concerned that this use of hazptr_acquire could confuse the thread-level hazptr_acquire, let's dig:

void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)

{
        struct hazptr_percpu_slots *percpu_slots;
        struct hazptr_slot_item *slot_item;
        struct hazptr_slot *slot;
        void *addr;

        guard(preempt)();
        percpu_slots = this_cpu_ptr(&hazptr_percpu_slots);
        slot_item = &percpu_slots->items[0];
        slot = &slot_item->slot;

[...]

  from here --------------------
        if (unlikely(slot->addr))
                return __hazptr_acquire(ctx, addr_p);
        WRITE_ONCE(slot->addr, HAZPTR_WILDCARD);        /* Store B */
        /* Memory ordering: Store B before Load A. */
        smp_mb();

        /*
         * Load @addr_p after storing wildcard to the hazard pointer slot.
         */
        addr = READ_ONCE(*addr_p);      /* Load A */

        /*
         * We don't care about ordering of Store C. It will simply
         * replace the wildcard by a more specific address. If addr is
         * NULL, we simply store NULL into the slot.
         */
        WRITE_ONCE(slot->addr, addr);   /* Store C */

to here ----------------------------

I designed hazptr_acquire so a _nested_ interrupt which _brings back_ the slot addr to its original state will work. Now let's see if that's still OK if the interrupt handler leaves the slot->addr populated with an address.

And no. If the interrupt happens right before "Store B", its reserved slot address is overwritten by the thread. That's incorrect.

Quoted 7 lines

So as it is today, the irq handler needs to vacate the slot before it returns, either through a hazptr release or a detach.

That being said, this is the code as it is today. If someone finds a clever way to support this use-case and keep it fast and not too complex, I'm all ears! :)

I don't find this use-case is very useful, but I guess a different set of percpu slot for interrupts can resolve this issue?

Regards,
Boqun

Quoted 15 lines

One possible way to make it work would be to install the HAZPTR_WILDCARD with a local-cmpxchg expecting a NULL slot->addr. This would close this race window. But it comes at a non-null overhead price. Another alternative on x86 would be to use a lock prefixed cmpxchg, which has an implied smp_mb on success, which may be in the same ballpark as the sequence of WRITE_ONCE+ explicit smp_mb().

Thanks,

Mathieu

Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
author reviewer
#18 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

Quoted 96 lines · Boqun Feng
Quoted 95 lines · Mathieu Desnoyers
Quoted 1 line · Paul E. McKenney

On Thu, Jul 09, 2026 at 05:47:00PM -0400, Mathieu Desnoyers wrote:

[...]

Quoted 37 lines
Quoted 14 lines
Quoted 14 lines

+ */
static inline
void hazptr_detach_from_task(struct hazptr_ctx *ctx) {

include/linux/hazptr.h +5 -2
@@ -160,17 +178,29 @@ void hazptr_note_context_switch(void)
    	}
    }
-/*
- * hazptr_acquire: Load pointer at address and protect with hazard pointer.
+/**
+ * hazptr_acquire - Load pointer at address and protect with hazard pointer.
+ *
+ * @ctx: The hazard-pointer context to be passed to hazptr_release().
+ * @addr_p: Pointer to the pointer that is to be hazard-pointer protected.
Quoted 8 lines

include/linux/hazptr.h void hazptr_note_context_switch(void) · line 168

Quoted 4 lines
include/linux/hazptr.h +0 -2
     *
     * Load @addr_p, and protect the loaded pointer with hazard pointer.
- * When using hazptr_acquire from interrupt handlers, the acquired slots
- * need to be released before returning from the interrupt handler.

I see that you removed wording of a major constraint here which allowed use of hazptr locally in a interrupt handler: the need to pair the acquire/release within the handler.

I did indeed remove that wording. You could do something like this:

	Task Context			IRQ Handler Interrupts Task
	------------			---------------------------
	preempt_disable();
	ihp = __this_cpu_read(irq_hc);	ihp = __this_cpu_read(irq_hc);
					p = hazptr_acquire(ihp, &gp);
	lp = xchg(p, NULL);
	if (lp) {
		do_something(lp);
		hazptr_release(ihp, lp);
	}
	preempt_enable();
Quoted 3 lines

If I understand the rules correctly (ha!), this is perfectly legal and does not require a hazptr_detach_from_task().

I am concerned about it, because I knowingly just used preempt disable to protect hazptr_acquire from the scheduler, but not from interrupt handlers, because it's faster than irqoff.

I am concerned that this use of hazptr_acquire could confuse the thread-level hazptr_acquire, let's dig:

void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)

{
         struct hazptr_percpu_slots *percpu_slots;
         struct hazptr_slot_item *slot_item;
         struct hazptr_slot *slot;
         void *addr;

         guard(preempt)();
         percpu_slots = this_cpu_ptr(&hazptr_percpu_slots);
         slot_item = &percpu_slots->items[0];
         slot = &slot_item->slot;

[...]

   from here --------------------
         if (unlikely(slot->addr))
                 return __hazptr_acquire(ctx, addr_p);
         WRITE_ONCE(slot->addr, HAZPTR_WILDCARD);        /* Store B */
         /* Memory ordering: Store B before Load A. */
         smp_mb();

         /*
          * Load @addr_p after storing wildcard to the hazard pointer slot.
          */
         addr = READ_ONCE(*addr_p);      /* Load A */

         /*
          * We don't care about ordering of Store C. It will simply
          * replace the wildcard by a more specific address. If addr is
          * NULL, we simply store NULL into the slot.
          */
         WRITE_ONCE(slot->addr, addr);   /* Store C */
    to here ----------------------------

I designed hazptr_acquire so a _nested_ interrupt which _brings back_ the slot addr to its original state will work. Now let's see if that's still OK if the interrupt handler leaves the slot->addr populated with an address.

And no. If the interrupt happens right before "Store B", its reserved slot address is overwritten by the thread. That's incorrect.

So as it is today, the irq handler needs to vacate the slot before it returns, either through a hazptr release or a detach.

Quoted 7 lines
Quoted 4 lines

That being said, this is the code as it is today. If someone finds a clever way to support this use-case and keep it fast and not too complex, I'm all ears! :)

I don't find this use-case is very useful, but I guess a different set of percpu slot for interrupts can resolve this issue?

Correct, but then you add overhead to hazptr synchronize because it needs to consider additional percpu slots.

And then there are softirqs and nmis, so complexity piles up fast.

Maybe not an issue, but it's certainly a tradeoff.

Thanks,

Mathieu

Signature · 3 lines
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com
maintainer
#19 lore raw

Re: [PATCH 2/2] hazptr: Introduce CONFIG_HAZPTR_DEBUG misuse detection

In reply to Paul E. McKenney
Quoted 11 lines · Paul E. McKenney
Quoted 5 lines · Mathieu Desnoyers

Introduce Hazard Pointers debug assert, which detects misuse of hazard pointers, namely failure to detach the hazard pointer from its owner thread before releasing it from a different thread.

Prints the following to the console when a failure is detected:

Thank you, Mathieu!

I am testing this one first to verify the debugging, and then I will test the patch 1/2 hazptrtorture.c changes to verify the fix.

And both tests passed, so thank you!

Quoted 2 lines

We are going to need to carefully document the hazard-pointer handling rules! ;-)

And for that, please see my other email in this thread.

Thanx, Paul

Quoted 145 lines
Quoted 145 lines

Hazard Pointer (addr=000000006885a05f) released on remote task without being detached from task. Acquire: caller=hazptr_torture_read_lock+0x43/0xa0 [hazptrtorture], pid=3727, cpu=1. Release: pid=3725, cpu=139.

WARNING: ./include/linux/hazptr.h:225 at hazptr_torture_read_unlock+0x68/0xf0 [hazptrtorture], CPU#139: hazptr_torture_/3725
Modules linked in: hazptrtorture torture nft_masq nft_chain_nat nf_nat nf_conntrack nf_defrag_ipv6 nf_defrag_ipv4 nf_tables nfnetlink
CPU: 139 UID: 0 PID: 3725 Comm: hazptr_torture_ Not tainted 7.1.0-rc4+ #9 PREEMPT(full)
Hardware name: QEMU Standard PC (Q35 + ICH9, 2009), BIOS 1.16.3-debian-1.16.3-2 04/01/2014
RIP: 0010:hazptr_torture_read_unlock+0x74/0xf0 [hazptrtorture]
Code: 74 31 8b 4f 40 4c 8b 43 48 49 c7 c2 22 c9 56 c0 48 c7 c7 3b c9 56 c0 4c 8d 1d b8 32 f1 ff 52 48 89 fa 4c 89 df 50 51 4c 89 d1 <67> 48 0f b9 3a 48 83 c4 18 48 8b 03 48 8d 53 18 48 c7 00 00 00 00
RSP: 0018:ff621a2a479b3de0 EFLAGS: 00010293
RAX: 0000000000000e8d RBX: ff12ea30d3913488 RCX: ffffffffc056c922
RDX: ffffffffc056c93b RSI: ffffffffc0562280 RDI: ffffffffc0562030
RBP: ff621a2a479b3e50 R08: ffffffffc064ee53 R09: 0000000000000e8f
R10: ffffffffc056c922 R11: ffffffffc0562030 R12: 0000000000000000
R13: ffffffffc0562280 R14: ff12ea30d3913488 R15: ff621a2a479b3e50
FS:  0000000000000000(0000) GS:ff12ea5011a84000(0000) knlGS:0000000000000000
CS:  0010 DS: 0000 ES: 0000 CR0: 0000000080050033
CR2: 00007f39b6e4b010 CR3: 0000000114c6e005 CR4: 0000000000771ef0
PKRU: 55555554
Call Trace:
 <TASK>
 hazptr_torture_reader_tail+0x8e/0x210 [hazptrtorture]
 hazptr_torture_reader+0x145/0xb30 [hazptrtorture]
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? set_cpus_allowed_ptr+0x36/0x60
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? srso_alias_return_thunk+0x5/0xfbef5
 ? __pfx_hazptr_torture_reader+0x10/0x10 [hazptrtorture]
 kthread+0xdf/0x120
 ? __pfx_kthread+0x10/0x10
 ret_from_fork+0x216/0x2d0
 ? __pfx_kthread+0x10/0x10
 ret_from_fork_asm+0x1a/0x30
 </TASK>
---[ end trace 0000000000000000 ]---
---
 include/linux/hazptr.h   | 38 ++++++++++++++++++++++++++++++++++++++
 kernel/rcu/Kconfig.debug |  9 +++++++++
 2 files changed, 47 insertions(+)
include/linux/hazptr.h +38 -0
index d96414575739..c5aa4fb03b11 100644
@@ -51,6 +51,11 @@ struct hazptr_ctx {
 	/* Backup slot in case all per-CPU slots are used. */
 	struct hazptr_backup_slot backup_slot;
 	struct hlist_node preempt_node;
+#ifdef CONFIG_HAZPTR_DEBUG
+	bool detach_task, detach_cpu;	/* Whether the ctx has been detached from task/cpu. */
+	int acquire_pid, acquire_cpu;	/* Note the task and cpu number at acquire. */
+	unsigned long acquire_caller;	/* Acquire instruction pointer. */
+#endif
 };
 
 struct hazptr_slot_ctx {
@@ -127,6 +132,9 @@ void hazptr_detach_from_task(struct hazptr_ctx *ctx)
 	struct hazptr_slot *slot;
 
 	guard(preempt)();
+#ifdef CONFIG_HAZPTR_DEBUG
+	ctx->detach_task = ctx->detach_cpu = true;
+#endif
 	slot = ctx->slot;
 	if (unlikely(hazptr_slot_is_backup(ctx, slot)))
 		return;
@@ -145,6 +153,9 @@ void hazptr_note_context_switch(void)
 
 		if (!slot->addr)
 			continue;
+#ifdef CONFIG_HAZPTR_DEBUG
+		item->ctx.ctx->detach_cpu = true;
+#endif
 		hazptr_promote_to_backup_slot(item->ctx.ctx, slot);
 	}
 }
@@ -173,6 +184,12 @@ void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
 	percpu_slots = this_cpu_ptr(&hazptr_percpu_slots);
 	slot_item = &percpu_slots->items[0];
 	slot = &slot_item->slot;
+#ifdef CONFIG_HAZPTR_DEBUG
+	ctx->detach_cpu = ctx->detach_task = false;
+	ctx->acquire_pid = current->pid;
+	ctx->acquire_cpu = smp_processor_id();
+	ctx->acquire_caller = _THIS_IP_;
+#endif
 	if (unlikely(slot->addr))
 		return __hazptr_acquire(ctx, addr_p);
 	WRITE_ONCE(slot->addr, HAZPTR_WILDCARD);	/* Store B */
@@ -196,6 +213,26 @@ void *hazptr_acquire(struct hazptr_ctx *ctx, void * const *addr_p)
 	return addr;
 }
 
+#ifdef CONFIG_HAZPTR_DEBUG
+/* Called with preemption disabled. */
+static inline
+void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr)
+{
+	int pid = current->pid, cpu = smp_processor_id();
+	bool warn_remote_cpu = !ctx->detach_cpu && ctx->acquire_cpu != cpu,
+	     warn_remote_task = !ctx->detach_task && ctx->acquire_pid != pid;
+
+	WARN_ONCE(warn_remote_cpu || warn_remote_task,
+		"Hazard Pointer (addr=%p) released on remote %s without %s. Acquire: caller=%pS, pid=%d, cpu=%d. Release: pid=%d, cpu=%d.",
+		addr,
+		warn_remote_task ? "task" : "cpu",
+		warn_remote_task ? "being detached from task" : "context switch",
+		(void *) ctx->acquire_caller, ctx->acquire_pid, ctx->acquire_cpu, pid, cpu);
+}
+#else
+static inline void hazptr_release_debug(struct hazptr_ctx *ctx, void *addr) { }
+#endif
+
 /* Release the protected hazard pointer from @slot. */
 static inline
 void hazptr_release(struct hazptr_ctx *ctx, void *addr)
@@ -205,6 +242,7 @@ void hazptr_release(struct hazptr_ctx *ctx, void *addr)
 	if (!addr)
 		return;
 	guard(preempt)();
+	hazptr_release_debug(ctx, addr);
 	slot = ctx->slot;
 	smp_store_release(&slot->addr, NULL);
 	if (unlikely(hazptr_slot_is_backup(ctx, slot)))
kernel/rcu/Kconfig.debug +9 -0
index 7629c345b0b6..57fec4444a97 100644
@@ -264,4 +264,13 @@ config TRIVIAL_PREEMPT_RCU
 
 	  This has no value for production and is only for testing.
 
+config HAZPTR_DEBUG
+	bool "Provide debugging asserts for Hazard Pointers"
+	depends on DEBUG_KERNEL
+	default n
+	help
+	  This option provides consistency checks for Hazard pointers.
+
+	  Say Y here if you want to enable those assert, N otherwise.
+
 endmenu # "RCU Debugging"
Signature · 1 line
2.43.0