kernel/2.6.29.6-aldebaran-rt/Documentation/kmemcheck.txt

   1 Contents
   2 ========
   3
   4   1. How to use
   5   2. Technical description
   6   3. Changes to the slab allocators
   7   4. Problems
   8   5. Parameters
   9   6. Future enhancements
  10
  11
  12 How to use (IMPORTANT)
  13 ======================
  14
  15 Always remember this: kmemcheck _will_ give false positives. So don't enable
  16 it and spam the mailing list with its reports; you are not going to be heard,
  17 and it will make people's skins thicker for when the real errors are found.
  18
  19 Instead, I encourage maintainers and developers to find errors in _their_
  20 _own_ code. And if you find false positives, you can try to work around them,
  21 try to figure out if it's a real bug or not, or simply ignore them. Most
  22 developers know their own code and will quickly and efficiently determine the
  23 root cause of a kmemcheck report. This is therefore also the most efficient
  24 way to work with kmemcheck.
  25
  26 If you still want to run kmemcheck to inspect others' code, the rule of thumb
  27 should be: If it's not obvious (to you), don't tell us about it either. Most
  28 likely the code is correct and you'll only waste our time. If you can work
  29 out the error, please do send the maintainer a heads up and/or a patch, but
  30 don't expect him/her to fix something that wasn't wrong in the first place.
  31
  32
  33 Technical description
  34 =====================
  35
  36 kmemcheck works by marking memory pages non-present. This means that whenever
  37 somebody attempts to access the page, a page fault is generated. The page
  38 fault handler notices that the page was in fact only hidden, and so it calls
  39 on the kmemcheck code to make further investigations.
  40
  41 When the investigations are completed, kmemcheck "shows" the page by marking
  42 it present (as it would be under normal circumstances). This way, the
  43 interrupted code can continue as usual.
  44
  45 But after the instruction has been executed, we should hide the page again, so
  46 that we can catch the next access too! Now kmemcheck makes use of a debugging
  47 feature of the processor, namely single-stepping. When the processor has
  48 finished the one instruction that generated the memory access, a debug
  49 exception is raised. From here, we simply hide the page again and continue
  50 execution, this time with the single-stepping feature turned off.
  51
  52
  53 Changes to the slab allocators
  54 ==============================
  55
  56 kmemcheck requires some assistance from the memory allocator in order to work.
  57 The memory allocator needs to
  58
  59 1. Tell kmemcheck about newly allocated pages and pages that are about to
  60    be freed. This allows kmemcheck to set up and tear down the shadow memory
  61    for the pages in question. The shadow memory stores the status of each byte
  62    in the allocation proper, e.g. whether it is initialized or uninitialized.
  63 2. Tell kmemcheck which parts of memory should be marked uninitialized. There
  64    are actually a few more states, such as "not yet allocated" and "recently
  65    freed".
  66
  67 If a slab cache is set up using the SLAB_NOTRACK flag, it will never return
  68 memory that can take page faults because of kmemcheck.
  69
  70 If a slab cache is NOT set up using the SLAB_NOTRACK flag, callers can still
  71 request memory with the __GFP_NOTRACK flag. This does not prevent the page
  72 faults from occurring, however, but marks the object in question as being
  73 initialized so that no warnings will ever be produced for this object.
  74
  75 Currently, the SLAB and SLUB allocators are supported by kmemcheck.
  76
  77
  78 Problems
  79 ========
  80
  81 The most prominent problem seems to be that of bit-fields. kmemcheck can only
  82 track memory with byte granularity. Therefore, when gcc generates code to
  83 access only one bit in a bit-field, there is really no way for kmemcheck to
  84 know which of the other bits will be used or thrown away. Consequently, there
  85 may be bogus warnings for bit-field accesses. We have added a "bitfields" API
  86 to get around this problem. See include/linux/kmemcheck.h for detailed
  87 instructions!
  88
  89
  90 Parameters
  91 ==========
  92
  93 In addition to enabling CONFIG_KMEMCHECK before the kernel is compiled, the
  94 parameter kmemcheck=1 must be passed to the kernel when it is started in order
  95 to actually do the tracking. So by default, there is only a very small
  96 (probably negligible) overhead for enabling the config option.
  97
  98 Similarly, kmemcheck may be turned on or off at run-time using, respectively:
  99
 100 echo 1 > /proc/sys/kernel/kmemcheck
 101         and
 102 echo 0 > /proc/sys/kernel/kmemcheck
 103
 104 Note that this is a lazy setting; once turned off, the old allocations will
 105 still have to take a single page fault exception before tracking is turned off
 106 for that particular page. Enabling kmemcheck on will only enable tracking for
 107 allocations made from that point onwards.
 108
 109 The default mode is the one-shot mode, where only the first error is reported
 110 before kmemcheck is disabled. This mode can be enabled by passing kmemcheck=2
 111 to the kernel at boot, or running
 112
 113 echo 2 > /proc/sys/kernel/kmemcheck
 114
 115 when the kernel is already running.
 116
 117
 118 Future enhancements
 119 ===================
 120
 121 There is already some preliminary support for catching use-after-free errors.
 122 What still needs to be done is delaying kfree() so that memory is not
 123 reallocated immediately after freeing it. [Suggested by Pekka Enberg.]
 124
 125 It should be possible to allow SMP systems by duplicating the page tables for
 126 each processor in the system. This is probably extremely difficult, however.
 127 [Suggested by Ingo Molnar.]
 128
 129 Support for instruction set extensions like XMM, SSE2, etc.