linux/Documentation/userspace-api
Suren Baghdasaryan 1d581ab234 alloc_tag: add ioctl to /proc/allocinfo
Patch series "alloc_tag: introduce IOCTL-based filtering for MAP", v8.

Currently, memory allocation profiling data is primarily exposed through
/proc/allocinfo.  While useful for manual inspection, this text-based
interface poses challenges for production monitoring and large-scale
analysis:

1. Userspace must parse large amounts of text to extract specific
fields.
2. To find specific tags, userspace must read the entire dataset,
requiring many context switches and high data copying.
3. The kernel currently aggregates per-CPU counters for every allocation
size, even those the user intends to filter out immediately.

This series introduces a new IOCTL-based binary interface for allocinfo
that supports kernel-side filtering.  By allowing the user to specify a
filter mask, we significantly reduce the work performed in-kernel and the
amount of data transferred to userspace.  The IOCTL mechanism was chosen
for allocinfo to address the per-CPU counter aggregation bottleneck.  A
traditional read() operation must report the total allocation count and
sizes for every code tag in the system.  Doing so requires iterating
across all CPUs to sum their per-CPU counters for thousands of tags, which
introduces substantial runtime overhead.

The IOCTL interface allows userspace to push selective filtering criteria
directly into the kernel before the per-CPU counter aggregation.  The
kernel aggregates per-CPU counters only for a small subset of tags that
match the filter.  This results in significant performance improvement.

Beyond fast filtered retrieval, the IOCTL foundation allows introducing a
context capture mechanism in the future to capture the context for
specific allocations.

Performance measurements were conducted on an Intel Xeon Platinum 8481C
(224 CPUs) with caches dropped before each run.

The IOCTL mechanism shows a ~20x performance improvement for
filtered queries. The kernel avoids the expensive per-CPU counter
aggregation (alloc_tag_read) for any tags that fail the initial string
or location filters.

Scenario 1: Specific File Filtering (arch/x86/events/rapl.c)
1. Traditional (cat /proc/allocinfo | grep): 22ms (sys)
2. IOCTL Interface: 1ms (sys)

Scenario 2: Compound Filtering (Filename + Size)
1. Traditional: (cat ... | grep | awk): 21ms (sys)
2. IOCTL Interface: 1ms (sys)

Scenario 3: Size-Based Filtering (min_size = 1MB)
1. Traditional: (cat ... | awk): 21ms (sys)
2. IOCTL Interface: 14ms (sys)


This patch (of 6):

Add the following ioctl commands for /proc/allocinfo file:

ALLOCINFO_IOC_CONTENT_ID - gets content identifier which can be used to
check whether the file content has changed specifically due to module
load/unload.  Every time a module is loaded / unloaded, the returned value
will be different.  By comparing the identifier value at the beginning and
at the end of the content retrieval operation, users can validate
retrieved information for consistency.

ALLOCINFO_IOC_GET_AT - gets the record at the specified position.  This is
the position of a record in /proc/allocinfo.

ALLOCINFO_IOC_GET_NEXT - gets the record next to the last retrieved one. 
If no records were previously retrieved, returns the first record.

Note, function file and module names often have the same prefixes,
therefore when filtering for them, we compare the last 64 characters to
minimize the chances of name collisions.

[akpm@linux-foundation.org: include compat.h, per Suren]
  Closes: https://lore.kernel.org/oe-kbuild-all/202607091820.qbjlGhKK-lkp@intel.com/
Link: https://lore.kernel.org/cover.1783532853.git.abhishekbapat@google.com
Link: https://lore.kernel.org/15596de2607ef13e7c77c6d74763f4ae992ec475.1783532853.git.abhishekbapat@google.com
Signed-off-by: Suren Baghdasaryan <surenb@google.com>
Signed-off-by: Abhishek Bapat <abhishekbapat@google.com>
Acked-by: Hao Ge <hao.ge@linux.dev>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Kent Overstreet <kent.overstreet@linux.dev>
Cc: Sourav Panda <souravpanda@google.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
2026-08-24 18:43:12 -07:00
..
accelerators Documentation: ocxl.rst: Update consortium site 2025-03-12 16:26:45 -06:00
ebpf
fwctl fwctl/bnxt_fwctl: Add documentation entries 2026-03-31 13:33:55 -03:00
gpio Documentation: use a source-read extension for the index link boilerplate 2026-01-23 11:59:34 -07:00
ioctl alloc_tag: add ioctl to /proc/allocinfo 2026-08-24 18:43:12 -07:00
media Documentation: media: add CEC opcodes 2026-05-19 17:53:04 +02:00
netlink docs: netlink: Correct buffer sizing info 2026-05-15 15:52:18 -07:00
check_exec.rst security: Add EXEC_RESTRICT_FILE and EXEC_DENY_INTERACTIVE securebits 2024-12-18 17:00:29 -08:00
dcdbas.rst Documentation: move driver-api/dcdbas to userspace-api/ 2024-01-03 14:17:40 -07:00
dma-buf-alloc-exchange.rst doc: uapi: Add document describing dma-buf semantics 2023-08-21 18:20:05 +02:00
dma-buf-heaps.rst dma-buf: heaps: system: document system_cc_shared heap 2026-04-10 14:20:01 +02:00
ELF.rst
futex2.rst
index.rst Scheduler changes for v7.0: 2026-02-10 12:50:10 -08:00
iommufd.rst iommufd: Fix spelling errors in iommufd.rst 2025-08-18 11:15:06 -03:00
isapnp.rst Documentation: move driver-api/isapnp to userspace-api/ 2024-01-03 14:17:39 -07:00
landlock.rst landlock: Add API support and docs for the quiet flags 2026-06-14 20:17:19 +02:00
liveupdate.rst liveupdate: document current compatibility status 2026-06-01 09:19:38 +03:00
lsm.rst LSM: Create lsm_list_modules system call 2023-11-12 22:54:42 -05:00
mfd_noexec.rst mm/memfd: add documentation for MFD_NOEXEC_SEAL MFD_EXEC 2024-06-15 10:43:07 -07:00
mseal.rst mm/mseal: fix mseal documentation for 32-bit kernels 2026-08-06 18:57:12 -07:00
no_new_privs.rst
ntsync.rst docs: ntsync: Add documentation for the ntsync uAPI. 2025-01-08 13:18:12 +01:00
perf_ring_buffer.rst coresight: docs: Remove target sink from examples 2025-03-11 14:55:57 +00:00
rseq.rst rseq: Reenable performance optimizations conditionally 2026-05-06 17:40:27 +02:00
seccomp_filter.rst
spec_ctrl.rst Documentation/x86: Fix PR_SET_SPECULATION_CTRL error codes 2025-12-29 16:27:45 +01:00
sysfs-platform_profile.rst docs: Fix typos, improve grammar in Userspace API 2025-06-09 15:13:33 -06:00
tee.rst Documentation: Destage TEE subsystem documentation 2023-12-08 15:45:10 -07:00
unshare.rst
vduse.rst Documentation: Add documentation for VDUSE Address Space IDs 2026-01-28 15:32:18 -05:00