1*4882a593Smuzhiyun /* SPDX-License-Identifier: GPL-2.0-only */ 2*4882a593Smuzhiyun /* 3*4882a593Smuzhiyun * android_kabi.h - Android kernel abi abstraction header 4*4882a593Smuzhiyun * 5*4882a593Smuzhiyun * Copyright (C) 2020 Google, Inc. 6*4882a593Smuzhiyun * 7*4882a593Smuzhiyun * Heavily influenced by rh_kabi.h which came from the RHEL/CENTOS kernel and 8*4882a593Smuzhiyun * was: 9*4882a593Smuzhiyun * Copyright (c) 2014 Don Zickus 10*4882a593Smuzhiyun * Copyright (c) 2015-2018 Jiri Benc 11*4882a593Smuzhiyun * Copyright (c) 2015 Sabrina Dubroca, Hannes Frederic Sowa 12*4882a593Smuzhiyun * Copyright (c) 2016-2018 Prarit Bhargava 13*4882a593Smuzhiyun * Copyright (c) 2017 Paolo Abeni, Larry Woodman 14*4882a593Smuzhiyun * 15*4882a593Smuzhiyun * These macros are to be used to try to help alleviate future kernel abi 16*4882a593Smuzhiyun * changes that will occur as LTS and other kernel patches are merged into the 17*4882a593Smuzhiyun * tree during a period in which the kernel abi is wishing to not be disturbed. 18*4882a593Smuzhiyun * 19*4882a593Smuzhiyun * There are two times these macros should be used: 20*4882a593Smuzhiyun * - Before the kernel abi is "frozen" 21*4882a593Smuzhiyun * Padding can be added to various kernel structures that have in the past 22*4882a593Smuzhiyun * been known to change over time. That will give "room" in the structure 23*4882a593Smuzhiyun * that can then be used when fields are added so that the structure size 24*4882a593Smuzhiyun * will not change. 25*4882a593Smuzhiyun * 26*4882a593Smuzhiyun * - After the kernel abi is "frozen" 27*4882a593Smuzhiyun * If a structure's field is changed to a type that is identical in size to 28*4882a593Smuzhiyun * the previous type, it can be changed with a union macro 29*4882a593Smuzhiyun * If a field is added to a structure, the padding fields can be used to add 30*4882a593Smuzhiyun * the new field in a "safe" way. 31*4882a593Smuzhiyun */ 32*4882a593Smuzhiyun #ifndef _ANDROID_KABI_H 33*4882a593Smuzhiyun #define _ANDROID_KABI_H 34*4882a593Smuzhiyun 35*4882a593Smuzhiyun #include <linux/compiler.h> 36*4882a593Smuzhiyun 37*4882a593Smuzhiyun /* 38*4882a593Smuzhiyun * Worker macros, don't use these, use the ones without a leading '_' 39*4882a593Smuzhiyun */ 40*4882a593Smuzhiyun 41*4882a593Smuzhiyun #define __ANDROID_KABI_CHECK_SIZE_ALIGN(_orig, _new) \ 42*4882a593Smuzhiyun union { \ 43*4882a593Smuzhiyun _Static_assert(sizeof(struct{_new;}) <= sizeof(struct{_orig;}), \ 44*4882a593Smuzhiyun __FILE__ ":" __stringify(__LINE__) ": " \ 45*4882a593Smuzhiyun __stringify(_new) \ 46*4882a593Smuzhiyun " is larger than " \ 47*4882a593Smuzhiyun __stringify(_orig) ); \ 48*4882a593Smuzhiyun _Static_assert(__alignof__(struct{_new;}) <= __alignof__(struct{_orig;}), \ 49*4882a593Smuzhiyun __FILE__ ":" __stringify(__LINE__) ": " \ 50*4882a593Smuzhiyun __stringify(_orig) \ 51*4882a593Smuzhiyun " is not aligned the same as " \ 52*4882a593Smuzhiyun __stringify(_new) ); \ 53*4882a593Smuzhiyun } 54*4882a593Smuzhiyun 55*4882a593Smuzhiyun #ifdef __GENKSYMS__ 56*4882a593Smuzhiyun 57*4882a593Smuzhiyun #define _ANDROID_KABI_REPLACE(_orig, _new) _orig 58*4882a593Smuzhiyun 59*4882a593Smuzhiyun #else 60*4882a593Smuzhiyun 61*4882a593Smuzhiyun #define _ANDROID_KABI_REPLACE(_orig, _new) \ 62*4882a593Smuzhiyun union { \ 63*4882a593Smuzhiyun _new; \ 64*4882a593Smuzhiyun struct { \ 65*4882a593Smuzhiyun _orig; \ 66*4882a593Smuzhiyun }; \ 67*4882a593Smuzhiyun __ANDROID_KABI_CHECK_SIZE_ALIGN(_orig, _new); \ 68*4882a593Smuzhiyun } 69*4882a593Smuzhiyun 70*4882a593Smuzhiyun #endif /* __GENKSYMS__ */ 71*4882a593Smuzhiyun 72*4882a593Smuzhiyun #define _ANDROID_KABI_RESERVE(n) u64 android_kabi_reserved##n 73*4882a593Smuzhiyun 74*4882a593Smuzhiyun 75*4882a593Smuzhiyun /* 76*4882a593Smuzhiyun * Macros to use _before_ the ABI is frozen 77*4882a593Smuzhiyun */ 78*4882a593Smuzhiyun 79*4882a593Smuzhiyun /* 80*4882a593Smuzhiyun * ANDROID_KABI_RESERVE 81*4882a593Smuzhiyun * Reserve some "padding" in a structure for potential future use. 82*4882a593Smuzhiyun * This normally placed at the end of a structure. 83*4882a593Smuzhiyun * number: the "number" of the padding variable in the structure. Start with 84*4882a593Smuzhiyun * 1 and go up. 85*4882a593Smuzhiyun */ 86*4882a593Smuzhiyun #ifdef CONFIG_ANDROID_KABI_RESERVE 87*4882a593Smuzhiyun #define ANDROID_KABI_RESERVE(number) _ANDROID_KABI_RESERVE(number) 88*4882a593Smuzhiyun #else 89*4882a593Smuzhiyun #define ANDROID_KABI_RESERVE(number) 90*4882a593Smuzhiyun #endif 91*4882a593Smuzhiyun 92*4882a593Smuzhiyun 93*4882a593Smuzhiyun /* 94*4882a593Smuzhiyun * Macros to use _after_ the ABI is frozen 95*4882a593Smuzhiyun */ 96*4882a593Smuzhiyun 97*4882a593Smuzhiyun /* 98*4882a593Smuzhiyun * ANDROID_KABI_USE(number, _new) 99*4882a593Smuzhiyun * Use a previous padding entry that was defined with ANDROID_KABI_RESERVE 100*4882a593Smuzhiyun * number: the previous "number" of the padding variable 101*4882a593Smuzhiyun * _new: the variable to use now instead of the padding variable 102*4882a593Smuzhiyun */ 103*4882a593Smuzhiyun #define ANDROID_KABI_USE(number, _new) \ 104*4882a593Smuzhiyun _ANDROID_KABI_REPLACE(_ANDROID_KABI_RESERVE(number), _new) 105*4882a593Smuzhiyun 106*4882a593Smuzhiyun /* 107*4882a593Smuzhiyun * ANDROID_KABI_USE2(number, _new1, _new2) 108*4882a593Smuzhiyun * Use a previous padding entry that was defined with ANDROID_KABI_RESERVE for 109*4882a593Smuzhiyun * two new variables that fit into 64 bits. This is good for when you do not 110*4882a593Smuzhiyun * want to "burn" a 64bit padding variable for a smaller variable size if not 111*4882a593Smuzhiyun * needed. 112*4882a593Smuzhiyun */ 113*4882a593Smuzhiyun #define ANDROID_KABI_USE2(number, _new1, _new2) \ 114*4882a593Smuzhiyun _ANDROID_KABI_REPLACE(_ANDROID_KABI_RESERVE(number), struct{ _new1; _new2; }) 115*4882a593Smuzhiyun 116*4882a593Smuzhiyun 117*4882a593Smuzhiyun #endif /* _ANDROID_KABI_H */ 118