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).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.