What is an atomic context trap?

Atomic context traps occur when code runs in a context where sleeping is illegal (e.g., while holding a spinlock). Tools like CONFIG_DEBUG_ATOMIC_SLEEP help catch these mistakes, and RCUs forbid sleep in read-side sections.

How should GFP_ATOMIC allocations be handled?

GFP_ATOMIC may return NULL. Always check the result, consider preallocation to avoid OOM, and prefer kzalloc to avoid leaking kernel info to userspace.

Why does copy_from_user return bytes not copied, and 0 means success?

copy_from_user returns the number of bytes that could not be copied. A return value of 0 means the copy succeeded; non-zero indicates partial or complete failure that must be handled.

Kernel

Verified

@ivangdavila

npx machina-cli add skill @ivangdavila/kernel --openclaw

Files (1)

SKILL.md

2.1 KB

Atomic Context Traps

spin_lock held = cannot sleep — no kmalloc(GFP_KERNEL), no mutex_lock, no copy_from_user
Interrupt can take same spinlock — must use spin_lock_irqsave, not plain spin_lock
rcu_read_lock() section cannot sleep — no blocking calls inside RCU read-side
might_sleep() annotation — add to functions that may sleep, catches bugs with CONFIG_DEBUG_ATOMIC_SLEEP

Allocation Failures

GFP_ATOMIC can return NULL — always check, don't assume success
vmalloc memory not physically contiguous — cannot use for DMA
kzalloc over kmalloc — uninitialized memory leaks kernel info to userspace
Allocation in loop risks OOM — preallocate or use memory pool

User Pointer Handling

copy_from_user returns bytes NOT copied — 0 means success, not failure
Never use %s with user pointer in printk — kernel crash or info leak
User memory can change during syscall — copy to kernel buffer, validate the copy
__user annotation is documentation — doesn't enforce anything, you must use copy functions

Memory Ordering

READ_ONCE/WRITE_ONCE for lockless shared data — prevents compiler from caching/reordering
Spinlock release has implicit barrier — but check-then-act patterns still need care
smp_wmb() before publishing pointer — ensures data visible before pointer is

Module Error Paths

Init fails midway — must undo everything already done
Reverse order cleanup — unregister in opposite order of register
goto err_* pattern standard — cleaner than nested ifs
Check what's actually initialized — don't free/unregister what wasn't set up

Locking Mistakes

Same lock acquired twice = deadlock — even in different functions
Inconsistent lock ordering — document order, acquire in same sequence everywhere
mutex_trylock returns 1 on success — opposite of pthread_mutex_trylock
Reader-writer locks rarely worth it — contention overhead usually exceeds benefit

Source

git clone https://clawhub.ai/ivangdavila/kernelView on GitHub

Overview

Kernel developers must avoid atomic context violations, allocation failures, and unsafe user-pointer handling. This skill consolidates traps across atomic contexts, memory ordering, and error paths to keep kernel code reliable and performant. Following these patterns helps prevent crashes, deadlocks, and information leakage.

How This Skill Works

Code in the kernel must respect atomic contexts and memory barriers. The guidance covers annotating may_sleep for potentially sleeping code, selecting proper GFP flags, and validating copy_from_user results. It also emphasizes clean error paths, reverse cleanup, and correct lock discipline to avoid subtle bugs.

When to Use It

Writing interrupt or atomic context code that must not sleep and uses spinlocks or RCUs
Allocating memory in atomic or high-priority contexts where GFP_ATOMIC may be required
Handling user-space data in system calls, especially copy_from_user and printk usage
Designing lock-free data paths and ensuring proper memory ordering with READ_ONCE/WRITE_ONCE and barriers
Implementing module init/exit paths with robust error handling and reverse-order cleanup

Quick Start

Step 1: Identify atomic-context boundaries and annotate may_sleep for functions that may sleep
Step 2: Choose correct allocation flags (GFP_ATOMIC or preallocate) and always check for NULL; avoid loops that can OOM
Step 3: Safely handle user memory with copy_from_user, avoid using user pointers in printk, and apply memory-ordering barriers (READ_ONCE/WRITE_ONCE)

Best Practices

Annotate may_sleep() on functions that may sleep and use CONFIG_DEBUG_ATOMIC_SLEEP
Prefer GFP_ATOMIC when allocating in atomic contexts; always check for NULL and preallocate to avoid OOM
Use copy_from_user to bring data safely into kernel space and validate the copy; avoid using user pointers in printk
Use READ_ONCE/WRITE_ONCE for lockless shared data and ensure proper barriers around publishes
Implement module init/exit with reverse-order cleanup and goto err_* paths

Example Use Cases

An interrupt handler that acquires a spinlock must use spin_lock_irqsave instead of plain spin_lock
RCU read-side sections cannot sleep, so avoid blocking calls inside them
Allocate memory with GFP flags appropriate to the context and check for NULL; kzalloc is often preferred to avoid uninitialized leaks
Copy user data with copy_from_user and validate the number of bytes copied; do not treat 0 as a failure
When an init path fails, unwind in reverse order and use a goto err_* pattern

Frequently Asked Questions

Add this skill to your agents