allocation-profiling.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3===========================
  4MEMORY ALLOCATION PROFILING
  5===========================
  6
  7Low overhead (suitable for production) accounting of all memory allocations,
  8tracked by file and line number.
  9
 10Usage:
 11kconfig options:
 12- CONFIG_MEM_ALLOC_PROFILING
 13
 14- CONFIG_MEM_ALLOC_PROFILING_ENABLED_BY_DEFAULT
 15
 16- CONFIG_MEM_ALLOC_PROFILING_DEBUG
 17  adds warnings for allocations that weren't accounted because of a
 18  missing annotation
 19
 20Boot parameter:
 21  sysctl.vm.mem_profiling={0|1|never}[,compressed]
 22
 23  When set to "never", memory allocation profiling overhead is minimized and it
 24  cannot be enabled at runtime (sysctl becomes read-only).
 25  When CONFIG_MEM_ALLOC_PROFILING_ENABLED_BY_DEFAULT=y, default value is "1".
 26  When CONFIG_MEM_ALLOC_PROFILING_ENABLED_BY_DEFAULT=n, default value is "never".
 27  "compressed" optional parameter will try to store page tag references in a
 28  compact format, avoiding page extensions. This results in improved performance
 29  and memory consumption, however it might fail depending on system configuration.
 30  If compression fails, a warning is issued and memory allocation profiling gets
 31  disabled.
 32
 33sysctl:
 34  /proc/sys/vm/mem_profiling
 35
 36  1: Enable memory profiling.
 37
 38  0: Disable memory profiling.
 39
 40  The default value depends on CONFIG_MEM_ALLOC_PROFILING_ENABLED_BY_DEFAULT.
 41
 42  When CONFIG_MEM_ALLOC_PROFILING_DEBUG=y, this control is read-only to avoid
 43  warnings produced by allocations made while profiling is disabled and freed
 44  when it's enabled.
 45
 46Runtime info:
 47  /proc/allocinfo
 48
 49Example output::
 50
 51  root@moria-kvm:~# sort -g /proc/allocinfo|tail|numfmt --to=iec
 52        2.8M    22648 fs/kernfs/dir.c:615 func:__kernfs_new_node
 53        3.8M      953 mm/memory.c:4214 func:alloc_anon_folio
 54        4.0M     1010 drivers/staging/ctagmod/ctagmod.c:20 [ctagmod] func:ctagmod_start
 55        4.1M        4 net/netfilter/nf_conntrack_core.c:2567 func:nf_ct_alloc_hashtable
 56        6.0M     1532 mm/filemap.c:1919 func:__filemap_get_folio
 57        8.8M     2785 kernel/fork.c:307 func:alloc_thread_stack_node
 58         13M      234 block/blk-mq.c:3421 func:blk_mq_alloc_rqs
 59         14M     3520 mm/mm_init.c:2530 func:alloc_large_system_hash
 60         15M     3656 mm/readahead.c:247 func:page_cache_ra_unbounded
 61         55M     4887 mm/slub.c:2259 func:alloc_slab_page
 62        122M    31168 mm/page_ext.c:270 func:alloc_page_ext
 63
 64Theory of operation
 65===================
 66
 67Memory allocation profiling builds off of code tagging, which is a library for
 68declaring static structs (that typically describe a file and line number in
 69some way, hence code tagging) and then finding and operating on them at runtime,
 70- i.e. iterating over them to print them in debugfs/procfs.
 71
 72To add accounting for an allocation call, we replace it with a macro
 73invocation, alloc_hooks(), that
 74- declares a code tag
 75- stashes a pointer to it in task_struct
 76- calls the real allocation function
 77- and finally, restores the task_struct alloc tag pointer to its previous value.
 78
 79This allows for alloc_hooks() calls to be nested, with the most recent one
 80taking effect. This is important for allocations internal to the mm/ code that
 81do not properly belong to the outer allocation context and should be counted
 82separately: for example, slab object extension vectors, or when the slab
 83allocates pages from the page allocator.
 84
 85Thus, proper usage requires determining which function in an allocation call
 86stack should be tagged. There are many helper functions that essentially wrap
 87e.g. kmalloc() and do a little more work, then are called in multiple places;
 88we'll generally want the accounting to happen in the callers of these helpers,
 89not in the helpers themselves.
 90
 91To fix up a given helper, for example foo(), do the following:
 92- switch its allocation call to the _noprof() version, e.g. kmalloc_noprof()
 93
 94- rename it to foo_noprof()
 95
 96- define a macro version of foo() like so:
 97
 98  #define foo(...) alloc_hooks(foo_noprof(__VA_ARGS__))
 99
100It's also possible to stash a pointer to an alloc tag in your own data structures.
101
102Do this when you're implementing a generic data structure that does allocations
103"on behalf of" some other code - for example, the rhashtable code. This way,
104instead of seeing a large line in /proc/allocinfo for rhashtable.c, we can
105break it out by rhashtable type.
106
107To do so:
108- Hook your data structure's init function, like any other allocation function.
109
110- Within your init function, use the convenience macro alloc_tag_record() to
111  record alloc tag in your data structure.
112
113- Then, use the following form for your allocations:
114  alloc_hooks_tag(ht->your_saved_tag, kmalloc_noprof(...))