1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Copyright (C) 2024 Google LLC 4 * 5 * Example macros for maintaining kABI stability. 6 * 7 * This file is based on android_kabi.h, which has the following notice: 8 * 9 * Heavily influenced by rh_kabi.h which came from the RHEL/CENTOS kernel 10 * and was: 11 * Copyright (c) 2014 Don Zickus 12 * Copyright (c) 2015-2018 Jiri Benc 13 * Copyright (c) 2015 Sabrina Dubroca, Hannes Frederic Sowa 14 * Copyright (c) 2016-2018 Prarit Bhargava 15 * Copyright (c) 2017 Paolo Abeni, Larry Woodman 16 */ 17 18 #ifndef __KABI_H__ 19 #define __KABI_H__ 20 21 /* Kernel macros for userspace testing. */ 22 #ifndef __aligned 23 #define __aligned(x) __attribute__((__aligned__(x))) 24 #endif 25 #ifndef __used 26 #define __used __attribute__((__used__)) 27 #endif 28 #ifndef __section 29 #define __section(section) __attribute__((__section__(section))) 30 #endif 31 #ifndef __PASTE 32 #define ___PASTE(a, b) a##b 33 #define __PASTE(a, b) ___PASTE(a, b) 34 #endif 35 #ifndef __stringify 36 #define __stringify_1(x...) #x 37 #define __stringify(x...) __stringify_1(x) 38 #endif 39 40 #define ___KABI_RULE(hint, target, value) \ 41 static const char __PASTE(__gendwarfksyms_rule_, \ 42 __COUNTER__)[] __used __aligned(1) \ 43 __section(".discard.gendwarfksyms.kabi_rules") = \ 44 "1\0" #hint "\0" target "\0" value 45 46 #define __KABI_RULE(hint, target, value) \ 47 ___KABI_RULE(hint, #target, #value) 48 49 #define __KABI_NORMAL_SIZE_ALIGN(_orig, _new) \ 50 union { \ 51 _Static_assert( \ 52 sizeof(struct { _new; }) <= sizeof(struct { _orig; }), \ 53 __FILE__ ":" __stringify(__LINE__) ": " __stringify( \ 54 _new) " is larger than " __stringify(_orig)); \ 55 _Static_assert( \ 56 __alignof__(struct { _new; }) <= \ 57 __alignof__(struct { _orig; }), \ 58 __FILE__ ":" __stringify(__LINE__) ": " __stringify( \ 59 _orig) " is not aligned the same as " __stringify(_new)); \ 60 } 61 62 #define __KABI_REPLACE(_orig, _new) \ 63 union { \ 64 _new; \ 65 struct { \ 66 _orig; \ 67 }; \ 68 __KABI_NORMAL_SIZE_ALIGN(_orig, _new); \ 69 } 70 71 /* 72 * KABI_DECLONLY(fqn) 73 * Treat the struct/union/enum fqn as a declaration, i.e. even if 74 * a definition is available, don't expand the contents. 75 */ 76 #define KABI_DECLONLY(fqn) __KABI_RULE(declonly, fqn, ) 77 78 /* 79 * KABI_ENUMERATOR_IGNORE(fqn, field) 80 * When expanding enum fqn, skip the provided field. This makes it 81 * possible to hide added enum fields from versioning. 82 */ 83 #define KABI_ENUMERATOR_IGNORE(fqn, field) \ 84 __KABI_RULE(enumerator_ignore, fqn field, ) 85 86 /* 87 * KABI_ENUMERATOR_VALUE(fqn, field, value) 88 * When expanding enum fqn, use the provided value for the 89 * specified field. This makes it possible to override enumerator 90 * values when calculating versions. 91 */ 92 #define KABI_ENUMERATOR_VALUE(fqn, field, value) \ 93 __KABI_RULE(enumerator_value, fqn field, value) 94 95 /* 96 * KABI_BYTE_SIZE(fqn, value) 97 * Set the byte_size attribute for the struct/union/enum fqn to 98 * value bytes. 99 */ 100 #define KABI_BYTE_SIZE(fqn, value) __KABI_RULE(byte_size, fqn, value) 101 102 /* 103 * KABI_TYPE_STRING(type, str) 104 * For the given type, override the type string used in symtypes 105 * output and version calculation with str. 106 */ 107 #define KABI_TYPE_STRING(type, str) ___KABI_RULE(type_string, type, str) 108 109 /* 110 * KABI_RESERVE 111 * Reserve some "padding" in a structure for use by LTS backports. 112 * This is normally placed at the end of a structure. 113 * number: the "number" of the padding variable in the structure. Start with 114 * 1 and go up. 115 */ 116 #define KABI_RESERVE(n) unsigned long __kabi_reserved##n 117 118 /* 119 * KABI_RESERVE_ARRAY 120 * Same as _BACKPORT_RESERVE but allocates an array with the specified 121 * size in bytes. 122 */ 123 #define KABI_RESERVE_ARRAY(n, s) \ 124 unsigned char __aligned(8) __kabi_reserved##n[s] 125 126 /* 127 * KABI_IGNORE 128 * Add a new field that's ignored in versioning. 129 */ 130 #define KABI_IGNORE(n, _new) \ 131 union { \ 132 _new; \ 133 unsigned char __kabi_ignored##n; \ 134 } 135 136 /* 137 * KABI_REPLACE 138 * Replace a field with a compatible new field. 139 */ 140 #define KABI_REPLACE(_oldtype, _oldname, _new) \ 141 __KABI_REPLACE(_oldtype __kabi_renamed##_oldname, struct { _new; }) 142 143 /* 144 * KABI_USE(number, _new) 145 * Use a previous padding entry that was defined with KABI_RESERVE 146 * number: the previous "number" of the padding variable 147 * _new: the variable to use now instead of the padding variable 148 */ 149 #define KABI_USE(number, _new) __KABI_REPLACE(KABI_RESERVE(number), _new) 150 151 /* 152 * KABI_USE2(number, _new1, _new2) 153 * Use a previous padding entry that was defined with KABI_RESERVE for 154 * two new variables that fit into 64 bits. This is good for when you do not 155 * want to "burn" a 64bit padding variable for a smaller variable size if not 156 * needed. 157 */ 158 #define KABI_USE2(number, _new1, _new2) \ 159 __KABI_REPLACE( \ 160 KABI_RESERVE(number), struct { \ 161 _new1; \ 162 _new2; \ 163 }) 164 /* 165 * KABI_USE_ARRAY(number, bytes, _new) 166 * Use a previous padding entry that was defined with KABI_RESERVE_ARRAY 167 * number: the previous "number" of the padding variable 168 * bytes: the size in bytes reserved for the array 169 * _new: the variable to use now instead of the padding variable 170 */ 171 #define KABI_USE_ARRAY(number, bytes, _new) \ 172 __KABI_REPLACE(KABI_RESERVE_ARRAY(number, bytes), _new) 173 174 #endif /* __KABI_H__ */ 175