ANDROID: GKI: add android_kabi.h

This header file is to be used for various macros to help make keeping
the kernel ABI "stable" during an "ABI Freeze" period.

They are to be used both before the freeze (to anticipate places where
there will be changes), and after the freeze (to keep the abi stable for
structures where there were changes due to LTS or other changes to the
kernel tree.)

Strongly based on rh_kabi.h from Red Hat's RHEL kernel tree.

This adds support for "real" padding and the ability to replace fields
with other fields.

But, note that ABI changes will still be caught by libabigail at this
point in time, work on that is still ongoing.  When that is completed,
all that will be needed is to modify the _ANDROID_KABI_RESERVE() macro
in this file.  No other file changes should be needed.

Bug: 151154716
Signed-off-by: Greg Kroah-Hartman <gregkh@google.com>
Change-Id: I77038cc251c819c3ed22a9cb8843b185416b6727

diff --git a/include/linux/android_kabi.h b/include/linux/android_kabi.h
new file mode 100644 (file)
index 0000000..efa5295
--- /dev/null
+++ b/include/linux/android_kabi.h
@@ -0,0 +1,113 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * android_kabi.h - Android kernel abi abstraction header
+ *
+ * Copyright (C) 2020 Google, Inc.
+ *
+ * Heavily influenced by rh_kabi.h which came from the RHEL/CENTOS kernel and
+ * was:
+ *     Copyright (c) 2014 Don Zickus
+ *     Copyright (c) 2015-2018 Jiri Benc
+ *     Copyright (c) 2015 Sabrina Dubroca, Hannes Frederic Sowa
+ *     Copyright (c) 2016-2018 Prarit Bhargava
+ *     Copyright (c) 2017 Paolo Abeni, Larry Woodman
+ *
+ * These macros are to be used to try to help alleviate future kernel abi
+ * changes that will occur as LTS and other kernel patches are merged into the
+ * tree during a period in which the kernel abi is wishing to not be disturbed.
+ *
+ * There are two times these macros should be used:
+ *  - Before the kernel abi is "frozen"
+ *    Padding can be added to various kernel structures that have in the past
+ *    been known to change over time.  That will give "room" in the structure
+ *    that can then be used when fields are added so that the structure size
+ *    will not change.
+ *
+ *  - After the kernel abi is "frozen"
+ *    If a structure's field is changed to a type that is identical in size to
+ *    the previous type, it can be changed with a union macro
+ *    If a field is added to a structure, the padding fields can be used to add
+ *    the new field in a "safe" way.
+ */
+#ifndef _ANDROID_KABI_H
+#define _ANDROID_KABI_H
+
+#include <linux/compiler.h>
+
+/*
+ * Worker macros, don't use these, use the ones without a leading '_'
+ */
+
+#define __ANDROID_KABI_CHECK_SIZE_ALIGN(_orig, _new)                           \
+       union {                                                                 \
+               _Static_assert(sizeof(struct{_new;}) <= sizeof(struct{_orig;}), \
+                              __FILE__ ":" __stringify(__LINE__) ": "          \
+                              __stringify(_new)                                \
+                              " is larger than "                               \
+                              __stringify(_orig) );                            \
+               _Static_assert(__alignof__(struct{_new;}) <= __alignof__(struct{_orig;}),       \
+                              __FILE__ ":" __stringify(__LINE__) ": "          \
+                              __stringify(_orig)                               \
+                              " is not aligned the same as "                   \
+                              __stringify(_new) );                             \
+       }
+
+#ifdef __GENKSYMS__
+
+#define _ANDROID_KABI_REPLACE(_orig, _new)             _orig
+
+#else
+
+#define _ANDROID_KABI_REPLACE(_orig, _new)                     \
+       union {                                                 \
+               _new;                                           \
+               struct {                                        \
+                       _orig;                                  \
+               } __UNIQUE_ID(android_kabi_hide);               \
+               __ANDROID_KABI_CHECK_SIZE_ALIGN(_orig, _new);   \
+       }
+
+#endif /* __GENKSYMS__ */
+
+#define _ANDROID_KABI_RESERVE(n)               u64 android_kabi_reserved##n
+
+
+/*
+ * Macros to use _before_ the ABI is frozen
+ */
+
+/*
+ * ANDROID_KABI_RESERVE
+ *   Reserve some "padding" in a structure for potential future use.
+ *   This normally placed at the end of a structure.
+ *   number: the "number" of the padding variable in the structure.  Start with
+ *   1 and go up.
+ */
+#define ANDROID_KABI_RESERVE(number)   _ANDROID_KABI_RESERVE(number)
+
+
+/*
+ * Macros to use _after_ the ABI is frozen
+ */
+
+/*
+ * ANDROID_KABI_USE(number, _new)
+ *   Use a previous padding entry that was defined with ANDROID_KABI_RESERVE
+ *   number: the previous "number" of the padding variable
+ *   _new: the variable to use now instead of the padding variable
+ */
+#define ANDROID_KABI_USE(number, _new)         \
+       _ANDROID_KABI_REPLACE(_ANDROID_KABI_RESERVE(number), _new)
+
+/*
+ * ANDROID_KABI_USE2(number, _new1, _new2)
+ *   Use a previous padding entry that was defined with ANDROID_KABI_RESERVE for
+ *   two new variables that fit into 64 bits.  This is good for when you do not
+ *   want to "burn" a 64bit padding variable for a smaller variable size if not
+ *   needed.
+ */
+#define ANDROID_KABI_USE2(number, _new1, _new2)                        \
+       _ANDROID_KABI_REPLACE(_ANDROID_KABI_RESERVE(number), struct{ _new1; _new2; })
+
+
+#endif /* _ANDROID_KABI_H */