1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * android_kabi.h - Android kernel abi abstraction header 4 * 5 * Copyright (C) 2020 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 #ifndef _ANDROID_KABI_H 33 #define _ANDROID_KABI_H 34 35 #include <linux/compiler.h> 36 37 /* 38 * Worker macros, don't use these, use the ones without a leading '_' 39 */ 40 41 #define __ANDROID_KABI_CHECK_SIZE_ALIGN(_orig, _new) \ 42 union { \ 43 _Static_assert(sizeof(struct{_new;}) <= sizeof(struct{_orig;}), \ 44 __FILE__ ":" __stringify(__LINE__) ": " \ 45 __stringify(_new) \ 46 " is larger than " \ 47 __stringify(_orig) ); \ 48 _Static_assert(__alignof__(struct{_new;}) <= __alignof__(struct{_orig;}), \ 49 __FILE__ ":" __stringify(__LINE__) ": " \ 50 __stringify(_orig) \ 51 " is not aligned the same as " \ 52 __stringify(_new) ); \ 53 } 54 55 #ifdef __GENKSYMS__ 56 57 #define _ANDROID_KABI_REPLACE(_orig, _new) _orig 58 59 #else 60 61 #define _ANDROID_KABI_REPLACE(_orig, _new) \ 62 union { \ 63 _new; \ 64 struct { \ 65 _orig; \ 66 }; \ 67 __ANDROID_KABI_CHECK_SIZE_ALIGN(_orig, _new); \ 68 } 69 70 #endif /* __GENKSYMS__ */ 71 72 #define _ANDROID_KABI_RESERVE(n) u64 android_kabi_reserved##n 73 #define _ANDROID_BACKPORT_RESERVE(n) u64 android_backport_reserved##n 74 #define _ANDROID_BACKPORT_RESERVE_ARRAY(n, s) u8 __aligned(8) android_backport_reserved##n[s] 75 76 77 /* 78 * Macros to use _before_ the ABI is frozen 79 */ 80 81 /* 82 * ANDROID_KABI_RESERVE 83 * Reserve some "padding" in a structure for use by LTS backports. 84 * This normally placed at the end of a structure. 85 * number: the "number" of the padding variable in the structure. Start with 86 * 1 and go up. 87 * 88 * ANDROID_BACKPORT_RESERVE 89 * Similar to ANDROID_KABI_RESERVE, but this is for planned feature backports 90 * (not for LTS). 91 * 92 * ANDROID_BACKPORT_RESERVE_ARRAY 93 * Same as ANDROID_BACKPORT_RESERVE but allocates an array with the specified 94 * size in bytes. 95 */ 96 #ifdef CONFIG_ANDROID_KABI_RESERVE 97 #define ANDROID_KABI_RESERVE(number) _ANDROID_KABI_RESERVE(number) 98 #define ANDROID_BACKPORT_RESERVE(number) _ANDROID_BACKPORT_RESERVE(number) 99 #define ANDROID_BACKPORT_RESERVE_ARRAY(number, bytes) _ANDROID_BACKPORT_RESERVE_ARRAY(number, bytes) 100 #else 101 #define ANDROID_KABI_RESERVE(number) 102 #define ANDROID_BACKPORT_RESERVE(number) 103 #define ANDROID_BACKPORT_RESERVE_ARRAY(number, bytes) 104 #endif 105 106 107 /* 108 * Macros to use _after_ the ABI is frozen 109 */ 110 111 /* 112 * ANDROID_KABI_USE(number, _new) 113 * Use a previous padding entry that was defined with ANDROID_KABI_RESERVE 114 * number: the previous "number" of the padding variable 115 * _new: the variable to use now instead of the padding variable 116 */ 117 #define ANDROID_KABI_USE(number, _new) \ 118 _ANDROID_KABI_REPLACE(_ANDROID_KABI_RESERVE(number), _new) 119 120 /* 121 * ANDROID_KABI_USE2(number, _new1, _new2) 122 * Use a previous padding entry that was defined with ANDROID_KABI_RESERVE for 123 * two new variables that fit into 64 bits. This is good for when you do not 124 * want to "burn" a 64bit padding variable for a smaller variable size if not 125 * needed. 126 */ 127 #define ANDROID_KABI_USE2(number, _new1, _new2) \ 128 _ANDROID_KABI_REPLACE(_ANDROID_KABI_RESERVE(number), struct{ _new1; _new2; }) 129 130 /* 131 * ANDROID_BACKPORT_USE(number, _new) 132 * Use a previous padding entry that was defined with ANDROID_BACKPORT_RESERVE 133 * number: the previous "number" of the padding variable 134 * _new: the variable to use now instead of the padding variable 135 */ 136 #define ANDROID_BACKPORT_USE(number, _new) \ 137 _ANDROID_KABI_REPLACE(_ANDROID_BACKPORT_RESERVE(number), _new) 138 139 /* 140 * ANDROID_BACKPORT_USE2(number, _new1, _new2) 141 * Use a previous padding entry that was defined with ANDROID_BACKPORT_RESERVE 142 * for two new variables that fit into 64 bits. This is good for when you do 143 * not want to "burn" a 64bit padding variable for a smaller variable size if 144 * not needed. 145 */ 146 #define ANDROID_BACKPORT_USE2(number, _new1, _new2) \ 147 _ANDROID_KABI_REPLACE(_ANDROID_BACKPORT_RESERVE(number), struct{ _new1; _new2; }) 148 149 /* 150 * ANDROID_BACKPORT_USE_ARRAY(number, bytes, _new) 151 * Use a previous padding entry that was defined with ANDROID_BACKPORT_RESERVE_ARRAY 152 * number: the previous "number" of the padding variable 153 * bytes: the size in bytes reserved for the array 154 * _new: the variable to use now instead of the padding variable 155 */ 156 #define ANDROID_BACKPORT_USE_ARRAY(number, bytes, _new) \ 157 _ANDROID_KABI_REPLACE(_ANDROID_BACKPORT_RESERVE_ARRAY(number, bytes), _new) 158 159 #endif /* _ANDROID_KABI_H */ 160