From: Prarit Bhargava on gitlab.com Merge Request: https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
Upstream Status: RHEL only
Forward port rh_kabi.h macros.
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
--- include/linux/rh_kabi.h | 436 ++++++++++++++++++++++++++++++++++++------------ 1 files changed, 327 insertions(+), 109 deletions(-)
From: Čestmír Kalina ckalina@redhat.com
kabi: introduce RH_KABI_HIDE_INCLUDE and RH_KABI_FAKE_INCLUDE
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 731d6d62fc7f0246d97e9cb5e29f549e40062b5d Author: Jiri Benc jbenc@redhat.com Date: Wed, 19 Feb 2020 12:04:19 -0500
Introduce a macro for the common pattern of a newly added #include uncovering a previously opaque structure to genksyms or vice versa.
Note that the parameter to the new macros is now subject to macro expansion. Unfortunately, there's a 'linux' macro already defined at the system level with a value of '1'. This would lead to any attempt to include linux/something.h to try to include 1/something.h instead. The 'linux' macro is not really needed in the kernel, we know we're building on Linux; however, to accommodate the rare obsolete cases where it is used (drivers/scsi/aic7xxx/aicasm/aicasm.c and include/linux/a.out.h), keep it defined.
There is also a genksyms-guarded include in drivers/message/fusion/mptlan.h but that is inherited from upstream and it is kept that way by this patch.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -82,6 +82,23 @@ * RH_KABI_REPLACE_UNSAFE * Unsafe version of RH_KABI_REPLACE. Only use for typedefs. * + * RH_KABI_HIDE_INCLUDE + * Hides the given include file from kABI checksum computations. This is + * used when a newly added #include makes a previously opaque struct + * visible. + * + * Example usage: + * #include RH_KABI_HIDE_INCLUDE(<linux/poll.h>) + * + * RH_KABI_FAKE_INCLUDE + * Pretends inclusion of the given file for kABI checksum computations. + * This is used when upstream removed a particular #include but that made + * some structures opaque that were previously visible and is causing kABI + * checker failures. + * + * Example usage: + * #include RH_KABI_FAKE_INCLUDE(<linux/rhashtable.h>) + * * RH_KABI_FORCE_CHANGE * Force change of the symbol checksum. The argument of the macro is a * version for cases we need to do this more than once. @@ -122,6 +139,10 @@ * (mainly for RH_KABI_EXTEND, but applied to all macros for uniformity). * */ + +#undef linux +#define linux linux + #ifdef __GENKSYMS__
# define RH_KABI_CONST @@ -129,6 +150,8 @@ # define RH_KABI_FILL_HOLE(_new) # define RH_KABI_FORCE_CHANGE(ver) __attribute__((rh_kabi_change ## ver)) # define RH_KABI_RENAME(_orig, _new) _orig +# define RH_KABI_HIDE_INCLUDE(_file) <linux/rh_kabi.h> +# define RH_KABI_FAKE_INCLUDE(_file) _file
# define _RH_KABI_DEPRECATE(_type, _orig) _type _orig # define _RH_KABI_DEPRECATE_FN(_type, _orig, _args...) _type (*_orig)(_args) @@ -145,6 +168,8 @@ # define RH_KABI_FILL_HOLE(_new) _new; # define RH_KABI_FORCE_CHANGE(ver) # define RH_KABI_RENAME(_orig, _new) _new +# define RH_KABI_HIDE_INCLUDE(_file) _file +# define RH_KABI_FAKE_INCLUDE(_file) <linux/rh_kabi.h>
#if IS_BUILTIN(CONFIG_RH_KABI_SIZE_ALIGN_CHECKS)
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: fix the note about terminating semicolon
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 4291fec226e36100b080a4834c7d641974435d75 Author: Jiri Benc jbenc@redhat.com Date: Wed, 19 Feb 2020 12:04:20 -0500
Move the note about terminating semicolon to the beginning of the file. The number of macros grew over time and the note got easy to miss.
While moving it, fix the wording. Not all macros add the semicolon, RH_KABI_RENAME does not (in order to be applicable to a wider range of use cases).
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -30,6 +30,14 @@ #include <linux/stringify.h>
/* + * NOTE + * Unless indicated otherwise, don't use ';' after these macros as it + * messes up the kABI checker by changing what the resulting token string + * looks like. Instead let the macros add the ';' so it can be properly + * hidden from the kABI checker (mainly for RH_KABI_EXTEND, but applied to + * most macros for uniformity). + * + * * RH_KABI_CONST * Adds a new const modifier to a function parameter preserving the old * checksum. @@ -67,7 +75,7 @@ * Simple macro for renaming an element without changing its type. This * macro can be used in bitfields, for example. * - * NOTE: does not include the final ';' + * NOTE: this macro does not add the final ';' * * RH_KABI_REPLACE * Simple replacement of _orig with a union of _orig and _new. @@ -132,12 +140,6 @@ * of the size is not allowed and would constitute a silent kABI breakage. * Beware that the RH_KABI_EXCLUDE macro does not do any size checks. * - * NOTE - * Don't use ';' after these macros as it messes up the kABI checker by - * changing what the resulting token string looks like. Instead let this - * macro add the ';' so it can be properly hidden from the kABI checker - * (mainly for RH_KABI_EXTEND, but applied to all macros for uniformity). - * */
#undef linux
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: macros for intentional kABI breakage
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 69bc4518f92fcaafabc846d31e568eedd65264d9 Author: Jiri Benc jbenc@redhat.com Date: Wed, 19 Feb 2020 12:04:22 -0500
Occasionally, we modify a struct that is included from a whitelisted function through a chain of other structs but the modified struct is internal to the kernel and 3rd party modules are not allowed to access it.
In such cases, it is safe and preferable to modify that struct without paying attention to the kABI checksums.
An example of this is bpf rebases: bpf is not considered kABI stable and 3rd party modules may not use it without recompilation between releases. However, through a chain of structs, some bpf structs are part of kABI checksum computations. Given the high volume of changes upstream in the bpf code, we need to keep the added fields at the same places as in upstream to ensure maintainability of RHEL code.
Another example is PHY rebases.
Currently, the code solves it by using the RH_KABI_EXTEND macro. Although it is technically okay and the code will work, it is not the right macro to use, as the RH_KABI macro usage is expected to also serve as a documentation of the kABI workaround used. In particular, RH_KABI_EXTEND means the structure was safely extended, preserving kABI stability. Which is not the case here, we did break kABI (but it was okay to break it).
Introduce new macros that convey this meaning and use them in all places where previously less fitting macros were used.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -2,7 +2,7 @@ * rh_kabi.h - Red Hat kABI abstraction header * * Copyright (c) 2014 Don Zickus - * Copyright (c) 2015-2018 Jiri Benc + * Copyright (c) 2015-2020 Jiri Benc * Copyright (c) 2015 Sabrina Dubroca, Hannes Frederic Sowa * Copyright (c) 2016-2018 Prarit Bhargava * Copyright (c) 2017 Paolo Abeni, Larry Woodman @@ -140,6 +140,30 @@ * of the size is not allowed and would constitute a silent kABI breakage. * Beware that the RH_KABI_EXCLUDE macro does not do any size checks. * + * RH_KABI_BROKEN_INSERT + * RH_KABI_BROKEN_REMOVE + * Insert a field to the middle of a struct / delete a field from a struct. + * Note that this breaks kABI! It can be done only when it's certain that + * no 3rd party driver can validly reach into the struct. A typical + * example is a struct that is: both (a) referenced only through a long + * chain of pointers from another struct that is part of a whitelisted + * symbol and (b) kernel internal only, it should have never been visible + * to genksyms in the first place. + * + * Another example are structs that are explicitly exempt from kABI + * guarantee but we did not have enough foresight to use RH_KABI_EXCLUDE. + * In this case, the warning for RH_KABI_EXCLUDE applies. + * + * A detailed explanation of correctness of every RH_KABI_BROKEN_* macro + * use is especially important. + * + * RH_KABI_BROKEN_INSERT_BLOCK + * RH_KABI_BROKEN_REMOVE_BLOCK + * A version of RH_KABI_BROKEN_INSERT / REMOVE that allows multiple fields + * to be inserted or removed together. All fields need to be terminated + * by ';' inside(!) the macro parameter. The macro itself must not be + * terminated by ';'. + * */
#undef linux @@ -154,6 +178,10 @@ # define RH_KABI_RENAME(_orig, _new) _orig # define RH_KABI_HIDE_INCLUDE(_file) <linux/rh_kabi.h> # define RH_KABI_FAKE_INCLUDE(_file) _file +# define RH_KABI_BROKEN_INSERT(_new) +# define RH_KABI_BROKEN_REMOVE(_orig) _orig; +# define RH_KABI_BROKEN_INSERT_BLOCK(_new) +# define RH_KABI_BROKEN_REMOVE_BLOCK(_orig) _orig
# define _RH_KABI_DEPRECATE(_type, _orig) _type _orig # define _RH_KABI_DEPRECATE_FN(_type, _orig, _args...) _type (*_orig)(_args) @@ -172,6 +200,10 @@ # define RH_KABI_RENAME(_orig, _new) _new # define RH_KABI_HIDE_INCLUDE(_file) _file # define RH_KABI_FAKE_INCLUDE(_file) <linux/rh_kabi.h> +# define RH_KABI_BROKEN_INSERT(_new) _new; +# define RH_KABI_BROKEN_REMOVE(_orig) +# define RH_KABI_BROKEN_INSERT_BLOCK(_new) _new +# define RH_KABI_BROKEN_REMOVE_BLOCK(_orig)
#if IS_BUILTIN(CONFIG_RH_KABI_SIZE_ALIGN_CHECKS)
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: Include kconfig.h
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 4621ba17e720ca93fdd9066e64c1f4fcea957cfc Author: Prarit Bhargava prarit@redhat.com Date: Tue, 31 Mar 2020 17:57:13 -0400
Using this config file by itself to compile code results in an error about IS_BUILTIN() not being defined.
Include kconfig.h.
RH-Signed-off-by: Prarit Bhargava prarit@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -26,6 +26,7 @@ #ifndef _LINUX_RH_KABI_H #define _LINUX_RH_KABI_H
+#include <linux/kconfig.h> #include <linux/compiler.h> #include <linux/stringify.h>
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: introduce RH_KABI_ADD_MODIFIER
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit e8c19640a09931c05012dd9a45c28d12dc7b2a02 Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:03 -0400
This is a generalized version of RH_KABI_CONST.
This allows RH_KABI_REPLACE_UNSAFE to be removed in a later patch.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -43,6 +43,13 @@ * Adds a new const modifier to a function parameter preserving the old * checksum. * + * RH_KABI_ADD_MODIFIER + * Adds a new modifier to a function parameter or a typedef, preserving + * the old checksum. Useful e.g. for adding rcu annotations or changing + * int to unsigned. Beware that this may change the semantics; if you're + * sure this is safe, always explain why binary compatibility with 3rd + * party modules is retained. + * * RH_KABI_DEPRECATE * Mark the element as deprecated and make it unusable by modules while * preserving kABI checksums. @@ -173,6 +180,7 @@ #ifdef __GENKSYMS__
# define RH_KABI_CONST +# define RH_KABI_ADD_MODIFIER(_new) # define RH_KABI_EXTEND(_new) # define RH_KABI_FILL_HOLE(_new) # define RH_KABI_FORCE_CHANGE(ver) __attribute__((rh_kabi_change ## ver)) @@ -195,6 +203,7 @@ # define RH_KABI_ALIGN_WARNING ". Disable CONFIG_RH_KABI_SIZE_ALIGN_CHECKS if debugging."
# define RH_KABI_CONST const +# define RH_KABI_ADD_MODIFIER(_new) _new # define RH_KABI_EXTEND(_new) _new; # define RH_KABI_FILL_HOLE(_new) _new; # define RH_KABI_FORCE_CHANGE(ver)
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: change RH_KABI_REPLACE_UNSAFE to RH_KABI_BROKEN_REPLACE
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit f34b146a5403ff8ad8d7308e59331d38d29cb373 Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:04 -0400
The macro RH_KABI_REPLACE_UNSAFE (and especially its comment) is misleading to developers trying to use it. The macro was needed in the past when RH_KABI_REPLACE was not smart enough and did not allow old and new struct field to have the same name (i.e. type change). This is not the case anymore. Another use of RH_KABI_REPLACE was typedefs but we have a better mechanism to deal with that now.
The only remaining usage of RH_KABI_REPLACE_UNSAFE is in places where we actually want to break the binary representation of the struct. We have RH_KABI_BROKEN_ family of macros for that; rework RH_KABI_REPLACE_UNSAFE to RH_KABI_BROKEN_REPLACE.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -95,9 +95,6 @@ * union structure preserves the size alignment (assuming the '_new' element * is not bigger than the '_orig' element). * - * RH_KABI_REPLACE_UNSAFE - * Unsafe version of RH_KABI_REPLACE. Only use for typedefs. - * * RH_KABI_HIDE_INCLUDE * Hides the given include file from kABI checksum computations. This is * used when a newly added #include makes a previously opaque struct @@ -172,6 +169,10 @@ * by ';' inside(!) the macro parameter. The macro itself must not be * terminated by ';'. * + * RH_KABI_BROKEN_REPLACE + * Replace a field by a different one without doing any checking. This + * allows replacing a field by another with a different size. Similarly + * to other RH_KABI_BROKEN macros, use of this indicates a kABI breakage. */
#undef linux @@ -191,11 +192,11 @@ # define RH_KABI_BROKEN_REMOVE(_orig) _orig; # define RH_KABI_BROKEN_INSERT_BLOCK(_new) # define RH_KABI_BROKEN_REMOVE_BLOCK(_orig) _orig +# define RH_KABI_BROKEN_REPLACE(_orig, _new) _orig;
# define _RH_KABI_DEPRECATE(_type, _orig) _type _orig # define _RH_KABI_DEPRECATE_FN(_type, _orig, _args...) _type (*_orig)(_args) # define _RH_KABI_REPLACE(_orig, _new) _orig -# define _RH_KABI_REPLACE_UNSAFE(_orig, _new) _orig # define _RH_KABI_EXCLUDE(_elem)
#else @@ -214,6 +215,7 @@ # define RH_KABI_BROKEN_REMOVE(_orig) # define RH_KABI_BROKEN_INSERT_BLOCK(_new) _new # define RH_KABI_BROKEN_REMOVE_BLOCK(_orig) +# define RH_KABI_BROKEN_REPLACE(_orig, _new) _new;
#if IS_BUILTIN(CONFIG_RH_KABI_SIZE_ALIGN_CHECKS) @@ -245,7 +247,6 @@ } RH_KABI_UNIQUE_ID; \ __RH_KABI_CHECK_SIZE_ALIGN(_orig, _new); \ } -# define _RH_KABI_REPLACE_UNSAFE(_orig, _new) _new
# define _RH_KABI_EXCLUDE(_elem) _elem
@@ -256,7 +257,6 @@ # define RH_KABI_DEPRECATE_FN(_type, _orig, _args...) \ _RH_KABI_DEPRECATE_FN(_type, _orig, _args); # define RH_KABI_REPLACE(_orig, _new) _RH_KABI_REPLACE(_orig, _new); -# define RH_KABI_REPLACE_UNSAFE(_orig, _new) _RH_KABI_REPLACE_UNSAFE(_orig, _new); /* * Macro for breaking up a random element into two smaller chunks using an * anonymous struct inside an anonymous union.
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: change RH_KABI_REPLACE2 to RH_KABI_REPLACE_SPLIT
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit b78086cc13db60964530d11f1abc897ec769c213 Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:05 -0400
Rename RH_KABI_REPLACE2 to RH_KABI_REPLACE_SPLIT and enhance it to accept any number of replacement fields.
It would be possible to just enhance RH_KABI_REPLACE and not having a separate RH_KABI_REPLACE_SPLIT, however, I decided not to do that for two reasons:
1. For consistency with RH_KABI_USE_SPLIT and generic RH_KABI_USE introduced later. RH_KABI_USE will accept variable number of arguments but those will denote the fields to be replaced. The distinction thus is that the _SPLIT version can have multiple new fields, while the non-SPLIT version can have multiple old fields.
2. RH_KABI_REPLACE currently does not generate an anonymous struct around the new field, this preserves that behavior and does not require changes to kabidw.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -261,7 +261,21 @@ * Macro for breaking up a random element into two smaller chunks using an * anonymous struct inside an anonymous union. */ -# define RH_KABI_REPLACE2(orig, _new1, _new2) RH_KABI_REPLACE(orig, struct{ _new1; _new2;}) +#define _RH_KABI_REPLACE1(_new) _new; +#define _RH_KABI_REPLACE2(_new, ...) _new; _RH_KABI_REPLACE1(__VA_ARGS__) +#define _RH_KABI_REPLACE3(_new, ...) _new; _RH_KABI_REPLACE2(__VA_ARGS__) +#define _RH_KABI_REPLACE4(_new, ...) _new; _RH_KABI_REPLACE3(__VA_ARGS__) +#define _RH_KABI_REPLACE5(_new, ...) _new; _RH_KABI_REPLACE4(__VA_ARGS__) +#define _RH_KABI_REPLACE6(_new, ...) _new; _RH_KABI_REPLACE5(__VA_ARGS__) +#define _RH_KABI_REPLACE7(_new, ...) _new; _RH_KABI_REPLACE6(__VA_ARGS__) +#define _RH_KABI_REPLACE8(_new, ...) _new; _RH_KABI_REPLACE7(__VA_ARGS__) +#define _RH_KABI_REPLACE9(_new, ...) _new; _RH_KABI_REPLACE8(__VA_ARGS__) +#define _RH_KABI_REPLACE10(_new, ...) _new; _RH_KABI_REPLACE9(__VA_ARGS__) +#define _RH_KABI_REPLACE11(_new, ...) _new; _RH_KABI_REPLACE10(__VA_ARGS__) +#define _RH_KABI_REPLACE12(_new, ...) _new; _RH_KABI_REPLACE11(__VA_ARGS__) + +#define RH_KABI_REPLACE_SPLIT(_orig, ...) _RH_KABI_REPLACE(_orig, \ + struct { __PASTE(_RH_KABI_REPLACE, COUNT_ARGS(__VA_ARGS__))(__VA_ARGS__) });
# define RH_KABI_RESERVE(n) _RH_KABI_RESERVE(n); /*
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: rename RH_KABI_USE2 to RH_KABI_USE_SPLIT
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit f46fa6e690b97a7088f40f1a8add998b40e39026 Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:06 -0400
Similarly to RH_KABI_REPLACE2 being renamed to RH_KABI_REPLACE and made more generic, do the same with RH_KABI_USE2.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -286,7 +286,7 @@ * Macros for breaking up a reserved element into two smaller chunks using * an anonymous struct inside an anonymous union. */ -# define RH_KABI_USE2(n, _new1, _new2) RH_KABI_REPLACE(_RH_KABI_RESERVE(n), struct{ _new1; _new2; }) +# define RH_KABI_USE_SPLIT(n, ...) RH_KABI_REPLACE_SPLIT(_RH_KABI_RESERVE(n), __VA_ARGS__)
/* * We tried to standardize on Red Hat reserved names. These wrappers
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: make RH_KABI_USE replace any number of reserved fields
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit df9c99ec7a23f3333b36870549987f826b12a01f Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:07 -0400
Example usage:
struct foo { int a; RH_KABI_USE(1, int b) RH_KABI_USE(2, 3, int c[3]) RH_KABI_USE(4, 5, 6, 7, 8, 9, 10, long d[7]) RH_KABI_RESERVE(11) };
Documentation will be updated in a later patch.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -281,7 +281,22 @@ /* * Simple wrappers to replace standard Red Hat reserved elements. */ -# define RH_KABI_USE(n, _new) RH_KABI_REPLACE(_RH_KABI_RESERVE(n), _new) +#define _RH_KABI_USE1(n, _new) _RH_KABI_RESERVE(n), _new +#define _RH_KABI_USE2(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE1(__VA_ARGS__) +#define _RH_KABI_USE3(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE2(__VA_ARGS__) +#define _RH_KABI_USE4(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE3(__VA_ARGS__) +#define _RH_KABI_USE5(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE4(__VA_ARGS__) +#define _RH_KABI_USE6(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE5(__VA_ARGS__) +#define _RH_KABI_USE7(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE6(__VA_ARGS__) +#define _RH_KABI_USE8(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE7(__VA_ARGS__) +#define _RH_KABI_USE9(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE8(__VA_ARGS__) +#define _RH_KABI_USE10(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE9(__VA_ARGS__) +#define _RH_KABI_USE11(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE10(__VA_ARGS__) +#define _RH_KABI_USE12(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE11(__VA_ARGS__) + +#define _RH_KABI_USE(...) _RH_KABI_REPLACE(__VA_ARGS__) +#define RH_KABI_USE(n, ...) _RH_KABI_USE(__PASTE(_RH_KABI_USE, COUNT_ARGS(__VA_ARGS__))(n, __VA_ARGS__)); + /* * Macros for breaking up a reserved element into two smaller chunks using * an anonymous struct inside an anonymous union.
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: expand and clarify documentation
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit d818ac8b111773fd3230ebc6ab602889f93af418 Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:09 -0400
Rewrite the comments throughout the file and move them to the beginning in the form of user documentation. Document the missing pieces.
The RH_KABI_SIZE_AND_EXTEND macros will be unified to this format later in the patch set.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -51,15 +51,23 @@ * party modules is retained. * * RH_KABI_DEPRECATE - * Mark the element as deprecated and make it unusable by modules while - * preserving kABI checksums. + * Marks the element as deprecated and make it unusable by modules while + * keeping a hole in its place to preserve binary compatibility. * * RH_KABI_DEPRECATE_FN - * Mark the function pointer as deprecated and make it unusable by modules - * while preserving kABI checksums. + * Marks the function pointer as deprecated and make it unusable by modules + * while keeping a hole in its place to preserve binary compatibility. * * RH_KABI_EXTEND - * Simple macro for adding a new element to a struct. + * Adds a new field to a struct. This must always be added to the end of + * the struct. Before using this macro, make sure this is actually safe + * to do - there is a number of conditions under which it is *not* safe. + * In particular (but not limited to), this macro cannot be used: + * - if the struct in question is embedded in another struct, or + * - if the struct is allocated by drivers either statically or + * dynamically, or + * - if the struct is allocated together with driver data (an example of + * such behavior is struct net_device or struct request). * * RH_KABI_EXTEND_WITH_SIZE * Adds a new element (usually a struct) to a struct and reserves extra @@ -75,25 +83,26 @@ * guarantee. * * RH_KABI_FILL_HOLE - * Simple macro for filling a hole in a struct. + * Fills a hole in a struct. * * Warning: only use if a hole exists for _all_ arches. Use pahole to verify. * * RH_KABI_RENAME - * Simple macro for renaming an element without changing its type. This - * macro can be used in bitfields, for example. + * Renames an element without changing its type. This macro can be used in + * bitfields, for example. * * NOTE: this macro does not add the final ';' * * RH_KABI_REPLACE - * Simple replacement of _orig with a union of _orig and _new. + * Replaces the _orig field by the _new field. The size of the occupied + * space is preserved, it's fine if the _new field is smaller than the + * _orig field. If a _new field is larger or has a different alignment, + * compilation will abort. * - * The RH_KABI_REPLACE* macros attempt to add the ability to use the '_new' - * element while preserving size alignment with the '_orig' element. - * - * The #ifdef __GENKSYMS__ preserves the kABI agreement, while the anonymous - * union structure preserves the size alignment (assuming the '_new' element - * is not bigger than the '_orig' element). + * RH_KABI_REPLACE_SPLIT + * Works the same as RH_KABI_REPLACE but replaces a single _orig field by + * multiple new fields. The checks for size and alignment done by + * RH_KABI_REPLACE are still applied. * * RH_KABI_HIDE_INCLUDE * Hides the given include file from kABI checksum computations. This is @@ -112,6 +121,45 @@ * Example usage: * #include RH_KABI_FAKE_INCLUDE(<linux/rhashtable.h>) * + * RH_KABI_RESERVE + * Adds a reserved field to a struct. This is done prior to kABI freeze + * for structs that cannot be expanded later using RH_KABI_EXTEND (for + * example because they are embedded in another struct or because they are + * allocated by drivers or because they use unusual memory layout). The + * size of the reserved field is 'unsigned long' and is assumed to be + * 8 bytes. + * + * The argument is a number unique for the given struct; usually, multiple + * RH_KABI_RESERVE macros are added to a struct with numbers starting from + * one. + * + * Example usage: + * struct foo { + * int a; + * RH_KABI_RESERVE(1) + * RH_KABI_RESERVE(2) + * RH_KABI_RESERVE(3) + * RH_KABI_RESERVE(4) + * }; + * + * RH_KABI_USE + * Uses a previously reserved field or multiple fields. The arguments are + * one or more numbers assigned to RH_KABI_RESERVE, followed by a field to + * be put in their place. The compiler ensures that the new field is not + * larger than the reserved area. + * + * Example usage: + * struct foo { + * int a; + * RH_KABI_USE(1, int b) + * RH_KABI_USE(2, 3, int c[3]) + * RH_KABI_RESERVE(4) + * }; + * + * RH_KABI_USE_SPLIT + * Works the same as RH_KABI_USE but replaces a single reserved field by + * multiple new fields. + * * RH_KABI_FORCE_CHANGE * Force change of the symbol checksum. The argument of the macro is a * version for cases we need to do this more than once. @@ -252,15 +300,11 @@
#endif /* __GENKSYMS__ */
-/* semicolon added wrappers for the RH_KABI_REPLACE macros */ # define RH_KABI_DEPRECATE(_type, _orig) _RH_KABI_DEPRECATE(_type, _orig); # define RH_KABI_DEPRECATE_FN(_type, _orig, _args...) \ _RH_KABI_DEPRECATE_FN(_type, _orig, _args); # define RH_KABI_REPLACE(_orig, _new) _RH_KABI_REPLACE(_orig, _new); -/* - * Macro for breaking up a random element into two smaller chunks using an - * anonymous struct inside an anonymous union. - */ + #define _RH_KABI_REPLACE1(_new) _new; #define _RH_KABI_REPLACE2(_new, ...) _new; _RH_KABI_REPLACE1(__VA_ARGS__) #define _RH_KABI_REPLACE3(_new, ...) _new; _RH_KABI_REPLACE2(__VA_ARGS__) @@ -278,9 +322,7 @@ struct { __PASTE(_RH_KABI_REPLACE, COUNT_ARGS(__VA_ARGS__))(__VA_ARGS__) });
# define RH_KABI_RESERVE(n) _RH_KABI_RESERVE(n); -/* - * Simple wrappers to replace standard Red Hat reserved elements. - */ + #define _RH_KABI_USE1(n, _new) _RH_KABI_RESERVE(n), _new #define _RH_KABI_USE2(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE1(__VA_ARGS__) #define _RH_KABI_USE3(n, ...) _RH_KABI_RESERVE(n); _RH_KABI_USE2(__VA_ARGS__) @@ -297,24 +339,12 @@ #define _RH_KABI_USE(...) _RH_KABI_REPLACE(__VA_ARGS__) #define RH_KABI_USE(n, ...) _RH_KABI_USE(__PASTE(_RH_KABI_USE, COUNT_ARGS(__VA_ARGS__))(n, __VA_ARGS__));
-/* - * Macros for breaking up a reserved element into two smaller chunks using - * an anonymous struct inside an anonymous union. - */ # define RH_KABI_USE_SPLIT(n, ...) RH_KABI_REPLACE_SPLIT(_RH_KABI_RESERVE(n), __VA_ARGS__)
-/* - * We tried to standardize on Red Hat reserved names. These wrappers - * leverage those common names making it easier to read and find in the - * code. - */ # define _RH_KABI_RESERVE(n) unsigned long rh_reserved##n
#define RH_KABI_EXCLUDE(_elem) _RH_KABI_EXCLUDE(_elem);
-/* - * Extending a struct while reserving extra space. - */ #define RH_KABI_EXTEND_WITH_SIZE(_new, _size) \ RH_KABI_EXTEND(union { \ _new; \
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: fix RH_KABI_SET_SIZE macro
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit ce96bb000b3a603533f885485bd875eb7dfbfff2 Author: Jiri Benc jbenc@redhat.com Author: Ivan Vecera ivecera@redhat.com Date: Wed, 1 Apr 2020 13:04:10 -0400
The current implementation of RH_KABI_SET_SIZE() macro does not allow to pass certain expressions as an argument.
E.g. RH_KABI_SET_SIZE(&cq->napi, napi_struct_extended) is expanded to:
&cq->napi->napi_struct_extended_size_rh = sizeof(struct ...)
and this is not correct and should be:
(&cq->napi)->napi_struct_extended_size_rh = sizeof(struct ...)
The patch fixes the macro this way.
RH-Signed-off-by: Ivan Vecera ivecera@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -398,7 +398,7 @@ * a semicolon is necessary at the end of the line where it is invoked. */ #define RH_KABI_SET_SIZE(_name, _struct) ({ \ - _name->_struct##_size_rh = sizeof(struct _struct##_rh); \ + (_name)->_struct##_size_rh = sizeof(struct _struct##_rh); \ })
/*
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: fix dereference in RH_KABI_CHECK_EXT
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 975873f60708e90b224998160bf23de27b8b3bec Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:11 -0400
Similarly to the previous patch, there are parentheses needed aroung the _ptr argument in RH_KABI_CHECK_EXT.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -419,7 +419,7 @@ */ #define RH_KABI_CHECK_EXT(_ptr, _struct, _field) ({ \ size_t __off = offsetof(struct _struct##_rh, _field); \ - _ptr->_struct##_size_rh > __off ? true : false; \ + (_ptr)->_struct##_size_rh > __off ? true : false; \ })
#endif /* _LINUX_RH_KABI_H */
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: use fixed field name for extended part
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 620b222e839dc20ce33b86ed7657903335cfbad1 Author: Jiri Benc jbenc@redhat.com Author: Ivan Vecera ivecera@redhat.com Date: Wed, 1 Apr 2020 13:04:12 -0400
The current RH_KABI_SIZE_AND_EXTEND* macros uses passed structure name as a prefix for the field used for access to the extended area.
Example:
struct napi_struct_extend { int ex_field; }; struct napi_struct { ... RH_KABI_SIZE_AND_EXTEND(napi_struct_extend) };
Unfortunately the generated field name is very long and when you need to access any field in extended part of napi_struct you need to use this horrible construct:
napi->napi_struct_extend.ex_field;
As RH_KABI_SIZE_AND_EXTEND* should not be used more than once in a structure we can use a short fixed name to access an extended area. The patch modifies the affected macros so '._rh' is used as a name for this field so the field from the previous example will be referenced as:
napi->_rh.ex_field;
RH-Signed-off-by: Ivan Vecera ivecera@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -378,13 +378,13 @@ */ #define _RH_KABI_SIZE_AND_EXTEND_PTR(_struct) \ size_t _struct##_size_rh; \ - RH_KABI_EXCLUDE(struct _struct##_rh *_struct##_rh) + RH_KABI_EXCLUDE(struct _struct##_rh *_rh) #define RH_KABI_SIZE_AND_EXTEND_PTR(_struct) \ _RH_KABI_SIZE_AND_EXTEND_PTR(_struct)
#define _RH_KABI_SIZE_AND_EXTEND(_struct) \ size_t _struct##_size_rh; \ - RH_KABI_EXCLUDE(struct _struct##_rh _struct##_rh) + RH_KABI_EXCLUDE(struct _struct##_rh _rh) #define RH_KABI_SIZE_AND_EXTEND(_struct) \ _RH_KABI_SIZE_AND_EXTEND(_struct)
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: more consistent _RH_KABI_SIZE_AND_EXTEND
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit df58e09e5bb20bcaf1670733f7d40f92ed4f2bce Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:13 -0400
The convention in rh_kabi.h is that the underscored versions of macros do not add the trailing semicolon, while the normal versions do.
This is not the case for _RH_KABI_SIZE_AND_EXTEND[_PTR], which add the semicolon. Those macros were introduced by commit 531826346544 ("redhat: rh_kabi: Indirect EXTEND macros so nesting of other macros will resolve.") for a different reason but since we have them now, we might as well make them consistent.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -378,15 +378,15 @@ */ #define _RH_KABI_SIZE_AND_EXTEND_PTR(_struct) \ size_t _struct##_size_rh; \ - RH_KABI_EXCLUDE(struct _struct##_rh *_rh) + _RH_KABI_EXCLUDE(struct _struct##_rh *_rh) #define RH_KABI_SIZE_AND_EXTEND_PTR(_struct) \ - _RH_KABI_SIZE_AND_EXTEND_PTR(_struct) + _RH_KABI_SIZE_AND_EXTEND_PTR(_struct);
#define _RH_KABI_SIZE_AND_EXTEND(_struct) \ size_t _struct##_size_rh; \ - RH_KABI_EXCLUDE(struct _struct##_rh _rh) + _RH_KABI_EXCLUDE(struct _struct##_rh _rh) #define RH_KABI_SIZE_AND_EXTEND(_struct) \ - _RH_KABI_SIZE_AND_EXTEND(_struct) + _RH_KABI_SIZE_AND_EXTEND(_struct);
/* * RH_KABI_SET_SIZE calculates and sets the size of the extended struct and
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: rename RH_KABI_SIZE_AND_EXTEND to AUX
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit a0d01aefc5e6959a2c3fa0d35e87f3e6ea7dde0e Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:14 -0400
The current RH_KABI_SIZE_AND_EXTEND and RH_KABI_SIZE_AND_EXTEND_PTR names have a few problems: they are similar to RH_KABI_EXTEND_WITH_SIZE, they are too long and they focuses on the implementation instead of the use.
Since the parallely allocated structures in some subsystems are already called "auxiliary structures", adopt that name. The macro RH_KABI_SIZE_AND_EXTEND_PTR is thus renamed to RH_KABI_AUX_PTR.
The macro RH_KABI_SIZE_AND_EXTEND is renamed to RH_KABI_AUX_EMBED to emphasize that the aux structure is embedded in the main structure. This frees up the RH_KABI_AUX name, which is used as a replacement for RH_KABI_CHECK_EXT.
I realize that the name of the RH_KABI_AUX macro is not descriptive. However, this is going to be heavily used macro as any access to a field in an aux struct needs to be guarded by a condition using this macro. Its name thus should be as short as possible; we can't get shorter than RH_KABI_AUX.
Lastly, the RH_KABI_SET_SIZE and RH_KABI_INIT_SIZE macros got a new _AUX_ infix to associate them with the other AUX macros. It makes them a bit longer but those are used only once for each struct, so it should be acceptable.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -372,52 +372,52 @@ */
/* - * RH_KABI_SIZE_AND_EXTEND|_PTR() extends a struct by embedding or adding + * RH_KABI_AUX_EMBED|_PTR() extends a struct by embedding or adding * a pointer in a base struct. The name of the new struct is the name * of the base struct appended with _rh. */ -#define _RH_KABI_SIZE_AND_EXTEND_PTR(_struct) \ +#define _RH_KABI_AUX_PTR(_struct) \ size_t _struct##_size_rh; \ _RH_KABI_EXCLUDE(struct _struct##_rh *_rh) -#define RH_KABI_SIZE_AND_EXTEND_PTR(_struct) \ - _RH_KABI_SIZE_AND_EXTEND_PTR(_struct); +#define RH_KABI_AUX_PTR(_struct) \ + _RH_KABI_AUX_PTR(_struct);
-#define _RH_KABI_SIZE_AND_EXTEND(_struct) \ +#define _RH_KABI_AUX_EMBED(_struct) \ size_t _struct##_size_rh; \ _RH_KABI_EXCLUDE(struct _struct##_rh _rh) -#define RH_KABI_SIZE_AND_EXTEND(_struct) \ - _RH_KABI_SIZE_AND_EXTEND(_struct); +#define RH_KABI_AUX_EMBED(_struct) \ + _RH_KABI_AUX_EMBED(_struct);
/* - * RH_KABI_SET_SIZE calculates and sets the size of the extended struct and + * RH_KABI_AUX_SET_SIZE calculates and sets the size of the extended struct and * stores it in the size_rh field for structs that are dynamically allocated. * This macro MUST be called when expanding a base struct with - * RH_KABI_SIZE_AND_EXTEND, and it MUST be called from the allocation site + * RH_KABI_AUX, and it MUST be called from the allocation site * regardless of being allocated in the kernel or a module. * Note: since this macro is intended to be invoked outside of a struct, * a semicolon is necessary at the end of the line where it is invoked. */ -#define RH_KABI_SET_SIZE(_name, _struct) ({ \ +#define RH_KABI_AUX_SET_SIZE(_name, _struct) ({ \ (_name)->_struct##_size_rh = sizeof(struct _struct##_rh); \ })
/* - * RH_KABI_INIT_SIZE calculates and sets the size of the extended struct and + * RH_KABI_AUX_INIT_SIZE calculates and sets the size of the extended struct and * stores it in the size_rh field for structs that are statically allocated. * This macro MUST be called when expanding a base struct with - * RH_KABI_SIZE_AND_EXTEND, and it MUST be called from the declaration site + * RH_KABI_AUX, and it MUST be called from the declaration site * regardless of being allocated in the kernel or a module. */ -#define RH_KABI_INIT_SIZE(_struct) \ +#define RH_KABI_AUX_INIT_SIZE(_struct) \ ._struct##_size_rh = sizeof(struct _struct##_rh),
/* - * RH_KABI_CHECK_EXT verifies allocated memory exists. This MUST be called to + * RH_KABI_AUX verifies allocated memory exists. This MUST be called to * verify that memory in the _rh struct is valid, and can be called - * regardless if RH_KABI_SIZE_AND_EXTEND or RH_KABI_SIZE_AND_EXTEND_PTR is + * regardless if RH_KABI_AUX_EMBED or RH_KABI_AUX_PTR is * used. */ -#define RH_KABI_CHECK_EXT(_ptr, _struct, _field) ({ \ +#define RH_KABI_AUX(_ptr, _struct, _field) ({ \ size_t __off = offsetof(struct _struct##_rh, _field); \ (_ptr)->_struct##_size_rh > __off ? true : false; \ })
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: introduce RH_KABI_USE_AUX_PTR
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 194de3042cda2e21a14b504965b4c463b47de73c Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:15 -0400
It's hard to predict the number of changes required in a struct. We do our best by reserving fields by RH_KABI_RESERVE but sometimes they run out. If that's going to happen, the last two reserved fields can be changed into an aux struct mechanism. Introduce a macro that does that.
Example: there's this struct:
struct foo { ... RH_KABI_USE(1, int a) RH_KABI_USE(2, int b) RH_KABI_RESERVE(3) RH_KABI_RESERVE(4) };
and a need to add field 'int c', while we expect further additions. It can be now done in this way:
struct foo_rh { int c; };
struct foo { ... RH_KABI_USE(1, int a) RH_KABI_USE(2, int b) RH_KABI_USE_AUX_PTR(3, 4, foo) };
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -388,6 +388,15 @@ #define RH_KABI_AUX_EMBED(_struct) \ _RH_KABI_AUX_EMBED(_struct);
+/* + * If there is a post-kABI freeze need of RH_KABI_AUX_PTR and there are + * still two reserved fields available, they can be converted by + * RH_KABI_USE_AUX_PTR. + */ +#define RH_KABI_USE_AUX_PTR(n1, n2, _struct) \ + RH_KABI_USE(n1, n2, \ + struct { RH_KABI_AUX_PTR(_struct) }) + /* * RH_KABI_AUX_SET_SIZE calculates and sets the size of the extended struct and * stores it in the size_rh field for structs that are dynamically allocated.
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: expand and clarify documentation of aux structs
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 7de1d9a6dbfbc631a7b051ccd2f69a2715ce15a9 Author: Jiri Benc jbenc@redhat.com Date: Wed, 1 Apr 2020 13:04:16 -0400
Rewrite the comments about aux structs throughout the file and move them to the beginning in the form of user documentation.
RH-Signed-off-by: Jiri Benc jbenc@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -160,6 +160,119 @@ * Works the same as RH_KABI_USE but replaces a single reserved field by * multiple new fields. * + * RH_KABI_AUX_EMBED + * RH_KABI_AUX_PTR + * Adds an extenstion of a struct in the form of "auxiliary structure". + * This is done prior to kABI freeze for structs that cannot be expanded + * later using RH_KABI_EXTEND. See also RH_KABI_RESERVED, these two + * approaches can (and often are) combined. + * + * To use this for 'struct foo' (the "base structure"), define a new + * structure called 'struct foo_rh'; this new struct is called "auxiliary + * structure". Then add RH_KABI_AUX_EMBED or RH_KABI_AUX_PTR to the end + * of the base structure. The argument is the name of the base structure, + * without the 'struct' keyword. + * + * RH_KABI_AUX_PTR stores a pointer to the aux structure in the base + * struct. The lifecycle of the aux struct needs to be properly taken + * care of. + * + * RH_KABI_AUX_EMBED embeds the aux struct into the base struct. This + * cannot be used when the base struct is itself embedded into another + * struct, allocated in an array, etc. + * + * Both approaches (ptr and embed) work correctly even when the aux struct + * is allocated by modules. To ensure this, the code responsible for + * allocation/assignment of the aux struct has to properly set the size of + * the aux struct; see the RH_KABI_AUX_SET_SIZE and RH_KABI_AUX_INIT_SIZE + * macros. + * + * New fields can be later added to the auxiliary structure, always to its + * end. Note the auxiliary structure cannot be shrunk in size later (i.e., + * fields cannot be removed, only deprecated). Any code accessing fields + * from the aux struct must guard the access using the RH_KABI_AUX macro. + * The access itself is then done via a '_rh' field in the base struct. + * + * The auxiliary structure is not guaranteed for access by modules unless + * explicitly commented as such in the declaration of the aux struct + * itself or some of its elements. + * + * Example: + * + * struct foo_rh { + * int newly_added; + * }; + * + * struct foo { + * bool big_hammer; + * RH_KABI_AUX_PTR(foo) + * }; + * + * void use(struct foo *f) + * { + * if (RH_KABI_AUX(f, foo, newly_added)) + * f->_rh->newly_added = 123; + * else + * // the field 'newly_added' is not present in the passed + * // struct, fall back to old behavior + * f->big_hammer = true; + * } + * + * static struct foo_rh my_foo_rh { + * .newly_added = 0; + * } + * + * static struct foo my_foo = { + * .big_hammer = false, + * ._rh = &my_foo_rh, + * RH_KABI_AUX_INIT_SIZE(foo) + * }; + * + * RH_KABI_USE_AUX_PTR + * Creates an auxiliary structure post kABI freeze. This works by using + * two reserved fields (thus there has to be two reserved fields still + * available) and converting them to RH_KABI_AUX_PTR. + * + * Example: + * + * struct foo_rh { + * }; + * + * struct foo { + * int a; + * RH_KABI_RESERVE(1) + * RH_KABI_USE_AUX_PTR(2, 3, foo) + * }; + * + * RH_KABI_AUX_SET_SIZE + * RH_KABI_AUX_INIT_SIZE + * Calculates and stores the size of the auxiliary structure. + * + * RH_KABI_AUX_SET_SIZE is for dynamically allocated base structs, + * RH_KABI_AUX_INIT_SIZE is for statically allocated case structs. + * + * These macros must be called from the allocation (RH_KABI_AUX_SET_SIZE) + * or declaration (RH_KABI_AUX_INIT_SIZE) site, regardless of whether + * that happens in the kernel or in a module. Without calling one of + * these macros, the aux struct will appear to have no fields to the + * kernel. + * + * Note: since RH_KABI_AUX_SET_SIZE is intended to be invoked outside of + * a struct definition, it does not add the semicolon and must be + * terminated by semicolon by the caller. + * + * RH_KABI_AUX + * Verifies that the given field exists in the given auxiliary structure. + * This MUST be called prior to accessing that field; failing to do that + * may lead to invalid memory access. + * + * The first argument is a pointer to the base struct, the second argument + * is the name of the base struct (without the 'struct' keyword), the + * third argument is the field name. + * + * This macro works for structs extended by either of RH_KABI_AUX_EMBED, + * RH_KABI_AUX_PTR and RH_KABI_USE_AUX_PTR. + * * RH_KABI_FORCE_CHANGE * Force change of the symbol checksum. The argument of the macro is a * version for cases we need to do this more than once. @@ -352,30 +465,6 @@ __RH_KABI_CHECK_SIZE(_new, 8 * (_size)); \ })
-/* - * RHEL macros to extend structs. - * - * base struct: The struct being extended. For example, pci_dev. - * extended struct: The Red Hat struct being added to the base struct. - * For example, pci_dev_rh. - * - * These macros should be used to extend structs before KABI freeze. - * They can be used post-KABI freeze in the limited case of the base - * struct not being embedded in another struct. - * - * Extended structs cannot be shrunk in size as changes will break - * the size & offset comparison. - * - * Extended struct elements are not guaranteed for access by modules unless - * explicitly commented as such in the declaration of the extended struct or - * the element in the extended struct. - */ - -/* - * RH_KABI_AUX_EMBED|_PTR() extends a struct by embedding or adding - * a pointer in a base struct. The name of the new struct is the name - * of the base struct appended with _rh. - */ #define _RH_KABI_AUX_PTR(_struct) \ size_t _struct##_size_rh; \ _RH_KABI_EXCLUDE(struct _struct##_rh *_rh) @@ -388,44 +477,17 @@ #define RH_KABI_AUX_EMBED(_struct) \ _RH_KABI_AUX_EMBED(_struct);
-/* - * If there is a post-kABI freeze need of RH_KABI_AUX_PTR and there are - * still two reserved fields available, they can be converted by - * RH_KABI_USE_AUX_PTR. - */ #define RH_KABI_USE_AUX_PTR(n1, n2, _struct) \ RH_KABI_USE(n1, n2, \ struct { RH_KABI_AUX_PTR(_struct) })
-/* - * RH_KABI_AUX_SET_SIZE calculates and sets the size of the extended struct and - * stores it in the size_rh field for structs that are dynamically allocated. - * This macro MUST be called when expanding a base struct with - * RH_KABI_AUX, and it MUST be called from the allocation site - * regardless of being allocated in the kernel or a module. - * Note: since this macro is intended to be invoked outside of a struct, - * a semicolon is necessary at the end of the line where it is invoked. - */ #define RH_KABI_AUX_SET_SIZE(_name, _struct) ({ \ (_name)->_struct##_size_rh = sizeof(struct _struct##_rh); \ })
-/* - * RH_KABI_AUX_INIT_SIZE calculates and sets the size of the extended struct and - * stores it in the size_rh field for structs that are statically allocated. - * This macro MUST be called when expanding a base struct with - * RH_KABI_AUX, and it MUST be called from the declaration site - * regardless of being allocated in the kernel or a module. - */ #define RH_KABI_AUX_INIT_SIZE(_struct) \ ._struct##_size_rh = sizeof(struct _struct##_rh),
-/* - * RH_KABI_AUX verifies allocated memory exists. This MUST be called to - * verify that memory in the _rh struct is valid, and can be called - * regardless if RH_KABI_AUX_EMBED or RH_KABI_AUX_PTR is - * used. - */ #define RH_KABI_AUX(_ptr, _struct, _field) ({ \ size_t __off = offsetof(struct _struct##_rh, _field); \ (_ptr)->_struct##_size_rh > __off ? true : false; \
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Čestmír Kalina ckalina@redhat.com
kabi: Add kABI macros for enum type
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2024595 Upstream Status: RHEL only
commit 258dac2f73c852bc4f3b401a58228a1333e2b002 Author: Waiman Long longman@redhat.com Date: Wed, 16 Dec 2020 00:14:58 -0500
Currently, there is no kABI macro to safely handle the addition and removal of enum fields in an enum type. Add the following macros to do that: - RH_KABI_BROKEN_INSERT_ENUM() - RH_KABI_BROKEN_REMOVE_ENUM() - RH_KABI_EXTEND_ENUM()
RH-Signed-off-by: Waiman Long longman@redhat.com
Signed-off-by: Čestmír Kalina ckalina@redhat.com Signed-off-by: Prarit Bhargava prarit@redhat.com
diff --git a/include/linux/rh_kabi.h b/include/linux/rh_kabi.h index blahblah..blahblah 100644 --- a/include/linux/rh_kabi.h +++ b/include/linux/rh_kabi.h @@ -334,6 +334,20 @@ * Replace a field by a different one without doing any checking. This * allows replacing a field by another with a different size. Similarly * to other RH_KABI_BROKEN macros, use of this indicates a kABI breakage. + * + * RH_KABI_BROKEN_INSERT_ENUM + * RH_KABI_BROKEN_REMOVE_ENUM + * Insert a field to the middle of an enumaration type / delete a field from + * an enumaration type. Note that this can break kABI especially if the + * number of enum fields is used in an array within a structure. It can be + * done only when it is certain that no 3rd party driver will use the + * enumeration type or a structure that embeds an array with size determined + * by an enumeration type. + * + * RH_KABI_EXTEND_ENUM + * Adds a new field to an enumeration type. This must always be added to + * the end of the enum. Before using this macro, make sure this is actually + * safe to do. */
#undef linux @@ -354,6 +368,9 @@ # define RH_KABI_BROKEN_INSERT_BLOCK(_new) # define RH_KABI_BROKEN_REMOVE_BLOCK(_orig) _orig # define RH_KABI_BROKEN_REPLACE(_orig, _new) _orig; +# define RH_KABI_BROKEN_INSERT_ENUM(_new) +# define RH_KABI_BROKEN_REMOVE_ENUM(_orig) _orig, +# define RH_KABI_EXTEND_ENUM(_new)
# define _RH_KABI_DEPRECATE(_type, _orig) _type _orig # define _RH_KABI_DEPRECATE_FN(_type, _orig, _args...) _type (*_orig)(_args) @@ -377,7 +394,9 @@ # define RH_KABI_BROKEN_INSERT_BLOCK(_new) _new # define RH_KABI_BROKEN_REMOVE_BLOCK(_orig) # define RH_KABI_BROKEN_REPLACE(_orig, _new) _new; - +# define RH_KABI_BROKEN_INSERT_ENUM(_new) _new, +# define RH_KABI_BROKEN_REMOVE_ENUM(_orig) +# define RH_KABI_EXTEND_ENUM(_new) _new,
#if IS_BUILTIN(CONFIG_RH_KABI_SIZE_ALIGN_CHECKS) # define __RH_KABI_CHECK_SIZE_ALIGN(_orig, _new) \
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530
From: Prarit Bhargava on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530#note_8293378...
@jwilsonrh is this okay now?
From: Jarod Wilson on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1530#note_8297158...
Yeah, all good now, thanks much.
kernel@lists.fedoraproject.org