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; }), __FILE__                                 \
44                       ":" __stringify(__LINE__) ": " __stringify(_new) " is larger than " __stringify(_orig));        \
45        _Static_assert(                                                                                                \
46            __alignof__(struct { _new; }) <= __alignof__(struct { _orig; }), __FILE__                                  \
47            ":" __stringify(__LINE__) ": " __stringify(_orig) " is not aligned the same as " __stringify(_new));       \
48    }
49
50#ifdef __GENKSYMS__
51
52#define _ANDROID_KABI_REPLACE(_orig, _new) _orig
53
54#else
55
56#define _ANDROID_KABI_REPLACE(_orig, _new)                                                                             \
57    union {                                                                                                            \
58        _new;                                                                                                          \
59        struct {                                                                                                       \
60            _orig;                                                                                                     \
61        } __UNIQUE_ID(android_kabi_hide);                                                                              \
62        __ANDROID_KABI_CHECK_SIZE_ALIGN(_orig, _new);                                                                  \
63    }
64
65#endif /* __GENKSYMS__ */
66
67#define _ANDROID_KABI_RESERVE(n) u64 android_kabi_reserved##n
68
69/*
70 * Macros to use _before_ the ABI is frozen
71 */
72
73/*
74 * ANDROID_KABI_RESERVE
75 *   Reserve some "padding" in a structure for potential future use.
76 *   This normally placed at the end of a structure.
77 *   number: the "number" of the padding variable in the structure.  Start with
78 *   1 and go up.
79 */
80#define ANDROID_KABI_RESERVE(number) _ANDROID_KABI_RESERVE(number)
81
82/*
83 * Macros to use _after_ the ABI is frozen
84 */
85
86/*
87 * ANDROID_KABI_USE(number, _new)
88 *   Use a previous padding entry that was defined with ANDROID_KABI_RESERVE
89 *   number: the previous "number" of the padding variable
90 *   _new: the variable to use now instead of the padding variable
91 */
92#define ANDROID_KABI_USE(number, _new) _ANDROID_KABI_REPLACE(_ANDROID_KABI_RESERVE(number), _new)
93
94/*
95 * ANDROID_KABI_USE2(number, _new1, _new2)
96 *   Use a previous padding entry that was defined with ANDROID_KABI_RESERVE for
97 *   two new variables that fit into 64 bits.  This is good for when you do not
98 *   want to "burn" a 64bit padding variable for a smaller variable size if not
99 *   needed.
100 */
101#define ANDROID_KABI_USE2(number, _new1, _new2)                                                                        \
102    _ANDROID_KABI_REPLACE(                                                                                             \
103        _ANDROID_KABI_RESERVE(number), struct {                                                                        \
104            _new1;                                                                                                     \
105            _new2;                                                                                                     \
106        })
107
108#endif /* _ANDROID_KABI_H */
109