0001 ============================================
0002 The object-lifetime debugging infrastructure
0003 ============================================
0004
0005 :Author: Thomas Gleixner
0006
0007 Introduction
0008 ============
0009
0010 debugobjects is a generic infrastructure to track the life time of
0011 kernel objects and validate the operations on those.
0012
0013 debugobjects is useful to check for the following error patterns:
0014
0015 - Activation of uninitialized objects
0016
0017 - Initialization of active objects
0018
0019 - Usage of freed/destroyed objects
0020
0021 debugobjects is not changing the data structure of the real object so it
0022 can be compiled in with a minimal runtime impact and enabled on demand
0023 with a kernel command line option.
0024
0025 Howto use debugobjects
0026 ======================
0027
0028 A kernel subsystem needs to provide a data structure which describes the
0029 object type and add calls into the debug code at appropriate places. The
0030 data structure to describe the object type needs at minimum the name of
0031 the object type. Optional functions can and should be provided to fixup
0032 detected problems so the kernel can continue to work and the debug
0033 information can be retrieved from a live system instead of hard core
0034 debugging with serial consoles and stack trace transcripts from the
0035 monitor.
0036
0037 The debug calls provided by debugobjects are:
0038
0039 - debug_object_init
0040
0041 - debug_object_init_on_stack
0042
0043 - debug_object_activate
0044
0045 - debug_object_deactivate
0046
0047 - debug_object_destroy
0048
0049 - debug_object_free
0050
0051 - debug_object_assert_init
0052
0053 Each of these functions takes the address of the real object and a
0054 pointer to the object type specific debug description structure.
0055
0056 Each detected error is reported in the statistics and a limited number
0057 of errors are printk'ed including a full stack trace.
0058
0059 The statistics are available via /sys/kernel/debug/debug_objects/stats.
0060 They provide information about the number of warnings and the number of
0061 successful fixups along with information about the usage of the internal
0062 tracking objects and the state of the internal tracking objects pool.
0063
0064 Debug functions
0065 ===============
0066
0067 .. kernel-doc:: lib/debugobjects.c
0068 :functions: debug_object_init
0069
0070 This function is called whenever the initialization function of a real
0071 object is called.
0072
0073 When the real object is already tracked by debugobjects it is checked,
0074 whether the object can be initialized. Initializing is not allowed for
0075 active and destroyed objects. When debugobjects detects an error, then
0076 it calls the fixup_init function of the object type description
0077 structure if provided by the caller. The fixup function can correct the
0078 problem before the real initialization of the object happens. E.g. it
0079 can deactivate an active object in order to prevent damage to the
0080 subsystem.
0081
0082 When the real object is not yet tracked by debugobjects, debugobjects
0083 allocates a tracker object for the real object and sets the tracker
0084 object state to ODEBUG_STATE_INIT. It verifies that the object is not
0085 on the callers stack. If it is on the callers stack then a limited
0086 number of warnings including a full stack trace is printk'ed. The
0087 calling code must use debug_object_init_on_stack() and remove the
0088 object before leaving the function which allocated it. See next section.
0089
0090 .. kernel-doc:: lib/debugobjects.c
0091 :functions: debug_object_init_on_stack
0092
0093 This function is called whenever the initialization function of a real
0094 object which resides on the stack is called.
0095
0096 When the real object is already tracked by debugobjects it is checked,
0097 whether the object can be initialized. Initializing is not allowed for
0098 active and destroyed objects. When debugobjects detects an error, then
0099 it calls the fixup_init function of the object type description
0100 structure if provided by the caller. The fixup function can correct the
0101 problem before the real initialization of the object happens. E.g. it
0102 can deactivate an active object in order to prevent damage to the
0103 subsystem.
0104
0105 When the real object is not yet tracked by debugobjects debugobjects
0106 allocates a tracker object for the real object and sets the tracker
0107 object state to ODEBUG_STATE_INIT. It verifies that the object is on
0108 the callers stack.
0109
0110 An object which is on the stack must be removed from the tracker by
0111 calling debug_object_free() before the function which allocates the
0112 object returns. Otherwise we keep track of stale objects.
0113
0114 .. kernel-doc:: lib/debugobjects.c
0115 :functions: debug_object_activate
0116
0117 This function is called whenever the activation function of a real
0118 object is called.
0119
0120 When the real object is already tracked by debugobjects it is checked,
0121 whether the object can be activated. Activating is not allowed for
0122 active and destroyed objects. When debugobjects detects an error, then
0123 it calls the fixup_activate function of the object type description
0124 structure if provided by the caller. The fixup function can correct the
0125 problem before the real activation of the object happens. E.g. it can
0126 deactivate an active object in order to prevent damage to the subsystem.
0127
0128 When the real object is not yet tracked by debugobjects then the
0129 fixup_activate function is called if available. This is necessary to
0130 allow the legitimate activation of statically allocated and initialized
0131 objects. The fixup function checks whether the object is valid and calls
0132 the debug_objects_init() function to initialize the tracking of this
0133 object.
0134
0135 When the activation is legitimate, then the state of the associated
0136 tracker object is set to ODEBUG_STATE_ACTIVE.
0137
0138
0139 .. kernel-doc:: lib/debugobjects.c
0140 :functions: debug_object_deactivate
0141
0142 This function is called whenever the deactivation function of a real
0143 object is called.
0144
0145 When the real object is tracked by debugobjects it is checked, whether
0146 the object can be deactivated. Deactivating is not allowed for untracked
0147 or destroyed objects.
0148
0149 When the deactivation is legitimate, then the state of the associated
0150 tracker object is set to ODEBUG_STATE_INACTIVE.
0151
0152 .. kernel-doc:: lib/debugobjects.c
0153 :functions: debug_object_destroy
0154
0155 This function is called to mark an object destroyed. This is useful to
0156 prevent the usage of invalid objects, which are still available in
0157 memory: either statically allocated objects or objects which are freed
0158 later.
0159
0160 When the real object is tracked by debugobjects it is checked, whether
0161 the object can be destroyed. Destruction is not allowed for active and
0162 destroyed objects. When debugobjects detects an error, then it calls the
0163 fixup_destroy function of the object type description structure if
0164 provided by the caller. The fixup function can correct the problem
0165 before the real destruction of the object happens. E.g. it can
0166 deactivate an active object in order to prevent damage to the subsystem.
0167
0168 When the destruction is legitimate, then the state of the associated
0169 tracker object is set to ODEBUG_STATE_DESTROYED.
0170
0171 .. kernel-doc:: lib/debugobjects.c
0172 :functions: debug_object_free
0173
0174 This function is called before an object is freed.
0175
0176 When the real object is tracked by debugobjects it is checked, whether
0177 the object can be freed. Free is not allowed for active objects. When
0178 debugobjects detects an error, then it calls the fixup_free function of
0179 the object type description structure if provided by the caller. The
0180 fixup function can correct the problem before the real free of the
0181 object happens. E.g. it can deactivate an active object in order to
0182 prevent damage to the subsystem.
0183
0184 Note that debug_object_free removes the object from the tracker. Later
0185 usage of the object is detected by the other debug checks.
0186
0187
0188 .. kernel-doc:: lib/debugobjects.c
0189 :functions: debug_object_assert_init
0190
0191 This function is called to assert that an object has been initialized.
0192
0193 When the real object is not tracked by debugobjects, it calls
0194 fixup_assert_init of the object type description structure provided by
0195 the caller, with the hardcoded object state ODEBUG_NOT_AVAILABLE. The
0196 fixup function can correct the problem by calling debug_object_init
0197 and other specific initializing functions.
0198
0199 When the real object is already tracked by debugobjects it is ignored.
0200
0201 Fixup functions
0202 ===============
0203
0204 Debug object type description structure
0205 ---------------------------------------
0206
0207 .. kernel-doc:: include/linux/debugobjects.h
0208 :internal:
0209
0210 fixup_init
0211 -----------
0212
0213 This function is called from the debug code whenever a problem in
0214 debug_object_init is detected. The function takes the address of the
0215 object and the state which is currently recorded in the tracker.
0216
0217 Called from debug_object_init when the object state is:
0218
0219 - ODEBUG_STATE_ACTIVE
0220
0221 The function returns true when the fixup was successful, otherwise
0222 false. The return value is used to update the statistics.
0223
0224 Note, that the function needs to call the debug_object_init() function
0225 again, after the damage has been repaired in order to keep the state
0226 consistent.
0227
0228 fixup_activate
0229 ---------------
0230
0231 This function is called from the debug code whenever a problem in
0232 debug_object_activate is detected.
0233
0234 Called from debug_object_activate when the object state is:
0235
0236 - ODEBUG_STATE_NOTAVAILABLE
0237
0238 - ODEBUG_STATE_ACTIVE
0239
0240 The function returns true when the fixup was successful, otherwise
0241 false. The return value is used to update the statistics.
0242
0243 Note that the function needs to call the debug_object_activate()
0244 function again after the damage has been repaired in order to keep the
0245 state consistent.
0246
0247 The activation of statically initialized objects is a special case. When
0248 debug_object_activate() has no tracked object for this object address
0249 then fixup_activate() is called with object state
0250 ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether
0251 this is a legitimate case of a statically initialized object or not. In
0252 case it is it calls debug_object_init() and debug_object_activate()
0253 to make the object known to the tracker and marked active. In this case
0254 the function should return false because this is not a real fixup.
0255
0256 fixup_destroy
0257 --------------
0258
0259 This function is called from the debug code whenever a problem in
0260 debug_object_destroy is detected.
0261
0262 Called from debug_object_destroy when the object state is:
0263
0264 - ODEBUG_STATE_ACTIVE
0265
0266 The function returns true when the fixup was successful, otherwise
0267 false. The return value is used to update the statistics.
0268
0269 fixup_free
0270 -----------
0271
0272 This function is called from the debug code whenever a problem in
0273 debug_object_free is detected. Further it can be called from the debug
0274 checks in kfree/vfree, when an active object is detected from the
0275 debug_check_no_obj_freed() sanity checks.
0276
0277 Called from debug_object_free() or debug_check_no_obj_freed() when
0278 the object state is:
0279
0280 - ODEBUG_STATE_ACTIVE
0281
0282 The function returns true when the fixup was successful, otherwise
0283 false. The return value is used to update the statistics.
0284
0285 fixup_assert_init
0286 -------------------
0287
0288 This function is called from the debug code whenever a problem in
0289 debug_object_assert_init is detected.
0290
0291 Called from debug_object_assert_init() with a hardcoded state
0292 ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug
0293 bucket.
0294
0295 The function returns true when the fixup was successful, otherwise
0296 false. The return value is used to update the statistics.
0297
0298 Note, this function should make sure debug_object_init() is called
0299 before returning.
0300
0301 The handling of statically initialized objects is a special case. The
0302 fixup function should check if this is a legitimate case of a statically
0303 initialized object or not. In this case only debug_object_init()
0304 should be called to make the object known to the tracker. Then the
0305 function should return false because this is not a real fixup.
0306
0307 Known Bugs And Assumptions
0308 ==========================
0309
0310 None (knock on wood).
