Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

Documentation/kbuild: Add new gendwarfksyms kABI rules

Document the "byte_size" and "type_string" kABI stability rules.

Signed-off-by: Sami Tolvanen <samitolvanen@google.com>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>

authored by

Sami Tolvanen and committed by
Masahiro Yamada
cf9d6926 881bf900

+92 -5
+92 -5
Documentation/kbuild/gendwarfksyms.rst
··· 125 125 qualified name of the DWARF Debugging Information Entry (DIE). 126 126 - `value`: Provides rule-specific data. 127 127 128 - The following helper macro, for example, can be used to specify rules 128 + The following helper macros, for example, can be used to specify rules 129 129 in the source code:: 130 130 131 - #define __KABI_RULE(hint, target, value) \ 132 - static const char __PASTE(__gendwarfksyms_rule_, \ 131 + #define ___KABI_RULE(hint, target, value) \ 132 + static const char __PASTE(__gendwarfksyms_rule_, \ 133 133 __COUNTER__)[] __used __aligned(1) \ 134 134 __section(".discard.gendwarfksyms.kabi_rules") = \ 135 - "1\0" #hint "\0" #target "\0" #value 135 + "1\0" #hint "\0" target "\0" value 136 + 137 + #define __KABI_RULE(hint, target, value) \ 138 + ___KABI_RULE(hint, #target, #value) 136 139 137 140 138 141 Currently, only the rules discussed in this section are supported, but ··· 226 223 KABI_ENUMERATOR_IGNORE(e, C); 227 224 KABI_ENUMERATOR_VALUE(e, LAST, 2); 228 225 226 + Managing structure size changes 227 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 228 + 229 + A data structure can be partially opaque to modules if its allocation is 230 + handled by the core kernel, and modules only need to access some of its 231 + members. In this situation, it's possible to append new members to the 232 + structure without breaking the ABI, as long as the layout for the original 233 + members remains unchanged. 234 + 235 + To append new members, we can hide them from symbol versioning as 236 + described in section :ref:`Hiding members <hiding_members>`, but we can't 237 + hide the increase in structure size. The `byte_size` rule allows us to 238 + override the structure size used for symbol versioning. 239 + 240 + The rule fields are expected to be as follows: 241 + 242 + - `type`: "byte_size" 243 + - `target`: The fully qualified name of the target data structure 244 + (as shown in **--dump-dies** output). 245 + - `value`: A positive decimal number indicating the structure size 246 + in bytes. 247 + 248 + Using the `__KABI_RULE` macro, this rule can be defined as:: 249 + 250 + #define KABI_BYTE_SIZE(fqn, value) \ 251 + __KABI_RULE(byte_size, fqn, value) 252 + 253 + Example usage:: 254 + 255 + struct s { 256 + /* Unchanged original members */ 257 + unsigned long a; 258 + void *p; 259 + 260 + /* Appended new members */ 261 + KABI_IGNORE(0, unsigned long n); 262 + }; 263 + 264 + KABI_BYTE_SIZE(s, 16); 265 + 266 + Overriding type strings 267 + ~~~~~~~~~~~~~~~~~~~~~~~ 268 + 269 + In rare situations where distributions must make significant changes to 270 + otherwise opaque data structures that have inadvertently been included 271 + in the published ABI, keeping symbol versions stable using the more 272 + targeted kABI rules can become tedious. The `type_string` rule allows us 273 + to override the full type string for a type or a symbol, and even add 274 + types for versioning that no longer exist in the kernel. 275 + 276 + The rule fields are expected to be as follows: 277 + 278 + - `type`: "type_string" 279 + - `target`: The fully qualified name of the target data structure 280 + (as shown in **--dump-dies** output) or symbol. 281 + - `value`: A valid type string (as shown in **--symtypes**) output) 282 + to use instead of the real type. 283 + 284 + Using the `__KABI_RULE` macro, this rule can be defined as:: 285 + 286 + #define KABI_TYPE_STRING(type, str) \ 287 + ___KABI_RULE("type_string", type, str) 288 + 289 + Example usage:: 290 + 291 + /* Override type for a structure */ 292 + KABI_TYPE_STRING("s#s", 293 + "structure_type s { " 294 + "member base_type int byte_size(4) " 295 + "encoding(5) n " 296 + "data_member_location(0) " 297 + "} byte_size(8)"); 298 + 299 + /* Override type for a symbol */ 300 + KABI_TYPE_STRING("my_symbol", "variable s#s"); 301 + 302 + The `type_string` rule should be used only as a last resort if maintaining 303 + a stable symbol versions cannot be reasonably achieved using other 304 + means. Overriding a type string increases the risk of actual ABI breakages 305 + going unnoticed as it hides all changes to the type. 306 + 229 307 Adding structure members 230 308 ------------------------ 231 309 ··· 360 276 simplify the process and also ensure the replacement member is correctly 361 277 aligned and its size won't exceed the reserved space. 362 278 279 + .. _hiding_members: 280 + 363 281 Hiding members 364 282 ~~~~~~~~~~~~~~ 365 283 ··· 391 305 unsigned long b; 392 306 }; 393 307 394 - With **--stable**, both versions produce the same symbol version. 308 + With **--stable**, both versions produce the same symbol version. The 309 + examples include a `KABI_IGNORE` macro to simplify the code.