Documentation/core-api/debug-objects.rst

   1 ============================================
   2 The object-lifetime debugging infrastructure
   3 ============================================
   4
   5 :Author: Thomas Gleixner
   6
   7 Introduction
   8 ============
   9
  10 debugobjects is a generic infrastructure to track the life time of
  11 kernel objects and validate the operations on those.
  12
  13 debugobjects is useful to check for the following error patterns:
  14
  15 -  Activation of uninitialized objects
  16
  17 -  Initialization of active objects
  18
  19 -  Usage of freed/destroyed objects
  20
  21 debugobjects is not changing the data structure of the real object so it
  22 can be compiled in with a minimal runtime impact and enabled on demand
  23 with a kernel command line option.
  24
  25 Howto use debugobjects
  26 ======================
  27
  28 A kernel subsystem needs to provide a data structure which describes the
  29 object type and add calls into the debug code at appropriate places. The
  30 data structure to describe the object type needs at minimum the name of
  31 the object type. Optional functions can and should be provided to fixup
  32 detected problems so the kernel can continue to work and the debug
  33 information can be retrieved from a live system instead of hard core
  34 debugging with serial consoles and stack trace transcripts from the
  35 monitor.
  36
  37 The debug calls provided by debugobjects are:
  38
  39 -  debug_object_init
  40
  41 -  debug_object_init_on_stack
  42
  43 -  debug_object_activate
  44
  45 -  debug_object_deactivate
  46
  47 -  debug_object_destroy
  48
  49 -  debug_object_free
  50
  51 -  debug_object_assert_init
  52
  53 Each of these functions takes the address of the real object and a
  54 pointer to the object type specific debug description structure.
  55
  56 Each detected error is reported in the statistics and a limited number
  57 of errors are printk'ed including a full stack trace.
  58
  59 The statistics are available via /sys/kernel/debug/debug_objects/stats.
  60 They provide information about the number of warnings and the number of
  61 successful fixups along with information about the usage of the internal
  62 tracking objects and the state of the internal tracking objects pool.
  63
  64 Debug functions
  65 ===============
  66
  67 .. kernel-doc:: lib/debugobjects.c
  68    :functions: debug_object_init
  69
  70 This function is called whenever the initialization function of a real
  71 object is called.
  72
  73 When the real object is already tracked by debugobjects it is checked,
  74 whether the object can be initialized. Initializing is not allowed for
  75 active and destroyed objects. When debugobjects detects an error, then
  76 it calls the fixup_init function of the object type description
  77 structure if provided by the caller. The fixup function can correct the
  78 problem before the real initialization of the object happens. E.g. it
  79 can deactivate an active object in order to prevent damage to the
  80 subsystem.
  81
  82 When the real object is not yet tracked by debugobjects, debugobjects
  83 allocates a tracker object for the real object and sets the tracker
  84 object state to ODEBUG_STATE_INIT. It verifies that the object is not
  85 on the callers stack. If it is on the callers stack then a limited
  86 number of warnings including a full stack trace is printk'ed. The
  87 calling code must use debug_object_init_on_stack() and remove the
  88 object before leaving the function which allocated it. See next section.
  89
  90 .. kernel-doc:: lib/debugobjects.c
  91    :functions: debug_object_init_on_stack
  92
  93 This function is called whenever the initialization function of a real
  94 object which resides on the stack is called.
  95
  96 When the real object is already tracked by debugobjects it is checked,
  97 whether the object can be initialized. Initializing is not allowed for
  98 active and destroyed objects. When debugobjects detects an error, then
  99 it calls the fixup_init function of the object type description
 100 structure if provided by the caller. The fixup function can correct the
 101 problem before the real initialization of the object happens. E.g. it
 102 can deactivate an active object in order to prevent damage to the
 103 subsystem.
 104
 105 When the real object is not yet tracked by debugobjects debugobjects
 106 allocates a tracker object for the real object and sets the tracker
 107 object state to ODEBUG_STATE_INIT. It verifies that the object is on
 108 the callers stack.
 109
 110 An object which is on the stack must be removed from the tracker by
 111 calling debug_object_free() before the function which allocates the
 112 object returns. Otherwise we keep track of stale objects.
 113
 114 .. kernel-doc:: lib/debugobjects.c
 115    :functions: debug_object_activate
 116
 117 This function is called whenever the activation function of a real
 118 object is called.
 119
 120 When the real object is already tracked by debugobjects it is checked,
 121 whether the object can be activated. Activating is not allowed for
 122 active and destroyed objects. When debugobjects detects an error, then
 123 it calls the fixup_activate function of the object type description
 124 structure if provided by the caller. The fixup function can correct the
 125 problem before the real activation of the object happens. E.g. it can
 126 deactivate an active object in order to prevent damage to the subsystem.
 127
 128 When the real object is not yet tracked by debugobjects then the
 129 fixup_activate function is called if available. This is necessary to
 130 allow the legitimate activation of statically allocated and initialized
 131 objects. The fixup function checks whether the object is valid and calls
 132 the debug_objects_init() function to initialize the tracking of this
 133 object.
 134
 135 When the activation is legitimate, then the state of the associated
 136 tracker object is set to ODEBUG_STATE_ACTIVE.
 137
 138
 139 .. kernel-doc:: lib/debugobjects.c
 140    :functions: debug_object_deactivate
 141
 142 This function is called whenever the deactivation function of a real
 143 object is called.
 144
 145 When the real object is tracked by debugobjects it is checked, whether
 146 the object can be deactivated. Deactivating is not allowed for untracked
 147 or destroyed objects.
 148
 149 When the deactivation is legitimate, then the state of the associated
 150 tracker object is set to ODEBUG_STATE_INACTIVE.
 151
 152 .. kernel-doc:: lib/debugobjects.c
 153    :functions: debug_object_destroy
 154
 155 This function is called to mark an object destroyed. This is useful to
 156 prevent the usage of invalid objects, which are still available in
 157 memory: either statically allocated objects or objects which are freed
 158 later.
 159
 160 When the real object is tracked by debugobjects it is checked, whether
 161 the object can be destroyed. Destruction is not allowed for active and
 162 destroyed objects. When debugobjects detects an error, then it calls the
 163 fixup_destroy function of the object type description structure if
 164 provided by the caller. The fixup function can correct the problem
 165 before the real destruction of the object happens. E.g. it can
 166 deactivate an active object in order to prevent damage to the subsystem.
 167
 168 When the destruction is legitimate, then the state of the associated
 169 tracker object is set to ODEBUG_STATE_DESTROYED.
 170
 171 .. kernel-doc:: lib/debugobjects.c
 172    :functions: debug_object_free
 173
 174 This function is called before an object is freed.
 175
 176 When the real object is tracked by debugobjects it is checked, whether
 177 the object can be freed. Free is not allowed for active objects. When
 178 debugobjects detects an error, then it calls the fixup_free function of
 179 the object type description structure if provided by the caller. The
 180 fixup function can correct the problem before the real free of the
 181 object happens. E.g. it can deactivate an active object in order to
 182 prevent damage to the subsystem.
 183
 184 Note that debug_object_free removes the object from the tracker. Later
 185 usage of the object is detected by the other debug checks.
 186
 187
 188 .. kernel-doc:: lib/debugobjects.c
 189    :functions: debug_object_assert_init
 190
 191 This function is called to assert that an object has been initialized.
 192
 193 When the real object is not tracked by debugobjects, it calls
 194 fixup_assert_init of the object type description structure provided by
 195 the caller, with the hardcoded object state ODEBUG_NOT_AVAILABLE. The
 196 fixup function can correct the problem by calling debug_object_init
 197 and other specific initializing functions.
 198
 199 When the real object is already tracked by debugobjects it is ignored.
 200
 201 Fixup functions
 202 ===============
 203
 204 Debug object type description structure
 205 ---------------------------------------
 206
 207 .. kernel-doc:: include/linux/debugobjects.h
 208    :internal:
 209
 210 fixup_init
 211 -----------
 212
 213 This function is called from the debug code whenever a problem in
 214 debug_object_init is detected. The function takes the address of the
 215 object and the state which is currently recorded in the tracker.
 216
 217 Called from debug_object_init when the object state is:
 218
 219 -  ODEBUG_STATE_ACTIVE
 220
 221 The function returns true when the fixup was successful, otherwise
 222 false. The return value is used to update the statistics.
 223
 224 Note, that the function needs to call the debug_object_init() function
 225 again, after the damage has been repaired in order to keep the state
 226 consistent.
 227
 228 fixup_activate
 229 ---------------
 230
 231 This function is called from the debug code whenever a problem in
 232 debug_object_activate is detected.
 233
 234 Called from debug_object_activate when the object state is:
 235
 236 -  ODEBUG_STATE_NOTAVAILABLE
 237
 238 -  ODEBUG_STATE_ACTIVE
 239
 240 The function returns true when the fixup was successful, otherwise
 241 false. The return value is used to update the statistics.
 242
 243 Note that the function needs to call the debug_object_activate()
 244 function again after the damage has been repaired in order to keep the
 245 state consistent.
 246
 247 The activation of statically initialized objects is a special case. When
 248 debug_object_activate() has no tracked object for this object address
 249 then fixup_activate() is called with object state
 250 ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether
 251 this is a legitimate case of a statically initialized object or not. In
 252 case it is it calls debug_object_init() and debug_object_activate()
 253 to make the object known to the tracker and marked active. In this case
 254 the function should return false because this is not a real fixup.
 255
 256 fixup_destroy
 257 --------------
 258
 259 This function is called from the debug code whenever a problem in
 260 debug_object_destroy is detected.
 261
 262 Called from debug_object_destroy when the object state is:
 263
 264 -  ODEBUG_STATE_ACTIVE
 265
 266 The function returns true when the fixup was successful, otherwise
 267 false. The return value is used to update the statistics.
 268
 269 fixup_free
 270 -----------
 271
 272 This function is called from the debug code whenever a problem in
 273 debug_object_free is detected. Further it can be called from the debug
 274 checks in kfree/vfree, when an active object is detected from the
 275 debug_check_no_obj_freed() sanity checks.
 276
 277 Called from debug_object_free() or debug_check_no_obj_freed() when
 278 the object state is:
 279
 280 -  ODEBUG_STATE_ACTIVE
 281
 282 The function returns true when the fixup was successful, otherwise
 283 false. The return value is used to update the statistics.
 284
 285 fixup_assert_init
 286 -------------------
 287
 288 This function is called from the debug code whenever a problem in
 289 debug_object_assert_init is detected.
 290
 291 Called from debug_object_assert_init() with a hardcoded state
 292 ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug
 293 bucket.
 294
 295 The function returns true when the fixup was successful, otherwise
 296 false. The return value is used to update the statistics.
 297
 298 Note, this function should make sure debug_object_init() is called
 299 before returning.
 300
 301 The handling of statically initialized objects is a special case. The
 302 fixup function should check if this is a legitimate case of a statically
 303 initialized object or not. In this case only debug_object_init()
 304 should be called to make the object known to the tracker. Then the
 305 function should return false because this is not a real fixup.
 306
 307 Known Bugs And Assumptions
 308 ==========================
 309
 310 None (knock on wood).