Documentation/mm/allocation-profiling.rst

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