311 lines · plain
1============================================2The object-lifetime debugging infrastructure3============================================4 5:Author: Thomas Gleixner6 7Introduction8============9 10debugobjects is a generic infrastructure to track the life time of11kernel objects and validate the operations on those.12 13debugobjects is useful to check for the following error patterns:14 15- Activation of uninitialized objects16 17- Initialization of active objects18 19- Usage of freed/destroyed objects20 21debugobjects is not changing the data structure of the real object so it22can be compiled in with a minimal runtime impact and enabled on demand23with a kernel command line option.24 25Howto use debugobjects26======================27 28A kernel subsystem needs to provide a data structure which describes the29object type and add calls into the debug code at appropriate places. The30data structure to describe the object type needs at minimum the name of31the object type. Optional functions can and should be provided to fixup32detected problems so the kernel can continue to work and the debug33information can be retrieved from a live system instead of hard core34debugging with serial consoles and stack trace transcripts from the35monitor.36 37The debug calls provided by debugobjects are:38 39- debug_object_init40 41- debug_object_init_on_stack42 43- debug_object_activate44 45- debug_object_deactivate46 47- debug_object_destroy48 49- debug_object_free50 51- debug_object_assert_init52 53Each of these functions takes the address of the real object and a54pointer to the object type specific debug description structure.55 56Each detected error is reported in the statistics and a limited number57of 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 of61successful fixups along with information about the usage of the internal62tracking objects and the state of the internal tracking objects pool.63 64Debug functions65===============66 67.. kernel-doc:: lib/debugobjects.c68 :functions: debug_object_init69 70This function is called whenever the initialization function of a real71object 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 for75active and destroyed objects. When debugobjects detects an error, then76it calls the fixup_init function of the object type description77structure if provided by the caller. The fixup function can correct the78problem before the real initialization of the object happens. E.g. it79can deactivate an active object in order to prevent damage to the80subsystem.81 82When the real object is not yet tracked by debugobjects, debugobjects83allocates a tracker object for the real object and sets the tracker84object state to ODEBUG_STATE_INIT. It verifies that the object is not85on the callers stack. If it is on the callers stack then a limited86number of warnings including a full stack trace is printk'ed. The87calling code must use debug_object_init_on_stack() and remove the88object before leaving the function which allocated it. See next section.89 90.. kernel-doc:: lib/debugobjects.c91 :functions: debug_object_init_on_stack92 93This function is called whenever the initialization function of a real94object 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 for98active and destroyed objects. When debugobjects detects an error, then99it calls the fixup_init function of the object type description100structure if provided by the caller. The fixup function can correct the101problem before the real initialization of the object happens. E.g. it102can deactivate an active object in order to prevent damage to the103subsystem.104 105When the real object is not yet tracked by debugobjects debugobjects106allocates a tracker object for the real object and sets the tracker107object state to ODEBUG_STATE_INIT. It verifies that the object is on108the callers stack.109 110An object which is on the stack must be removed from the tracker by111calling debug_object_free() before the function which allocates the112object returns. Otherwise we keep track of stale objects.113 114.. kernel-doc:: lib/debugobjects.c115 :functions: debug_object_activate116 117This function is called whenever the activation function of a real118object 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 for122active and destroyed objects. When debugobjects detects an error, then123it calls the fixup_activate function of the object type description124structure if provided by the caller. The fixup function can correct the125problem before the real activation of the object happens. E.g. it can126deactivate an active object in order to prevent damage to the subsystem.127 128When the real object is not yet tracked by debugobjects then the129fixup_activate function is called if available. This is necessary to130allow the legitimate activation of statically allocated and initialized131objects. The fixup function checks whether the object is valid and calls132the debug_objects_init() function to initialize the tracking of this133object.134 135When the activation is legitimate, then the state of the associated136tracker object is set to ODEBUG_STATE_ACTIVE.137 138 139.. kernel-doc:: lib/debugobjects.c140 :functions: debug_object_deactivate141 142This function is called whenever the deactivation function of a real143object is called.144 145When the real object is tracked by debugobjects it is checked, whether146the object can be deactivated. Deactivating is not allowed for untracked147or destroyed objects.148 149When the deactivation is legitimate, then the state of the associated150tracker object is set to ODEBUG_STATE_INACTIVE.151 152.. kernel-doc:: lib/debugobjects.c153 :functions: debug_object_destroy154 155This function is called to mark an object destroyed. This is useful to156prevent the usage of invalid objects, which are still available in157memory: either statically allocated objects or objects which are freed158later.159 160When the real object is tracked by debugobjects it is checked, whether161the object can be destroyed. Destruction is not allowed for active and162destroyed objects. When debugobjects detects an error, then it calls the163fixup_destroy function of the object type description structure if164provided by the caller. The fixup function can correct the problem165before the real destruction of the object happens. E.g. it can166deactivate an active object in order to prevent damage to the subsystem.167 168When the destruction is legitimate, then the state of the associated169tracker object is set to ODEBUG_STATE_DESTROYED.170 171.. kernel-doc:: lib/debugobjects.c172 :functions: debug_object_free173 174This function is called before an object is freed.175 176When the real object is tracked by debugobjects it is checked, whether177the object can be freed. Free is not allowed for active objects. When178debugobjects detects an error, then it calls the fixup_free function of179the object type description structure if provided by the caller. The180fixup function can correct the problem before the real free of the181object happens. E.g. it can deactivate an active object in order to182prevent damage to the subsystem.183 184Note that debug_object_free removes the object from the tracker. Later185usage of the object is detected by the other debug checks.186 187 188.. kernel-doc:: lib/debugobjects.c189 :functions: debug_object_assert_init190 191This function is called to assert that an object has been initialized.192 193When the real object is not tracked by debugobjects, it calls194fixup_assert_init of the object type description structure provided by195the caller, with the hardcoded object state ODEBUG_NOT_AVAILABLE. The196fixup function can correct the problem by calling debug_object_init197and other specific initializing functions.198 199When the real object is already tracked by debugobjects it is ignored.200 201Fixup functions202===============203 204Debug object type description structure205---------------------------------------206 207.. kernel-doc:: include/linux/debugobjects.h208 :internal:209 210fixup_init211-----------212 213This function is called from the debug code whenever a problem in214debug_object_init is detected. The function takes the address of the215object 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_ACTIVE220 221The function returns true when the fixup was successful, otherwise222false. The return value is used to update the statistics.223 224Note, that the function needs to call the debug_object_init() function225again, after the damage has been repaired in order to keep the state226consistent.227 228fixup_activate229---------------230 231This function is called from the debug code whenever a problem in232debug_object_activate is detected.233 234Called from debug_object_activate when the object state is:235 236- ODEBUG_STATE_NOTAVAILABLE237 238- ODEBUG_STATE_ACTIVE239 240The function returns true when the fixup was successful, otherwise241false. 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 the245state consistent.246 247The activation of statically initialized objects is a special case. When248debug_object_activate() has no tracked object for this object address249then fixup_activate() is called with object state250ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether251this is a legitimate case of a statically initialized object or not. In252case it is it calls debug_object_init() and debug_object_activate()253to make the object known to the tracker and marked active. In this case254the function should return false because this is not a real fixup.255 256fixup_destroy257--------------258 259This function is called from the debug code whenever a problem in260debug_object_destroy is detected.261 262Called from debug_object_destroy when the object state is:263 264- ODEBUG_STATE_ACTIVE265 266The function returns true when the fixup was successful, otherwise267false. The return value is used to update the statistics.268 269fixup_free270-----------271 272This function is called from the debug code whenever a problem in273debug_object_free is detected. Further it can be called from the debug274checks in kfree/vfree, when an active object is detected from the275debug_check_no_obj_freed() sanity checks.276 277Called from debug_object_free() or debug_check_no_obj_freed() when278the object state is:279 280- ODEBUG_STATE_ACTIVE281 282The function returns true when the fixup was successful, otherwise283false. The return value is used to update the statistics.284 285fixup_assert_init286-------------------287 288This function is called from the debug code whenever a problem in289debug_object_assert_init is detected.290 291Called from debug_object_assert_init() with a hardcoded state292ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug293bucket.294 295The function returns true when the fixup was successful, otherwise296false. The return value is used to update the statistics.297 298Note, this function should make sure debug_object_init() is called299before returning.300 301The handling of statically initialized objects is a special case. The302fixup function should check if this is a legitimate case of a statically303initialized object or not. In this case only debug_object_init()304should be called to make the object known to the tracker. Then the305function should return false because this is not a real fixup.306 307Known Bugs And Assumptions308==========================309 310None (knock on wood).311