1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5<book id="debug-objects-guide"> 6 <bookinfo> 7 <title>Debug objects life time</title> 8 9 <authorgroup> 10 <author> 11 <firstname>Thomas</firstname> 12 <surname>Gleixner</surname> 13 <affiliation> 14 <address> 15 <email>tglx@linutronix.de</email> 16 </address> 17 </affiliation> 18 </author> 19 </authorgroup> 20 21 <copyright> 22 <year>2008</year> 23 <holder>Thomas Gleixner</holder> 24 </copyright> 25 26 <legalnotice> 27 <para> 28 This documentation is free software; you can redistribute 29 it and/or modify it under the terms of the GNU General Public 30 License version 2 as published by the Free Software Foundation. 31 </para> 32 33 <para> 34 This program is distributed in the hope that it will be 35 useful, but WITHOUT ANY WARRANTY; without even the implied 36 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 37 See the GNU General Public License for more details. 38 </para> 39 40 <para> 41 You should have received a copy of the GNU General Public 42 License along with this program; if not, write to the Free 43 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 44 MA 02111-1307 USA 45 </para> 46 47 <para> 48 For more details see the file COPYING in the source 49 distribution of Linux. 50 </para> 51 </legalnotice> 52 </bookinfo> 53 54<toc></toc> 55 56 <chapter id="intro"> 57 <title>Introduction</title> 58 <para> 59 debugobjects is a generic infrastructure to track the life time 60 of kernel objects and validate the operations on those. 61 </para> 62 <para> 63 debugobjects is useful to check for the following error patterns: 64 <itemizedlist> 65 <listitem><para>Activation of uninitialized objects</para></listitem> 66 <listitem><para>Initialization of active objects</para></listitem> 67 <listitem><para>Usage of freed/destroyed objects</para></listitem> 68 </itemizedlist> 69 </para> 70 <para> 71 debugobjects is not changing the data structure of the real 72 object so it can be compiled in with a minimal runtime impact 73 and enabled on demand with a kernel command line option. 74 </para> 75 </chapter> 76 77 <chapter id="howto"> 78 <title>Howto use debugobjects</title> 79 <para> 80 A kernel subsystem needs to provide a data structure which 81 describes the object type and add calls into the debug code at 82 appropriate places. The data structure to describe the object 83 type needs at minimum the name of the object type. Optional 84 functions can and should be provided to fixup detected problems 85 so the kernel can continue to work and the debug information can 86 be retrieved from a live system instead of hard core debugging 87 with serial consoles and stack trace transcripts from the 88 monitor. 89 </para> 90 <para> 91 The debug calls provided by debugobjects are: 92 <itemizedlist> 93 <listitem><para>debug_object_init</para></listitem> 94 <listitem><para>debug_object_init_on_stack</para></listitem> 95 <listitem><para>debug_object_activate</para></listitem> 96 <listitem><para>debug_object_deactivate</para></listitem> 97 <listitem><para>debug_object_destroy</para></listitem> 98 <listitem><para>debug_object_free</para></listitem> 99 <listitem><para>debug_object_assert_init</para></listitem> 100 </itemizedlist> 101 Each of these functions takes the address of the real object and 102 a pointer to the object type specific debug description 103 structure. 104 </para> 105 <para> 106 Each detected error is reported in the statistics and a limited 107 number of errors are printk'ed including a full stack trace. 108 </para> 109 <para> 110 The statistics are available via /sys/kernel/debug/debug_objects/stats. 111 They provide information about the number of warnings and the 112 number of successful fixups along with information about the 113 usage of the internal tracking objects and the state of the 114 internal tracking objects pool. 115 </para> 116 </chapter> 117 <chapter id="debugfunctions"> 118 <title>Debug functions</title> 119 <sect1 id="prototypes"> 120 <title>Debug object function reference</title> 121<!-- lib/debugobjects.c --> 122<refentry id="API-debug-object-init"> 123<refentryinfo> 124 <title>LINUX</title> 125 <productname>Kernel Hackers Manual</productname> 126 <date>July 2017</date> 127</refentryinfo> 128<refmeta> 129 <refentrytitle><phrase>debug_object_init</phrase></refentrytitle> 130 <manvolnum>9</manvolnum> 131 <refmiscinfo class="version">4.1.27</refmiscinfo> 132</refmeta> 133<refnamediv> 134 <refname>debug_object_init</refname> 135 <refpurpose> 136 debug checks when an object is initialized 137 </refpurpose> 138</refnamediv> 139<refsynopsisdiv> 140 <title>Synopsis</title> 141 <funcsynopsis><funcprototype> 142 <funcdef>void <function>debug_object_init </function></funcdef> 143 <paramdef>void * <parameter>addr</parameter></paramdef> 144 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 145 </funcprototype></funcsynopsis> 146</refsynopsisdiv> 147<refsect1> 148 <title>Arguments</title> 149 <variablelist> 150 <varlistentry> 151 <term><parameter>addr</parameter></term> 152 <listitem> 153 <para> 154 address of the object 155 </para> 156 </listitem> 157 </varlistentry> 158 <varlistentry> 159 <term><parameter>descr</parameter></term> 160 <listitem> 161 <para> 162 pointer to an object specific debug description structure 163 </para> 164 </listitem> 165 </varlistentry> 166 </variablelist> 167</refsect1> 168</refentry> 169 170<refentry id="API-debug-object-init-on-stack"> 171<refentryinfo> 172 <title>LINUX</title> 173 <productname>Kernel Hackers Manual</productname> 174 <date>July 2017</date> 175</refentryinfo> 176<refmeta> 177 <refentrytitle><phrase>debug_object_init_on_stack</phrase></refentrytitle> 178 <manvolnum>9</manvolnum> 179 <refmiscinfo class="version">4.1.27</refmiscinfo> 180</refmeta> 181<refnamediv> 182 <refname>debug_object_init_on_stack</refname> 183 <refpurpose> 184 debug checks when an object on stack is initialized 185 </refpurpose> 186</refnamediv> 187<refsynopsisdiv> 188 <title>Synopsis</title> 189 <funcsynopsis><funcprototype> 190 <funcdef>void <function>debug_object_init_on_stack </function></funcdef> 191 <paramdef>void * <parameter>addr</parameter></paramdef> 192 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 193 </funcprototype></funcsynopsis> 194</refsynopsisdiv> 195<refsect1> 196 <title>Arguments</title> 197 <variablelist> 198 <varlistentry> 199 <term><parameter>addr</parameter></term> 200 <listitem> 201 <para> 202 address of the object 203 </para> 204 </listitem> 205 </varlistentry> 206 <varlistentry> 207 <term><parameter>descr</parameter></term> 208 <listitem> 209 <para> 210 pointer to an object specific debug description structure 211 </para> 212 </listitem> 213 </varlistentry> 214 </variablelist> 215</refsect1> 216</refentry> 217 218<refentry id="API-debug-object-activate"> 219<refentryinfo> 220 <title>LINUX</title> 221 <productname>Kernel Hackers Manual</productname> 222 <date>July 2017</date> 223</refentryinfo> 224<refmeta> 225 <refentrytitle><phrase>debug_object_activate</phrase></refentrytitle> 226 <manvolnum>9</manvolnum> 227 <refmiscinfo class="version">4.1.27</refmiscinfo> 228</refmeta> 229<refnamediv> 230 <refname>debug_object_activate</refname> 231 <refpurpose> 232 debug checks when an object is activated 233 </refpurpose> 234</refnamediv> 235<refsynopsisdiv> 236 <title>Synopsis</title> 237 <funcsynopsis><funcprototype> 238 <funcdef>int <function>debug_object_activate </function></funcdef> 239 <paramdef>void * <parameter>addr</parameter></paramdef> 240 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 241 </funcprototype></funcsynopsis> 242</refsynopsisdiv> 243<refsect1> 244 <title>Arguments</title> 245 <variablelist> 246 <varlistentry> 247 <term><parameter>addr</parameter></term> 248 <listitem> 249 <para> 250 address of the object 251 </para> 252 </listitem> 253 </varlistentry> 254 <varlistentry> 255 <term><parameter>descr</parameter></term> 256 <listitem> 257 <para> 258 pointer to an object specific debug description structure 259 Returns 0 for success, -EINVAL for check failed. 260 </para> 261 </listitem> 262 </varlistentry> 263 </variablelist> 264</refsect1> 265</refentry> 266 267<refentry id="API-debug-object-deactivate"> 268<refentryinfo> 269 <title>LINUX</title> 270 <productname>Kernel Hackers Manual</productname> 271 <date>July 2017</date> 272</refentryinfo> 273<refmeta> 274 <refentrytitle><phrase>debug_object_deactivate</phrase></refentrytitle> 275 <manvolnum>9</manvolnum> 276 <refmiscinfo class="version">4.1.27</refmiscinfo> 277</refmeta> 278<refnamediv> 279 <refname>debug_object_deactivate</refname> 280 <refpurpose> 281 debug checks when an object is deactivated 282 </refpurpose> 283</refnamediv> 284<refsynopsisdiv> 285 <title>Synopsis</title> 286 <funcsynopsis><funcprototype> 287 <funcdef>void <function>debug_object_deactivate </function></funcdef> 288 <paramdef>void * <parameter>addr</parameter></paramdef> 289 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 290 </funcprototype></funcsynopsis> 291</refsynopsisdiv> 292<refsect1> 293 <title>Arguments</title> 294 <variablelist> 295 <varlistentry> 296 <term><parameter>addr</parameter></term> 297 <listitem> 298 <para> 299 address of the object 300 </para> 301 </listitem> 302 </varlistentry> 303 <varlistentry> 304 <term><parameter>descr</parameter></term> 305 <listitem> 306 <para> 307 pointer to an object specific debug description structure 308 </para> 309 </listitem> 310 </varlistentry> 311 </variablelist> 312</refsect1> 313</refentry> 314 315<refentry id="API-debug-object-destroy"> 316<refentryinfo> 317 <title>LINUX</title> 318 <productname>Kernel Hackers Manual</productname> 319 <date>July 2017</date> 320</refentryinfo> 321<refmeta> 322 <refentrytitle><phrase>debug_object_destroy</phrase></refentrytitle> 323 <manvolnum>9</manvolnum> 324 <refmiscinfo class="version">4.1.27</refmiscinfo> 325</refmeta> 326<refnamediv> 327 <refname>debug_object_destroy</refname> 328 <refpurpose> 329 debug checks when an object is destroyed 330 </refpurpose> 331</refnamediv> 332<refsynopsisdiv> 333 <title>Synopsis</title> 334 <funcsynopsis><funcprototype> 335 <funcdef>void <function>debug_object_destroy </function></funcdef> 336 <paramdef>void * <parameter>addr</parameter></paramdef> 337 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 338 </funcprototype></funcsynopsis> 339</refsynopsisdiv> 340<refsect1> 341 <title>Arguments</title> 342 <variablelist> 343 <varlistentry> 344 <term><parameter>addr</parameter></term> 345 <listitem> 346 <para> 347 address of the object 348 </para> 349 </listitem> 350 </varlistentry> 351 <varlistentry> 352 <term><parameter>descr</parameter></term> 353 <listitem> 354 <para> 355 pointer to an object specific debug description structure 356 </para> 357 </listitem> 358 </varlistentry> 359 </variablelist> 360</refsect1> 361</refentry> 362 363<refentry id="API-debug-object-free"> 364<refentryinfo> 365 <title>LINUX</title> 366 <productname>Kernel Hackers Manual</productname> 367 <date>July 2017</date> 368</refentryinfo> 369<refmeta> 370 <refentrytitle><phrase>debug_object_free</phrase></refentrytitle> 371 <manvolnum>9</manvolnum> 372 <refmiscinfo class="version">4.1.27</refmiscinfo> 373</refmeta> 374<refnamediv> 375 <refname>debug_object_free</refname> 376 <refpurpose> 377 debug checks when an object is freed 378 </refpurpose> 379</refnamediv> 380<refsynopsisdiv> 381 <title>Synopsis</title> 382 <funcsynopsis><funcprototype> 383 <funcdef>void <function>debug_object_free </function></funcdef> 384 <paramdef>void * <parameter>addr</parameter></paramdef> 385 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 386 </funcprototype></funcsynopsis> 387</refsynopsisdiv> 388<refsect1> 389 <title>Arguments</title> 390 <variablelist> 391 <varlistentry> 392 <term><parameter>addr</parameter></term> 393 <listitem> 394 <para> 395 address of the object 396 </para> 397 </listitem> 398 </varlistentry> 399 <varlistentry> 400 <term><parameter>descr</parameter></term> 401 <listitem> 402 <para> 403 pointer to an object specific debug description structure 404 </para> 405 </listitem> 406 </varlistentry> 407 </variablelist> 408</refsect1> 409</refentry> 410 411<refentry id="API-debug-object-assert-init"> 412<refentryinfo> 413 <title>LINUX</title> 414 <productname>Kernel Hackers Manual</productname> 415 <date>July 2017</date> 416</refentryinfo> 417<refmeta> 418 <refentrytitle><phrase>debug_object_assert_init</phrase></refentrytitle> 419 <manvolnum>9</manvolnum> 420 <refmiscinfo class="version">4.1.27</refmiscinfo> 421</refmeta> 422<refnamediv> 423 <refname>debug_object_assert_init</refname> 424 <refpurpose> 425 debug checks when object should be init-ed 426 </refpurpose> 427</refnamediv> 428<refsynopsisdiv> 429 <title>Synopsis</title> 430 <funcsynopsis><funcprototype> 431 <funcdef>void <function>debug_object_assert_init </function></funcdef> 432 <paramdef>void * <parameter>addr</parameter></paramdef> 433 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 434 </funcprototype></funcsynopsis> 435</refsynopsisdiv> 436<refsect1> 437 <title>Arguments</title> 438 <variablelist> 439 <varlistentry> 440 <term><parameter>addr</parameter></term> 441 <listitem> 442 <para> 443 address of the object 444 </para> 445 </listitem> 446 </varlistentry> 447 <varlistentry> 448 <term><parameter>descr</parameter></term> 449 <listitem> 450 <para> 451 pointer to an object specific debug description structure 452 </para> 453 </listitem> 454 </varlistentry> 455 </variablelist> 456</refsect1> 457</refentry> 458 459<refentry id="API-debug-object-active-state"> 460<refentryinfo> 461 <title>LINUX</title> 462 <productname>Kernel Hackers Manual</productname> 463 <date>July 2017</date> 464</refentryinfo> 465<refmeta> 466 <refentrytitle><phrase>debug_object_active_state</phrase></refentrytitle> 467 <manvolnum>9</manvolnum> 468 <refmiscinfo class="version">4.1.27</refmiscinfo> 469</refmeta> 470<refnamediv> 471 <refname>debug_object_active_state</refname> 472 <refpurpose> 473 debug checks object usage state machine 474 </refpurpose> 475</refnamediv> 476<refsynopsisdiv> 477 <title>Synopsis</title> 478 <funcsynopsis><funcprototype> 479 <funcdef>void <function>debug_object_active_state </function></funcdef> 480 <paramdef>void * <parameter>addr</parameter></paramdef> 481 <paramdef>struct debug_obj_descr * <parameter>descr</parameter></paramdef> 482 <paramdef>unsigned int <parameter>expect</parameter></paramdef> 483 <paramdef>unsigned int <parameter>next</parameter></paramdef> 484 </funcprototype></funcsynopsis> 485</refsynopsisdiv> 486<refsect1> 487 <title>Arguments</title> 488 <variablelist> 489 <varlistentry> 490 <term><parameter>addr</parameter></term> 491 <listitem> 492 <para> 493 address of the object 494 </para> 495 </listitem> 496 </varlistentry> 497 <varlistentry> 498 <term><parameter>descr</parameter></term> 499 <listitem> 500 <para> 501 pointer to an object specific debug description structure 502 </para> 503 </listitem> 504 </varlistentry> 505 <varlistentry> 506 <term><parameter>expect</parameter></term> 507 <listitem> 508 <para> 509 expected state 510 </para> 511 </listitem> 512 </varlistentry> 513 <varlistentry> 514 <term><parameter>next</parameter></term> 515 <listitem> 516 <para> 517 state to move to if expected state is found 518 </para> 519 </listitem> 520 </varlistentry> 521 </variablelist> 522</refsect1> 523</refentry> 524 525 </sect1> 526 <sect1 id="debug_object_init"> 527 <title>debug_object_init</title> 528 <para> 529 This function is called whenever the initialization function 530 of a real object is called. 531 </para> 532 <para> 533 When the real object is already tracked by debugobjects it is 534 checked, whether the object can be initialized. Initializing 535 is not allowed for active and destroyed objects. When 536 debugobjects detects an error, then it calls the fixup_init 537 function of the object type description structure if provided 538 by the caller. The fixup function can correct the problem 539 before the real initialization of the object happens. E.g. it 540 can deactivate an active object in order to prevent damage to 541 the subsystem. 542 </para> 543 <para> 544 When the real object is not yet tracked by debugobjects, 545 debugobjects allocates a tracker object for the real object 546 and sets the tracker object state to ODEBUG_STATE_INIT. It 547 verifies that the object is not on the callers stack. If it is 548 on the callers stack then a limited number of warnings 549 including a full stack trace is printk'ed. The calling code 550 must use debug_object_init_on_stack() and remove the object 551 before leaving the function which allocated it. See next 552 section. 553 </para> 554 </sect1> 555 556 <sect1 id="debug_object_init_on_stack"> 557 <title>debug_object_init_on_stack</title> 558 <para> 559 This function is called whenever the initialization function 560 of a real object which resides on the stack is called. 561 </para> 562 <para> 563 When the real object is already tracked by debugobjects it is 564 checked, whether the object can be initialized. Initializing 565 is not allowed for active and destroyed objects. When 566 debugobjects detects an error, then it calls the fixup_init 567 function of the object type description structure if provided 568 by the caller. The fixup function can correct the problem 569 before the real initialization of the object happens. E.g. it 570 can deactivate an active object in order to prevent damage to 571 the subsystem. 572 </para> 573 <para> 574 When the real object is not yet tracked by debugobjects 575 debugobjects allocates a tracker object for the real object 576 and sets the tracker object state to ODEBUG_STATE_INIT. It 577 verifies that the object is on the callers stack. 578 </para> 579 <para> 580 An object which is on the stack must be removed from the 581 tracker by calling debug_object_free() before the function 582 which allocates the object returns. Otherwise we keep track of 583 stale objects. 584 </para> 585 </sect1> 586 587 <sect1 id="debug_object_activate"> 588 <title>debug_object_activate</title> 589 <para> 590 This function is called whenever the activation function of a 591 real object is called. 592 </para> 593 <para> 594 When the real object is already tracked by debugobjects it is 595 checked, whether the object can be activated. Activating is 596 not allowed for active and destroyed objects. When 597 debugobjects detects an error, then it calls the 598 fixup_activate function of the object type description 599 structure if provided by the caller. The fixup function can 600 correct the problem before the real activation of the object 601 happens. E.g. it can deactivate an active object in order to 602 prevent damage to the subsystem. 603 </para> 604 <para> 605 When the real object is not yet tracked by debugobjects then 606 the fixup_activate function is called if available. This is 607 necessary to allow the legitimate activation of statically 608 allocated and initialized objects. The fixup function checks 609 whether the object is valid and calls the debug_objects_init() 610 function to initialize the tracking of this object. 611 </para> 612 <para> 613 When the activation is legitimate, then the state of the 614 associated tracker object is set to ODEBUG_STATE_ACTIVE. 615 </para> 616 </sect1> 617 618 <sect1 id="debug_object_deactivate"> 619 <title>debug_object_deactivate</title> 620 <para> 621 This function is called whenever the deactivation function of 622 a real object is called. 623 </para> 624 <para> 625 When the real object is tracked by debugobjects it is checked, 626 whether the object can be deactivated. Deactivating is not 627 allowed for untracked or destroyed objects. 628 </para> 629 <para> 630 When the deactivation is legitimate, then the state of the 631 associated tracker object is set to ODEBUG_STATE_INACTIVE. 632 </para> 633 </sect1> 634 635 <sect1 id="debug_object_destroy"> 636 <title>debug_object_destroy</title> 637 <para> 638 This function is called to mark an object destroyed. This is 639 useful to prevent the usage of invalid objects, which are 640 still available in memory: either statically allocated objects 641 or objects which are freed later. 642 </para> 643 <para> 644 When the real object is tracked by debugobjects it is checked, 645 whether the object can be destroyed. Destruction is not 646 allowed for active and destroyed objects. When debugobjects 647 detects an error, then it calls the fixup_destroy function of 648 the object type description structure if provided by the 649 caller. The fixup function can correct the problem before the 650 real destruction of the object happens. E.g. it can deactivate 651 an active object in order to prevent damage to the subsystem. 652 </para> 653 <para> 654 When the destruction is legitimate, then the state of the 655 associated tracker object is set to ODEBUG_STATE_DESTROYED. 656 </para> 657 </sect1> 658 659 <sect1 id="debug_object_free"> 660 <title>debug_object_free</title> 661 <para> 662 This function is called before an object is freed. 663 </para> 664 <para> 665 When the real object is tracked by debugobjects it is checked, 666 whether the object can be freed. Free is not allowed for 667 active objects. When debugobjects detects an error, then it 668 calls the fixup_free function of the object type description 669 structure if provided by the caller. The fixup function can 670 correct the problem before the real free of the object 671 happens. E.g. it can deactivate an active object in order to 672 prevent damage to the subsystem. 673 </para> 674 <para> 675 Note that debug_object_free removes the object from the 676 tracker. Later usage of the object is detected by the other 677 debug checks. 678 </para> 679 </sect1> 680 681 <sect1 id="debug_object_assert_init"> 682 <title>debug_object_assert_init</title> 683 <para> 684 This function is called to assert that an object has been 685 initialized. 686 </para> 687 <para> 688 When the real object is not tracked by debugobjects, it calls 689 fixup_assert_init of the object type description structure 690 provided by the caller, with the hardcoded object state 691 ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem 692 by calling debug_object_init and other specific initializing 693 functions. 694 </para> 695 <para> 696 When the real object is already tracked by debugobjects it is 697 ignored. 698 </para> 699 </sect1> 700 </chapter> 701 <chapter id="fixupfunctions"> 702 <title>Fixup functions</title> 703 <sect1 id="debug_obj_descr"> 704 <title>Debug object type description structure</title> 705<!-- include/linux/debugobjects.h --> 706<refentry id="API-struct-debug-obj"> 707<refentryinfo> 708 <title>LINUX</title> 709 <productname>Kernel Hackers Manual</productname> 710 <date>July 2017</date> 711</refentryinfo> 712<refmeta> 713 <refentrytitle><phrase>struct debug_obj</phrase></refentrytitle> 714 <manvolnum>9</manvolnum> 715 <refmiscinfo class="version">4.1.27</refmiscinfo> 716</refmeta> 717<refnamediv> 718 <refname>struct debug_obj</refname> 719 <refpurpose> 720 representaion of an tracked object 721 </refpurpose> 722</refnamediv> 723<refsynopsisdiv> 724 <title>Synopsis</title> 725 <programlisting> 726struct debug_obj { 727 struct hlist_node node; 728 enum debug_obj_state state; 729 unsigned int astate; 730 void * object; 731 struct debug_obj_descr * descr; 732}; </programlisting> 733</refsynopsisdiv> 734 <refsect1> 735 <title>Members</title> 736 <variablelist> 737 <varlistentry> <term>node</term> 738 <listitem><para> 739hlist node to link the object into the tracker list 740 </para></listitem> 741 </varlistentry> 742 <varlistentry> <term>state</term> 743 <listitem><para> 744tracked object state 745 </para></listitem> 746 </varlistentry> 747 <varlistentry> <term>astate</term> 748 <listitem><para> 749current active state 750 </para></listitem> 751 </varlistentry> 752 <varlistentry> <term>object</term> 753 <listitem><para> 754pointer to the real object 755 </para></listitem> 756 </varlistentry> 757 <varlistentry> <term>descr</term> 758 <listitem><para> 759pointer to an object type specific debug description structure 760 </para></listitem> 761 </varlistentry> 762 </variablelist> 763 </refsect1> 764</refentry> 765 766<refentry id="API-struct-debug-obj-descr"> 767<refentryinfo> 768 <title>LINUX</title> 769 <productname>Kernel Hackers Manual</productname> 770 <date>July 2017</date> 771</refentryinfo> 772<refmeta> 773 <refentrytitle><phrase>struct debug_obj_descr</phrase></refentrytitle> 774 <manvolnum>9</manvolnum> 775 <refmiscinfo class="version">4.1.27</refmiscinfo> 776</refmeta> 777<refnamediv> 778 <refname>struct debug_obj_descr</refname> 779 <refpurpose> 780 object type specific debug description structure 781 </refpurpose> 782</refnamediv> 783<refsynopsisdiv> 784 <title>Synopsis</title> 785 <programlisting> 786struct debug_obj_descr { 787 const char * name; 788 void *(* debug_hint) (void *addr); 789 int (* fixup_init) (void *addr, enum debug_obj_state state); 790 int (* fixup_activate) (void *addr, enum debug_obj_state state); 791 int (* fixup_destroy) (void *addr, enum debug_obj_state state); 792 int (* fixup_free) (void *addr, enum debug_obj_state state); 793 int (* fixup_assert_init) (void *addr, enum debug_obj_state state); 794}; </programlisting> 795</refsynopsisdiv> 796 <refsect1> 797 <title>Members</title> 798 <variablelist> 799 <varlistentry> <term>name</term> 800 <listitem><para> 801 name of the object typee 802 </para></listitem> 803 </varlistentry> 804 <varlistentry> <term>debug_hint</term> 805 <listitem><para> 806 function returning address, which have associated 807 kernel symbol, to allow identify the object 808 </para></listitem> 809 </varlistentry> 810 <varlistentry> <term>fixup_init</term> 811 <listitem><para> 812 fixup function, which is called when the init check 813 fails 814 </para></listitem> 815 </varlistentry> 816 <varlistentry> <term>fixup_activate</term> 817 <listitem><para> 818 fixup function, which is called when the activate check 819 fails 820 </para></listitem> 821 </varlistentry> 822 <varlistentry> <term>fixup_destroy</term> 823 <listitem><para> 824 fixup function, which is called when the destroy check 825 fails 826 </para></listitem> 827 </varlistentry> 828 <varlistentry> <term>fixup_free</term> 829 <listitem><para> 830 fixup function, which is called when the free check 831 fails 832 </para></listitem> 833 </varlistentry> 834 <varlistentry> <term>fixup_assert_init</term> 835 <listitem><para> 836 fixup function, which is called when the assert_init 837 check fails 838 </para></listitem> 839 </varlistentry> 840 </variablelist> 841 </refsect1> 842</refentry> 843 844 </sect1> 845 <sect1 id="fixup_init"> 846 <title>fixup_init</title> 847 <para> 848 This function is called from the debug code whenever a problem 849 in debug_object_init is detected. The function takes the 850 address of the object and the state which is currently 851 recorded in the tracker. 852 </para> 853 <para> 854 Called from debug_object_init when the object state is: 855 <itemizedlist> 856 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> 857 </itemizedlist> 858 </para> 859 <para> 860 The function returns 1 when the fixup was successful, 861 otherwise 0. The return value is used to update the 862 statistics. 863 </para> 864 <para> 865 Note, that the function needs to call the debug_object_init() 866 function again, after the damage has been repaired in order to 867 keep the state consistent. 868 </para> 869 </sect1> 870 871 <sect1 id="fixup_activate"> 872 <title>fixup_activate</title> 873 <para> 874 This function is called from the debug code whenever a problem 875 in debug_object_activate is detected. 876 </para> 877 <para> 878 Called from debug_object_activate when the object state is: 879 <itemizedlist> 880 <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem> 881 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> 882 </itemizedlist> 883 </para> 884 <para> 885 The function returns 1 when the fixup was successful, 886 otherwise 0. The return value is used to update the 887 statistics. 888 </para> 889 <para> 890 Note that the function needs to call the debug_object_activate() 891 function again after the damage has been repaired in order to 892 keep the state consistent. 893 </para> 894 <para> 895 The activation of statically initialized objects is a special 896 case. When debug_object_activate() has no tracked object for 897 this object address then fixup_activate() is called with 898 object state ODEBUG_STATE_NOTAVAILABLE. The fixup function 899 needs to check whether this is a legitimate case of a 900 statically initialized object or not. In case it is it calls 901 debug_object_init() and debug_object_activate() to make the 902 object known to the tracker and marked active. In this case 903 the function should return 0 because this is not a real fixup. 904 </para> 905 </sect1> 906 907 <sect1 id="fixup_destroy"> 908 <title>fixup_destroy</title> 909 <para> 910 This function is called from the debug code whenever a problem 911 in debug_object_destroy is detected. 912 </para> 913 <para> 914 Called from debug_object_destroy when the object state is: 915 <itemizedlist> 916 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> 917 </itemizedlist> 918 </para> 919 <para> 920 The function returns 1 when the fixup was successful, 921 otherwise 0. The return value is used to update the 922 statistics. 923 </para> 924 </sect1> 925 <sect1 id="fixup_free"> 926 <title>fixup_free</title> 927 <para> 928 This function is called from the debug code whenever a problem 929 in debug_object_free is detected. Further it can be called 930 from the debug checks in kfree/vfree, when an active object is 931 detected from the debug_check_no_obj_freed() sanity checks. 932 </para> 933 <para> 934 Called from debug_object_free() or debug_check_no_obj_freed() 935 when the object state is: 936 <itemizedlist> 937 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> 938 </itemizedlist> 939 </para> 940 <para> 941 The function returns 1 when the fixup was successful, 942 otherwise 0. The return value is used to update the 943 statistics. 944 </para> 945 </sect1> 946 <sect1 id="fixup_assert_init"> 947 <title>fixup_assert_init</title> 948 <para> 949 This function is called from the debug code whenever a problem 950 in debug_object_assert_init is detected. 951 </para> 952 <para> 953 Called from debug_object_assert_init() with a hardcoded state 954 ODEBUG_STATE_NOTAVAILABLE when the object is not found in the 955 debug bucket. 956 </para> 957 <para> 958 The function returns 1 when the fixup was successful, 959 otherwise 0. The return value is used to update the 960 statistics. 961 </para> 962 <para> 963 Note, this function should make sure debug_object_init() is 964 called before returning. 965 </para> 966 <para> 967 The handling of statically initialized objects is a special 968 case. The fixup function should check if this is a legitimate 969 case of a statically initialized object or not. In this case only 970 debug_object_init() should be called to make the object known to 971 the tracker. Then the function should return 0 because this is not 972 a real fixup. 973 </para> 974 </sect1> 975 </chapter> 976 <chapter id="bugs"> 977 <title>Known Bugs And Assumptions</title> 978 <para> 979 None (knock on wood). 980 </para> 981 </chapter> 982</book> 983