callbacks.rst 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133
  1. ======================
  2. (Un)patching Callbacks
  3. ======================
  4. Livepatch (un)patch-callbacks provide a mechanism for livepatch modules
  5. to execute callback functions when a kernel object is (un)patched. They
  6. can be considered a **power feature** that **extends livepatching abilities**
  7. to include:
  8. - Safe updates to global data
  9. - "Patches" to init and probe functions
  10. - Patching otherwise unpatchable code (i.e. assembly)
  11. In most cases, (un)patch callbacks will need to be used in conjunction
  12. with memory barriers and kernel synchronization primitives, like
  13. mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues.
  14. 1. Motivation
  15. =============
  16. Callbacks differ from existing kernel facilities:
  17. - Module init/exit code doesn't run when disabling and re-enabling a
  18. patch.
  19. - A module notifier can't stop a to-be-patched module from loading.
  20. Callbacks are part of the klp_object structure and their implementation
  21. is specific to that klp_object. Other livepatch objects may or may not
  22. be patched, irrespective of the target klp_object's current state.
  23. 2. Callback types
  24. =================
  25. Callbacks can be registered for the following livepatch actions:
  26. * Pre-patch
  27. - before a klp_object is patched
  28. * Post-patch
  29. - after a klp_object has been patched and is active
  30. across all tasks
  31. * Pre-unpatch
  32. - before a klp_object is unpatched (ie, patched code is
  33. active), used to clean up post-patch callback
  34. resources
  35. * Post-unpatch
  36. - after a klp_object has been patched, all code has
  37. been restored and no tasks are running patched code,
  38. used to cleanup pre-patch callback resources
  39. 3. How it works
  40. ===============
  41. Each callback is optional, omitting one does not preclude specifying any
  42. other. However, the livepatching core executes the handlers in
  43. symmetry: pre-patch callbacks have a post-unpatch counterpart and
  44. post-patch callbacks have a pre-unpatch counterpart. An unpatch
  45. callback will only be executed if its corresponding patch callback was
  46. executed. Typical use cases pair a patch handler that acquires and
  47. configures resources with an unpatch handler tears down and releases
  48. those same resources.
  49. A callback is only executed if its host klp_object is loaded. For
  50. in-kernel vmlinux targets, this means that callbacks will always execute
  51. when a livepatch is enabled/disabled. For patch target kernel modules,
  52. callbacks will only execute if the target module is loaded. When a
  53. module target is (un)loaded, its callbacks will execute only if the
  54. livepatch module is enabled.
  55. The pre-patch callback, if specified, is expected to return a status
  56. code (0 for success, -ERRNO on error). An error status code indicates
  57. to the livepatching core that patching of the current klp_object is not
  58. safe and to stop the current patching request. (When no pre-patch
  59. callback is provided, the transition is assumed to be safe.) If a
  60. pre-patch callback returns failure, the kernel's module loader will:
  61. - Refuse to load a livepatch, if the livepatch is loaded after
  62. targeted code.
  63. or:
  64. - Refuse to load a module, if the livepatch was already successfully
  65. loaded.
  66. No post-patch, pre-unpatch, or post-unpatch callbacks will be executed
  67. for a given klp_object if the object failed to patch, due to a failed
  68. pre_patch callback or for any other reason.
  69. If a patch transition is reversed, no pre-unpatch handlers will be run
  70. (this follows the previously mentioned symmetry -- pre-unpatch callbacks
  71. will only occur if their corresponding post-patch callback executed).
  72. If the object did successfully patch, but the patch transition never
  73. started for some reason (e.g., if another object failed to patch),
  74. only the post-unpatch callback will be called.
  75. 4. Use cases
  76. ============
  77. Sample livepatch modules demonstrating the callback API can be found in
  78. samples/livepatch/ directory. These samples were modified for use in
  79. kselftests and can be found in the lib/livepatch directory.
  80. Global data update
  81. ------------------
  82. A pre-patch callback can be useful to update a global variable. For
  83. example, 75ff39ccc1bd ("tcp: make challenge acks less predictable")
  84. changes a global sysctl, as well as patches the tcp_send_challenge_ack()
  85. function.
  86. In this case, if we're being super paranoid, it might make sense to
  87. patch the data *after* patching is complete with a post-patch callback,
  88. so that tcp_send_challenge_ack() could first be changed to read
  89. sysctl_tcp_challenge_ack_limit with READ_ONCE.
  90. __init and probe function patches support
  91. -----------------------------------------
  92. Although __init and probe functions are not directly livepatch-able, it
  93. may be possible to implement similar updates via pre/post-patch
  94. callbacks.
  95. The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that
  96. virtnet_probe() initialized its driver's net_device features. A
  97. pre/post-patch callback could iterate over all such devices, making a
  98. similar change to their hw_features value. (Client functions of the
  99. value may need to be updated accordingly.)