docs: livepatch: convert docs to ReST and rename to *.rst

+1 -1

Documentation/ABI/testing/sysfs-kernel-livepatch

··· 45 45 use this feature without a clearance from a patch 46 46 distributor. Removal (rmmod) of patch modules is permanently 47 47 disabled when the feature is used. See 48 - Documentation/livepatch/livepatch.txt for more information. 48 + Documentation/livepatch/livepatch.rst for more information. 49 49 50 50 What: /sys/kernel/livepatch/<patch>/<object> 51 51 Date: Nov 2014

+8 -4

Documentation/livepatch/callbacks.txt Documentation/livepatch/callbacks.rst

··· 30 30 31 31 Callbacks can be registered for the following livepatch actions: 32 32 33 - * Pre-patch - before a klp_object is patched 33 + * Pre-patch 34 + - before a klp_object is patched 34 35 35 - * Post-patch - after a klp_object has been patched and is active 36 + * Post-patch 37 + - after a klp_object has been patched and is active 36 38 across all tasks 37 39 38 - * Pre-unpatch - before a klp_object is unpatched (ie, patched code is 40 + * Pre-unpatch 41 + - before a klp_object is unpatched (ie, patched code is 39 42 active), used to clean up post-patch callback 40 43 resources 41 44 42 - * Post-unpatch - after a klp_object has been patched, all code has 45 + * Post-unpatch 46 + - after a klp_object has been patched, all code has 43 47 been restored and no tasks are running patched code, 44 48 used to cleanup pre-patch callback resources 45 49

+7 -7

Documentation/livepatch/cumulative-patches.txt Documentation/livepatch/cumulative-patches.rst

··· 18 18 ----- 19 19 20 20 The atomic replace can be enabled by setting "replace" flag in struct klp_patch, 21 - for example: 21 + for example:: 22 22 23 23 static struct klp_patch patch = { 24 24 .mod = THIS_MODULE, ··· 49 49 50 50 The atomic replace allows: 51 51 52 - + Atomically revert some functions in a previous patch while 52 + - Atomically revert some functions in a previous patch while 53 53 upgrading other functions. 54 54 55 - + Remove eventual performance impact caused by core redirection 55 + - Remove eventual performance impact caused by core redirection 56 56 for functions that are no longer patched. 57 57 58 - + Decrease user confusion about dependencies between livepatches. 58 + - Decrease user confusion about dependencies between livepatches. 59 59 60 60 61 61 Limitations: 62 62 ------------ 63 63 64 - + Once the operation finishes, there is no straightforward way 64 + - Once the operation finishes, there is no straightforward way 65 65 to reverse it and restore the replaced patches atomically. 66 66 67 67 A good practice is to set .replace flag in any released livepatch. ··· 74 74 only when the transition was not forced. 75 75 76 76 77 - + Only the (un)patching callbacks from the _new_ cumulative livepatch are 77 + - Only the (un)patching callbacks from the _new_ cumulative livepatch are 78 78 executed. Any callbacks from the replaced patches are ignored. 79 79 80 80 In other words, the cumulative patch is responsible for doing any actions ··· 93 93 enabled patches were called. 94 94 95 95 96 - + There is no special handling of shadow variables. Livepatch authors 96 + - There is no special handling of shadow variables. Livepatch authors 97 97 must create their own rules how to pass them from one cumulative 98 98 patch to the other. Especially that they should not blindly remove 99 99 them in module_exit() functions.

+21

Documentation/livepatch/index.rst

··· 1 + :orphan: 2 + 3 + =================== 4 + Kernel Livepatching 5 + =================== 6 + 7 + .. toctree:: 8 + :maxdepth: 1 9 + 10 + livepatch 11 + callbacks 12 + cumulative-patches 13 + module-elf-format 14 + shadow-vars 15 + 16 + .. only:: subproject and html 17 + 18 + Indices 19 + ======= 20 + 21 + * :ref:`genindex`

+31 -29

Documentation/livepatch/livepatch.txt Documentation/livepatch/livepatch.rst

··· 4 4 5 5 This document outlines basic information about kernel livepatching. 6 6 7 - Table of Contents: 7 + .. Table of Contents: 8 8 9 - 1. Motivation 10 - 2. Kprobes, Ftrace, Livepatching 11 - 3. Consistency model 12 - 4. Livepatch module 13 - 4.1. New functions 14 - 4.2. Metadata 15 - 5. Livepatch life-cycle 16 - 5.1. Loading 17 - 5.2. Enabling 18 - 5.3. Replacing 19 - 5.4. Disabling 20 - 5.5. Removing 21 - 6. Sysfs 22 - 7. Limitations 9 + 1. Motivation 10 + 2. Kprobes, Ftrace, Livepatching 11 + 3. Consistency model 12 + 4. Livepatch module 13 + 4.1. New functions 14 + 4.2. Metadata 15 + 5. Livepatch life-cycle 16 + 5.1. Loading 17 + 5.2. Enabling 18 + 5.3. Replacing 19 + 5.4. Disabling 20 + 5.5. Removing 21 + 6. Sysfs 22 + 7. Limitations 23 23 24 24 25 25 1. Motivation ··· 40 40 to redirection of code execution; namely: kernel probes, function tracing, 41 41 and livepatching: 42 42 43 - + The kernel probes are the most generic. The code can be redirected by 43 + - The kernel probes are the most generic. The code can be redirected by 44 44 putting a breakpoint instruction instead of any instruction. 45 45 46 - + The function tracer calls the code from a predefined location that is 46 + - The function tracer calls the code from a predefined location that is 47 47 close to the function entry point. This location is generated by the 48 48 compiler using the '-pg' gcc option. 49 49 50 - + Livepatching typically needs to redirect the code at the very beginning 50 + - Livepatching typically needs to redirect the code at the very beginning 51 51 of the function entry before the function parameters or the stack 52 52 are in any way modified. 53 53 ··· 249 249 might want to access functions or data from the original source file 250 250 that may only be locally accessible. This can be solved by a special 251 251 relocation section in the generated livepatch module, see 252 - Documentation/livepatch/module-elf-format.txt for more details. 252 + Documentation/livepatch/module-elf-format.rst for more details. 253 253 254 254 255 255 4.2. Metadata ··· 258 258 The patch is described by several structures that split the information 259 259 into three levels: 260 260 261 - + struct klp_func is defined for each patched function. It describes 261 + - struct klp_func is defined for each patched function. It describes 262 262 the relation between the original and the new implementation of a 263 263 particular function. 264 264 ··· 275 275 only for a particular object ( vmlinux or a kernel module ). Note that 276 276 kallsyms allows for searching symbols according to the object name. 277 277 278 - + struct klp_object defines an array of patched functions (struct 278 + - struct klp_object defines an array of patched functions (struct 279 279 klp_func) in the same object. Where the object is either vmlinux 280 280 (NULL) or a module name. 281 281 ··· 285 285 only when they are available. 286 286 287 287 288 - + struct klp_patch defines an array of patched objects (struct 288 + - struct klp_patch defines an array of patched objects (struct 289 289 klp_object). 290 290 291 291 This structure handles all patched functions consistently and eventually, ··· 337 337 Second, livepatch enters into a transition state where tasks are converging 338 338 to the patched state. If an original function is patched for the first 339 339 time, a function specific struct klp_ops is created and an universal 340 - ftrace handler is registered[*]. This stage is indicated by a value of '1' 340 + ftrace handler is registered\ [#]_. This stage is indicated by a value of '1' 341 341 in /sys/kernel/livepatch/<name>/transition. For more information about 342 342 this process, see the "Consistency model" section. 343 343 344 344 Finally, once all tasks have been patched, the 'transition' value changes 345 345 to '0'. 346 346 347 - [*] Note that functions might be patched multiple times. The ftrace handler 347 + .. [#] 348 + 349 + Note that functions might be patched multiple times. The ftrace handler 348 350 is registered only once for a given function. Further patches just add 349 351 an entry to the list (see field `func_stack`) of the struct klp_ops. 350 352 The right implementation is selected by the ftrace handler, see ··· 370 368 freed when the related function is not modified by the new patch 371 369 and func_stack list becomes empty. 372 370 373 - See Documentation/livepatch/cumulative-patches.txt for more details. 371 + See Documentation/livepatch/cumulative-patches.rst for more details. 374 372 375 373 376 374 5.4. Disabling ··· 423 421 424 422 The current Livepatch implementation has several limitations: 425 423 426 - + Only functions that can be traced could be patched. 424 + - Only functions that can be traced could be patched. 427 425 428 426 Livepatch is based on the dynamic ftrace. In particular, functions 429 427 implementing ftrace or the livepatch ftrace handler could not be ··· 433 431 434 432 435 433 436 - + Livepatch works reliably only when the dynamic ftrace is located at 434 + - Livepatch works reliably only when the dynamic ftrace is located at 437 435 the very beginning of the function. 438 436 439 437 The function need to be redirected before the stack or the function ··· 447 445 this is handled on the ftrace level. 448 446 449 447 450 - + Kretprobes using the ftrace framework conflict with the patched 448 + - Kretprobes using the ftrace framework conflict with the patched 451 449 functions. 452 450 453 451 Both kretprobes and livepatches use a ftrace handler that modifies ··· 455 453 is rejected when the handler is already in use by the other. 456 454 457 455 458 - + Kprobes in the original function are ignored when the code is 456 + - Kprobes in the original function are ignored when the code is 459 457 redirected to the new implementation. 460 458 461 459 There is a work in progress to add warnings about this situation.

+114 -97

Documentation/livepatch/module-elf-format.txt Documentation/livepatch/module-elf-format.rst

··· 4 4 5 5 This document outlines the Elf format requirements that livepatch modules must follow. 6 6 7 - ----------------- 8 - Table of Contents 9 - ----------------- 10 - 0. Background and motivation 11 - 1. Livepatch modinfo field 12 - 2. Livepatch relocation sections 13 - 2.1 What are livepatch relocation sections? 14 - 2.2 Livepatch relocation section format 15 - 2.2.1 Required flags 16 - 2.2.2 Required name format 17 - 2.2.3 Example livepatch relocation section names 18 - 2.2.4 Example `readelf --sections` output 19 - 2.2.5 Example `readelf --relocs` output 20 - 3. Livepatch symbols 21 - 3.1 What are livepatch symbols? 22 - 3.2 A livepatch module's symbol table 23 - 3.3 Livepatch symbol format 24 - 3.3.1 Required flags 25 - 3.3.2 Required name format 26 - 3.3.3 Example livepatch symbol names 27 - 3.3.4 Example `readelf --symbols` output 28 - 4. Architecture-specific sections 29 - 5. Symbol table and Elf section access 7 + 8 + .. Table of Contents 9 + 10 + 0. Background and motivation 11 + 1. Livepatch modinfo field 12 + 2. Livepatch relocation sections 13 + 2.1 What are livepatch relocation sections? 14 + 2.2 Livepatch relocation section format 15 + 2.2.1 Required flags 16 + 2.2.2 Required name format 17 + 2.2.3 Example livepatch relocation section names 18 + 2.2.4 Example `readelf --sections` output 19 + 2.2.5 Example `readelf --relocs` output 20 + 3. Livepatch symbols 21 + 3.1 What are livepatch symbols? 22 + 3.2 A livepatch module's symbol table 23 + 3.3 Livepatch symbol format 24 + 3.3.1 Required flags 25 + 3.3.2 Required name format 26 + 3.3.3 Example livepatch symbol names 27 + 3.3.4 Example `readelf --symbols` output 28 + 4. Architecture-specific sections 29 + 5. Symbol table and Elf section access 30 30 31 31 ---------------------------- 32 32 0. Background and motivation ··· 89 89 90 90 Example modinfo output: 91 91 ----------------------- 92 - % modinfo livepatch-meminfo.ko 93 - filename: livepatch-meminfo.ko 94 - livepatch: Y 95 - license: GPL 96 - depends: 97 - vermagic: 4.3.0+ SMP mod_unload 92 + 93 + :: 94 + 95 + % modinfo livepatch-meminfo.ko 96 + filename: livepatch-meminfo.ko 97 + livepatch: Y 98 + license: GPL 99 + depends: 100 + vermagic: 4.3.0+ SMP mod_unload 98 101 99 102 -------------------------------- 100 103 2. Livepatch relocation sections ··· 145 142 146 143 2.2.2 Required name format 147 144 -------------------------- 148 - The name of a livepatch relocation section must conform to the following format: 145 + The name of a livepatch relocation section must conform to the following 146 + format:: 149 147 150 - .klp.rela.objname.section_name 151 - ^ ^^ ^ ^ ^ 152 - |________||_____| |__________| 153 - [A] [B] [C] 148 + .klp.rela.objname.section_name 149 + ^ ^^ ^ ^ ^ 150 + |________||_____| |__________| 151 + [A] [B] [C] 154 152 155 - [A] The relocation section name is prefixed with the string ".klp.rela." 156 - [B] The name of the object (i.e. "vmlinux" or name of module) to 157 - which the relocation section belongs follows immediately after the prefix. 158 - [C] The actual name of the section to which this relocation section applies. 153 + [A] The relocation section name is prefixed with the string ".klp.rela." 154 + [B] The name of the object (i.e. "vmlinux" or name of module) to 155 + which the relocation section belongs follows immediately after the prefix. 156 + [C] The actual name of the section to which this relocation section applies. 159 157 160 158 2.2.3 Example livepatch relocation section names: 161 159 ------------------------------------------------- ··· 166 162 2.2.4 Example `readelf --sections` output for a patch 167 163 module that patches vmlinux and modules 9p, btrfs, ext4: 168 164 -------------------------------------------------------- 165 + 166 + :: 167 + 169 168 Section Headers: 170 169 [Nr] Name Type Address Off Size ES Flg Lk Inf Al 171 170 [ snip ] ··· 182 175 [ snip ] ^ ^ 183 176 | | 184 177 [*] [*] 185 - [*] Livepatch relocation sections are SHT_RELA sections but with a few special 186 - characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will 187 - not be discarded when the module is loaded into memory, as well as with the 188 - SHF_RELA_LIVEPATCH flag ("o" - for OS-specific). 178 + [*] Livepatch relocation sections are SHT_RELA sections but with a few special 179 + characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will 180 + not be discarded when the module is loaded into memory, as well as with the 181 + SHF_RELA_LIVEPATCH flag ("o" - for OS-specific). 189 182 190 183 2.2.5 Example `readelf --relocs` output for a patch module: 191 184 ----------------------------------------------------------- 192 - Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: 193 - Offset Info Type Symbol's Value Symbol's Name + Addend 194 - 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 195 - 0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0 196 - 0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4 197 - 000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4 198 - [ snip ] ^ 199 - | 185 + 186 + :: 187 + 188 + Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: 189 + Offset Info Type Symbol's Value Symbol's Name + Addend 190 + 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 191 + 0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0 192 + 0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4 193 + 000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4 194 + [ snip ] ^ 195 + | 200 196 [*] 201 - [*] Every symbol referenced by a relocation is a livepatch symbol. 197 + [*] Every symbol referenced by a relocation is a livepatch symbol. 202 198 203 199 -------------------- 204 200 3. Livepatch symbols ··· 241 231 and the original symbol indices (and thus the symtab ordering) must be 242 232 preserved in order for apply_relocate_add() to find the right symbol. 243 233 244 - For example, take this particular rela from a livepatch module: 245 - Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: 246 - Offset Info Type Symbol's Value Symbol's Name + Addend 247 - 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 234 + For example, take this particular rela from a livepatch module::: 248 235 249 - This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded 250 - in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the 251 - symbol index 94. 252 - And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol: 253 - [ snip ] 254 - 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0 255 - [ snip ] 236 + Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: 237 + Offset Info Type Symbol's Value Symbol's Name + Addend 238 + 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 239 + 240 + This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded 241 + in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the 242 + symbol index 94. 243 + And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol: 244 + [ snip ] 245 + 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0 246 + [ snip ] 256 247 257 248 --------------------------- 258 249 3.3 Livepatch symbol format ··· 267 256 268 257 3.3.2 Required name format 269 258 -------------------------- 270 - Livepatch symbol names must conform to the following format: 259 + Livepatch symbol names must conform to the following format:: 271 260 272 - .klp.sym.objname.symbol_name,sympos 273 - ^ ^^ ^ ^ ^ ^ 274 - |_______||_____| |_________| | 275 - [A] [B] [C] [D] 261 + .klp.sym.objname.symbol_name,sympos 262 + ^ ^^ ^ ^ ^ ^ 263 + |_______||_____| |_________| | 264 + [A] [B] [C] [D] 276 265 277 - [A] The symbol name is prefixed with the string ".klp.sym." 278 - [B] The name of the object (i.e. "vmlinux" or name of module) to 279 - which the symbol belongs follows immediately after the prefix. 280 - [C] The actual name of the symbol. 281 - [D] The position of the symbol in the object (as according to kallsyms) 282 - This is used to differentiate duplicate symbols within the same 283 - object. The symbol position is expressed numerically (0, 1, 2...). 284 - The symbol position of a unique symbol is 0. 266 + [A] The symbol name is prefixed with the string ".klp.sym." 267 + [B] The name of the object (i.e. "vmlinux" or name of module) to 268 + which the symbol belongs follows immediately after the prefix. 269 + [C] The actual name of the symbol. 270 + [D] The position of the symbol in the object (as according to kallsyms) 271 + This is used to differentiate duplicate symbols within the same 272 + object. The symbol position is expressed numerically (0, 1, 2...). 273 + The symbol position of a unique symbol is 0. 285 274 286 275 3.3.3 Example livepatch symbol names: 287 276 ------------------------------------- 288 - .klp.sym.vmlinux.snprintf,0 289 - .klp.sym.vmlinux.printk,0 290 - .klp.sym.btrfs.btrfs_ktype,0 277 + 278 + :: 279 + 280 + .klp.sym.vmlinux.snprintf,0 281 + .klp.sym.vmlinux.printk,0 282 + .klp.sym.btrfs.btrfs_ktype,0 291 283 292 284 3.3.4 Example `readelf --symbols` output for a patch module: 293 285 ------------------------------------------------------------ 294 - Symbol table '.symtab' contains 127 entries: 295 - Num: Value Size Type Bind Vis Ndx Name 296 - [ snip ] 297 - 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0 298 - 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0 299 - 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0 300 - 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0 301 - [ snip ] ^ 302 - | 303 - [*] 304 - [*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20). 305 - "OS" means OS-specific. 286 + 287 + :: 288 + 289 + Symbol table '.symtab' contains 127 entries: 290 + Num: Value Size Type Bind Vis Ndx Name 291 + [ snip ] 292 + 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0 293 + 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0 294 + 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0 295 + 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0 296 + [ snip ] ^ 297 + | 298 + [*] 299 + [*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20). 300 + "OS" means OS-specific. 306 301 307 302 --------------------------------- 308 303 4. Architecture-specific sections ··· 330 313 symbol table, and relocation section indices, Elf information is preserved for 331 314 livepatch modules and is made accessible by the module loader through 332 315 module->klp_info, which is a klp_modinfo struct. When a livepatch module loads, 333 - this struct is filled in by the module loader. Its fields are documented below: 316 + this struct is filled in by the module loader. Its fields are documented below:: 334 317 335 - struct klp_modinfo { 336 - Elf_Ehdr hdr; /* Elf header */ 337 - Elf_Shdr *sechdrs; /* Section header table */ 338 - char *secstrings; /* String table for the section headers */ 339 - unsigned int symndx; /* The symbol table section index */ 340 - }; 318 + struct klp_modinfo { 319 + Elf_Ehdr hdr; /* Elf header */ 320 + Elf_Shdr *sechdrs; /* Section header table */ 321 + char *secstrings; /* String table for the section headers */ 322 + unsigned int symndx; /* The symbol table section index */ 323 + };

+41 -24

Documentation/livepatch/shadow-vars.txt Documentation/livepatch/shadow-vars.rst

··· 27 27 stored and retrieved through a <obj, id> pair. 28 28 29 29 * The klp_shadow variable data structure encapsulates both tracking 30 - meta-data and shadow-data: 30 + meta-data and shadow-data: 31 + 31 32 - meta-data 33 + 32 34 - obj - pointer to parent object 33 35 - id - data identifier 36 + 34 37 - data[] - storage for shadow data 35 38 36 39 It is important to note that the klp_shadow_alloc() and ··· 50 47 51 48 * klp_shadow_alloc() - allocate and add a new shadow variable 52 49 - search hashtable for <obj, id> pair 50 + 53 51 - if exists 52 + 54 53 - WARN and return NULL 54 + 55 55 - if <obj, id> doesn't already exist 56 + 56 57 - allocate a new shadow variable 57 58 - initialize the variable using a custom constructor and data when provided 58 59 - add <obj, id> to the global hashtable 59 60 60 61 * klp_shadow_get_or_alloc() - get existing or alloc a new shadow variable 61 62 - search hashtable for <obj, id> pair 63 + 62 64 - if exists 65 + 63 66 - return existing shadow variable 67 + 64 68 - if <obj, id> doesn't already exist 69 + 65 70 - allocate a new shadow variable 66 71 - initialize the variable using a custom constructor and data when provided 67 72 - add <obj, id> pair to the global hashtable 68 73 69 74 * klp_shadow_free() - detach and free a <obj, id> shadow variable 70 75 - find and remove a <obj, id> reference from global hashtable 76 + 71 77 - if found 78 + 72 79 - call destructor function if defined 73 80 - free shadow variable 74 81 75 82 * klp_shadow_free_all() - detach and free all <*, id> shadow variables 76 83 - find and remove any <*, id> references from global hashtable 84 + 77 85 - if found 86 + 78 87 - call destructor function if defined 79 88 - free shadow variable 80 89 ··· 117 102 for this <obj, id> pair.) 118 103 119 104 For commit 1d147bfa6429, when a parent sta_info structure is allocated, 120 - allocate a shadow copy of the ps_lock pointer, then initialize it: 105 + allocate a shadow copy of the ps_lock pointer, then initialize it:: 121 106 122 - #define PS_LOCK 1 123 - struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata, 124 - const u8 *addr, gfp_t gfp) 125 - { 107 + #define PS_LOCK 1 108 + struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata, 109 + const u8 *addr, gfp_t gfp) 110 + { 126 111 struct sta_info *sta; 127 112 spinlock_t *ps_lock; 128 113 ··· 138 123 ... 139 124 140 125 When requiring a ps_lock, query the shadow variable API to retrieve one 141 - for a specific struct sta_info: 126 + for a specific struct sta_info::: 142 127 143 - void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) 144 - { 128 + void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) 129 + { 145 130 spinlock_t *ps_lock; 146 131 147 132 /* sync with ieee80211_tx_h_unicast_ps_buf */ ··· 151 136 ... 152 137 153 138 When the parent sta_info structure is freed, first free the shadow 154 - variable: 139 + variable:: 155 140 156 - void sta_info_free(struct ieee80211_local *local, struct sta_info *sta) 157 - { 141 + void sta_info_free(struct ieee80211_local *local, struct sta_info *sta) 142 + { 158 143 klp_shadow_free(sta, PS_LOCK, NULL); 159 144 kfree(sta); 160 145 ... ··· 170 155 shadow variables to parents already in-flight. 171 156 172 157 For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is 173 - inside ieee80211_sta_ps_deliver_wakeup(): 158 + inside ieee80211_sta_ps_deliver_wakeup():: 174 159 175 - int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data) 176 - { 160 + int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data) 161 + { 177 162 spinlock_t *lock = shadow_data; 178 163 179 164 spin_lock_init(lock); 180 165 return 0; 181 - } 166 + } 182 167 183 - #define PS_LOCK 1 184 - void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) 185 - { 168 + #define PS_LOCK 1 169 + void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) 170 + { 186 171 spinlock_t *ps_lock; 187 172 188 173 /* sync with ieee80211_tx_h_unicast_ps_buf */ ··· 215 200 ============= 216 201 217 202 * https://github.com/dynup/kpatch 218 - The livepatch implementation is based on the kpatch version of shadow 219 - variables. 203 + 204 + The livepatch implementation is based on the kpatch version of shadow 205 + variables. 220 206 221 207 * http://files.mkgnu.net/files/dynamos/doc/papers/dynamos_eurosys_07.pdf 222 - Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity 223 - Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented 224 - a datatype update technique called "shadow data structures". 208 + 209 + Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity 210 + Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented 211 + a datatype update technique called "shadow data structures".

+1 -1

tools/objtool/Documentation/stack-validation.txt

··· 111 111 be detectable). Objtool makes that possible. 112 112 113 113 For more details, see the livepatch documentation in the Linux kernel 114 - source tree at Documentation/livepatch/livepatch.txt. 114 + source tree at Documentation/livepatch/livepatch.rst. 115 115 116 116 Rules 117 117 -----