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 67Debug object function reference 68------------------------------- 69 70.. kernel-doc:: lib/debugobjects.c 71 :export: 72 73debug_object_init 74------------------- 75 76This function is called whenever the initialization function of a real 77object is called. 78 79When the real object is already tracked by debugobjects it is checked, 80whether the object can be initialized. Initializing is not allowed for 81active and destroyed objects. When debugobjects detects an error, then 82it calls the fixup_init function of the object type description 83structure if provided by the caller. The fixup function can correct the 84problem before the real initialization of the object happens. E.g. it 85can deactivate an active object in order to prevent damage to the 86subsystem. 87 88When the real object is not yet tracked by debugobjects, debugobjects 89allocates a tracker object for the real object and sets the tracker 90object state to ODEBUG_STATE_INIT. It verifies that the object is not 91on the callers stack. If it is on the callers stack then a limited 92number of warnings including a full stack trace is printk'ed. The 93calling code must use debug_object_init_on_stack() and remove the 94object before leaving the function which allocated it. See next section. 95 96debug_object_init_on_stack 97------------------------------ 98 99This function is called whenever the initialization function of a real 100object which resides on the stack is called. 101 102When the real object is already tracked by debugobjects it is checked, 103whether the object can be initialized. Initializing is not allowed for 104active and destroyed objects. When debugobjects detects an error, then 105it calls the fixup_init function of the object type description 106structure if provided by the caller. The fixup function can correct the 107problem before the real initialization of the object happens. E.g. it 108can deactivate an active object in order to prevent damage to the 109subsystem. 110 111When the real object is not yet tracked by debugobjects debugobjects 112allocates a tracker object for the real object and sets the tracker 113object state to ODEBUG_STATE_INIT. It verifies that the object is on 114the callers stack. 115 116An object which is on the stack must be removed from the tracker by 117calling debug_object_free() before the function which allocates the 118object returns. Otherwise we keep track of stale objects. 119 120debug_object_activate 121----------------------- 122 123This function is called whenever the activation function of a real 124object is called. 125 126When the real object is already tracked by debugobjects it is checked, 127whether the object can be activated. Activating is not allowed for 128active and destroyed objects. When debugobjects detects an error, then 129it calls the fixup_activate function of the object type description 130structure if provided by the caller. The fixup function can correct the 131problem before the real activation of the object happens. E.g. it can 132deactivate an active object in order to prevent damage to the subsystem. 133 134When the real object is not yet tracked by debugobjects then the 135fixup_activate function is called if available. This is necessary to 136allow the legitimate activation of statically allocated and initialized 137objects. The fixup function checks whether the object is valid and calls 138the debug_objects_init() function to initialize the tracking of this 139object. 140 141When the activation is legitimate, then the state of the associated 142tracker object is set to ODEBUG_STATE_ACTIVE. 143 144debug_object_deactivate 145------------------------- 146 147This function is called whenever the deactivation function of a real 148object is called. 149 150When the real object is tracked by debugobjects it is checked, whether 151the object can be deactivated. Deactivating is not allowed for untracked 152or destroyed objects. 153 154When the deactivation is legitimate, then the state of the associated 155tracker object is set to ODEBUG_STATE_INACTIVE. 156 157debug_object_destroy 158---------------------- 159 160This function is called to mark an object destroyed. This is useful to 161prevent the usage of invalid objects, which are still available in 162memory: either statically allocated objects or objects which are freed 163later. 164 165When the real object is tracked by debugobjects it is checked, whether 166the object can be destroyed. Destruction is not allowed for active and 167destroyed objects. When debugobjects detects an error, then it calls the 168fixup_destroy function of the object type description structure if 169provided by the caller. The fixup function can correct the problem 170before the real destruction of the object happens. E.g. it can 171deactivate an active object in order to prevent damage to the subsystem. 172 173When the destruction is legitimate, then the state of the associated 174tracker object is set to ODEBUG_STATE_DESTROYED. 175 176debug_object_free 177------------------- 178 179This function is called before an object is freed. 180 181When the real object is tracked by debugobjects it is checked, whether 182the object can be freed. Free is not allowed for active objects. When 183debugobjects detects an error, then it calls the fixup_free function of 184the object type description structure if provided by the caller. The 185fixup function can correct the problem before the real free of the 186object happens. E.g. it can deactivate an active object in order to 187prevent damage to the subsystem. 188 189Note that debug_object_free removes the object from the tracker. Later 190usage of the object is detected by the other debug checks. 191 192debug_object_assert_init 193--------------------------- 194 195This function is called to assert that an object has been initialized. 196 197When the real object is not tracked by debugobjects, it calls 198fixup_assert_init of the object type description structure provided by 199the caller, with the hardcoded object state ODEBUG_NOT_AVAILABLE. The 200fixup function can correct the problem by calling debug_object_init 201and other specific initializing functions. 202 203When the real object is already tracked by debugobjects it is ignored. 204 205Fixup functions 206=============== 207 208Debug object type description structure 209--------------------------------------- 210 211.. kernel-doc:: include/linux/debugobjects.h 212 :internal: 213 214fixup_init 215----------- 216 217This function is called from the debug code whenever a problem in 218debug_object_init is detected. The function takes the address of the 219object and the state which is currently recorded in the tracker. 220 221Called from debug_object_init when the object state is: 222 223- ODEBUG_STATE_ACTIVE 224 225The function returns true when the fixup was successful, otherwise 226false. The return value is used to update the statistics. 227 228Note, that the function needs to call the debug_object_init() function 229again, after the damage has been repaired in order to keep the state 230consistent. 231 232fixup_activate 233--------------- 234 235This function is called from the debug code whenever a problem in 236debug_object_activate is detected. 237 238Called from debug_object_activate when the object state is: 239 240- ODEBUG_STATE_NOTAVAILABLE 241 242- ODEBUG_STATE_ACTIVE 243 244The function returns true when the fixup was successful, otherwise 245false. The return value is used to update the statistics. 246 247Note that the function needs to call the debug_object_activate() 248function again after the damage has been repaired in order to keep the 249state consistent. 250 251The activation of statically initialized objects is a special case. When 252debug_object_activate() has no tracked object for this object address 253then fixup_activate() is called with object state 254ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether 255this is a legitimate case of a statically initialized object or not. In 256case it is it calls debug_object_init() and debug_object_activate() 257to make the object known to the tracker and marked active. In this case 258the function should return false because this is not a real fixup. 259 260fixup_destroy 261-------------- 262 263This function is called from the debug code whenever a problem in 264debug_object_destroy is detected. 265 266Called from debug_object_destroy when the object state is: 267 268- ODEBUG_STATE_ACTIVE 269 270The function returns true when the fixup was successful, otherwise 271false. The return value is used to update the statistics. 272 273fixup_free 274----------- 275 276This function is called from the debug code whenever a problem in 277debug_object_free is detected. Further it can be called from the debug 278checks in kfree/vfree, when an active object is detected from the 279debug_check_no_obj_freed() sanity checks. 280 281Called from debug_object_free() or debug_check_no_obj_freed() when 282the object state is: 283 284- ODEBUG_STATE_ACTIVE 285 286The function returns true when the fixup was successful, otherwise 287false. The return value is used to update the statistics. 288 289fixup_assert_init 290------------------- 291 292This function is called from the debug code whenever a problem in 293debug_object_assert_init is detected. 294 295Called from debug_object_assert_init() with a hardcoded state 296ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug 297bucket. 298 299The function returns true when the fixup was successful, otherwise 300false. The return value is used to update the statistics. 301 302Note, this function should make sure debug_object_init() is called 303before returning. 304 305The handling of statically initialized objects is a special case. The 306fixup function should check if this is a legitimate case of a statically 307initialized object or not. In this case only debug_object_init() 308should be called to make the object known to the tracker. Then the 309function should return false because this is not a real fixup. 310 311Known Bugs And Assumptions 312========================== 313 314None (knock on wood). 315