From: Čestmír Kalina <ckalina(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Author: Ivan Vecera <ivecera(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Author: Ivan Vecera <ivecera(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; 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(a)redhat.com&gt; Signed-off-by: Čestmír Kalina <ckalina(a)redhat.com&gt; Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt; 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