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