1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * android_kabi.h - Android kernel abi abstraction header 4 * 5 * Copyright (C) 2020-2025 Google, Inc. 6 * 7 * Heavily influenced by rh_kabi.h which came from the RHEL/CENTOS kernel and 8 * was: 9 * Copyright (c) 2014 Don Zickus 10 * Copyright (c) 2015-2018 Jiri Benc 11 * Copyright (c) 2015 Sabrina Dubroca, Hannes Frederic Sowa 12 * Copyright (c) 2016-2018 Prarit Bhargava 13 * Copyright (c) 2017 Paolo Abeni, Larry Woodman 14 * 15 * These macros are to be used to try to help alleviate future kernel abi 16 * changes that will occur as LTS and other kernel patches are merged into the 17 * tree during a period in which the kernel abi is wishing to not be disturbed. 18 * 19 * There are two times these macros should be used: 20 * - Before the kernel abi is "frozen" 21 * Padding can be added to various kernel structures that have in the past 22 * been known to change over time. That will give "room" in the structure 23 * that can then be used when fields are added so that the structure size 24 * will not change. 25 * 26 * - After the kernel abi is "frozen" 27 * If a structure's field is changed to a type that is identical in size to 28 * the previous type, it can be changed with a union macro 29 * If a field is added to a structure, the padding fields can be used to add 30 * the new field in a "safe" way. 31 */ 32 33 #ifndef _ANDROID_KABI_H 34 #define _ANDROID_KABI_H 35 36 #include <linux/args.h> 37 #include <linux/compiler.h> 38 #include <linux/compiler_attributes.h> 39 #include <linux/stringify.h> 40 41 /* 42 * Worker macros, don't use these, use the ones without a leading '_' 43 */ 44 45 #if defined(BUILD_VDSO) || defined(__DISABLE_EXPORTS) 46 #define __ANDROID_KABI_RULE(hint, target, value) 47 #else 48 #define __ANDROID_KABI_RULE(hint, target, value) \ 49 static const char CONCATENATE(__gendwarfksyms_rule_, \ 50 __COUNTER__)[] __used __aligned(1) \ 51 __section(".discard.gendwarfksyms.kabi_rules") = \ 52 "1\0" #hint "\0" target "\0" value 53 #endif 54 55 #define _ANDROID_KABI_RULE(hint, target, value) \ 56 __ANDROID_KABI_RULE(hint, #target, #value) 57 58 #define _ANDROID_KABI_NORMAL_SIZE_ALIGN(_orig, _new) \ 59 union { \ 60 _Static_assert( \ 61 sizeof(struct { _new; }) <= \ 62 sizeof(struct { _orig; }), \ 63 FILE_LINE ": " __stringify(_new) \ 64 " is larger than " __stringify(_orig)); \ 65 _Static_assert( \ 66 __alignof__(struct { _new; }) <= \ 67 __alignof__(struct { _orig; }), \ 68 FILE_LINE ": " __stringify(_orig) \ 69 " is not aligned the same as " \ 70 __stringify(_new)); \ 71 } 72 73 #define _ANDROID_KABI_REPLACE(_orig, _new) \ 74 union { \ 75 _new; \ 76 struct { \ 77 _orig; \ 78 }; \ 79 _ANDROID_KABI_NORMAL_SIZE_ALIGN(_orig, _new); \ 80 } 81 82 83 /* 84 * Macros to use _before_ the ABI is frozen 85 */ 86 87 /* 88 * ANDROID_KABI_RESERVE 89 * Reserve some "padding" in a structure for use by LTS backports. 90 * This normally placed at the end of a structure. 91 * number: the "number" of the padding variable in the structure. Start with 92 * 1 and go up. 93 * 94 * 95 * ANDROID_BACKPORT_RESERVE 96 * Similar to ANDROID_KABI_RESERVE, but this is for planned feature backports 97 * (not for LTS). 98 */ 99 #define ANDROID_KABI_RESERVE(number) u64 __kabi_reserved##number 100 #define ANDROID_BACKPORT_RESERVE(number) u64 __kabi_reserved_backport##number 101 102 /* 103 * Macros to use _after_ the ABI is frozen 104 */ 105 106 /* 107 * ANDROID_KABI_DECLONLY(fqn) 108 * Treat the struct/union/enum fqn as a declaration, i.e. even if 109 * a definition is available, don't expand the contents. 110 */ 111 #define ANDROID_KABI_DECLONLY(fqn) _ANDROID_KABI_RULE(declonly, fqn, /**/) 112 113 /* 114 * ANDROID_KABI_ENUMERATOR_IGNORE(fqn, field) 115 * When expanding enum fqn, skip the provided field. This makes it 116 * possible to hide added enum fields from versioning. 117 */ 118 #define ANDROID_KABI_ENUMERATOR_IGNORE(fqn, field) \ 119 _ANDROID_KABI_RULE(enumerator_ignore, fqn field, /**/) 120 121 /* 122 * ANDROID_KABI_ENUMERATOR_VALUE(fqn, field, value) 123 * When expanding enum fqn, use the provided value for the 124 * specified field. This makes it possible to override enumerator 125 * values when calculating versions. 126 */ 127 #define ANDROID_KABI_ENUMERATOR_VALUE(fqn, field, value) \ 128 _ANDROID_KABI_RULE(enumerator_value, fqn field, value) 129 130 /* 131 * ANDROID_KABI_BYTE_SIZE(fqn, value) 132 * Set the byte_size attribute for the struct/union/enum fqn to 133 * value bytes. 134 */ 135 #define ANDROID_KABI_BYTE_SIZE(fqn, value) \ 136 _ANDROID_KABI_RULE(byte_size, fqn, value) 137 138 /* 139 * ANDROID_KABI_TYPE_STRING(type, str) 140 * For the given type, override the type string used in symtypes 141 * output and version calculation with str. 142 */ 143 #define ANDROID_KABI_TYPE_STRING(type, str) \ 144 __ANDROID_KABI_RULE(type_string, type, str) 145 146 /* 147 * ANDROID_KABI_IGNORE 148 * Add a new field that's ignored in versioning. 149 */ 150 #define ANDROID_KABI_IGNORE(n, _new) \ 151 union { \ 152 _new; \ 153 unsigned char __kabi_ignored##n; \ 154 } 155 156 /* 157 * ANDROID_KABI_REPLACE 158 * Replace a field with a compatible new field. 159 */ 160 #define ANDROID_KABI_REPLACE(_oldtype, _oldname, _new) \ 161 _ANDROID_KABI_REPLACE(_oldtype __kabi_renamed##_oldname, struct { _new; }) 162 163 /* 164 * ANDROID_KABI_USE(number, _new) 165 * Use a previous padding entry that was defined with ANDROID_KABI_RESERVE 166 * number: the previous "number" of the padding variable 167 * _new: the variable to use now instead of the padding variable 168 */ 169 #define ANDROID_KABI_USE(number, _new) \ 170 _ANDROID_KABI_REPLACE(ANDROID_KABI_RESERVE(number), _new) 171 172 /* 173 * ANDROID_KABI_USE2(number, _new1, _new2) 174 * Use a previous padding entry that was defined with ANDROID_KABI_RESERVE for 175 * two new variables that fit into 64 bits. This is good for when you do not 176 * want to "burn" a 64bit padding variable for a smaller variable size if not 177 * needed. 178 */ 179 #define ANDROID_KABI_USE2(number, _new1, _new2) \ 180 _ANDROID_KABI_REPLACE(ANDROID_KABI_RESERVE(number), struct{ _new1; _new2; }) 181 182 /* 183 * ANDROID_BACKPORT_USE(number, _new) 184 * Use a previous padding entry that was defined with ANDROID_BACKPORT_RESERVE 185 * number: the previous "number" of the padding variable 186 * _new: the variable to use now instead of the padding variable 187 */ 188 #define ANDROID_BACKPORT_USE(number, _new) \ 189 _ANDROID_KABI_REPLACE(ANDROID_BACKPORT_RESERVE(number), _new) 190 191 #endif /* _ANDROID_KABI_H */ 192