Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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 | |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 67 | .. kernel-doc:: lib/debugobjects.c |
Jonathan Corbet | 8da3dc5 | 2016-11-18 17:17:11 -0700 | [diff] [blame] | 68 | :functions: debug_object_init |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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 | |
Jonathan Corbet | 8da3dc5 | 2016-11-18 17:17:11 -0700 | [diff] [blame] | 90 | .. kernel-doc:: lib/debugobjects.c |
| 91 | :functions: debug_object_init_on_stack |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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 | |
Jonathan Corbet | 8da3dc5 | 2016-11-18 17:17:11 -0700 | [diff] [blame] | 114 | .. kernel-doc:: lib/debugobjects.c |
| 115 | :functions: debug_object_activate |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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 | |
Jonathan Corbet | 8da3dc5 | 2016-11-18 17:17:11 -0700 | [diff] [blame] | 138 | |
| 139 | .. kernel-doc:: lib/debugobjects.c |
| 140 | :functions: debug_object_deactivate |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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 | |
Jonathan Corbet | 8da3dc5 | 2016-11-18 17:17:11 -0700 | [diff] [blame] | 152 | .. kernel-doc:: lib/debugobjects.c |
| 153 | :functions: debug_object_destroy |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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 | |
Jonathan Corbet | 8da3dc5 | 2016-11-18 17:17:11 -0700 | [diff] [blame] | 171 | .. kernel-doc:: lib/debugobjects.c |
| 172 | :functions: debug_object_free |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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 | |
Jonathan Corbet | 8da3dc5 | 2016-11-18 17:17:11 -0700 | [diff] [blame] | 187 | |
| 188 | .. kernel-doc:: lib/debugobjects.c |
| 189 | :functions: debug_object_assert_init |
Jonathan Corbet | 93dc3a1 | 2016-11-18 17:06:13 -0700 | [diff] [blame] | 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). |