代码拉取完成,页面将自动刷新
维护 KABI 的兼容性是 openEuler kernel 的一项重要工作,为方便 KABI 结构预留与 KABI 接口兼容性适配,参考 RHEL "include/linux/rh_kabi.h", 引入常用的宏。
/* SPDX-License-Identifier: GPL-2.0 */
/*
* kabi.h - openEuler kABI abstraction header
*
* 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
* Copyright (c) 2021 Xie XiuQi <xiexiuqi@huawei.com>
*
* This file is released under the GPLv2.
* See the file COPYING for more details.
*
* These kabi macros hide the changes from the kabi checker and from the
* process that computes the exported symbols' checksums.
* They have 2 variants: one (defined under __GENKSYMS__) used when
* generating the checksums, and the other used when building the kernel's
* binaries.
*
* The use of these macros does not guarantee that the usage and modification
* of code is correct. As with all openEuler only changes, an engineer must
* explain why the use of the macro is valid in the patch containing the
* changes.
*
* The macro helpers are derived from Red Hat "include/linux/rh_kabi.h"
* Mostly debrand from RHEL.
*/
#ifndef _LINUX_KABI_H
#define _LINUX_KABI_H
#include <linux/compiler.h>
#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 KABI_EXTEND, but applied to
* most macros for uniformity).
*
* KABI_CONST
* Adds a new const modifier to a function parameter preserving the old
* checksum.
*
* 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.
*
* KABI_DEPRECATE
* Marks the element as deprecated and make it unusable by modules while
* keeping a hole in its place to preserve binary compatibility.
*
* # define RH_KABI_BROKEN_INSERT_ENUM(_new) _new,
* # define RH_KABI_BROKEN_REMOVE_ENUM(_orig)
* KABI_DEPRECATE_FN
* Marks the function pointer as deprecated and make it unusable by modules
* while keeping a hole in its place to preserve binary compatibility.
*
* KABI_EXTEND
* 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).
*
* KABI_EXTEND_WITH_SIZE
* Adds a new element (usually a struct) to a struct and reserves extra
* space for the new element. The provided 'size' is the total space to
* be added in longs (i.e. it's 8 * 'size' bytes), including the size of
* the added element. It is automatically checked that the new element
* does not overflow the reserved space, now nor in the future. However,
* no attempt is done to check the content of the added element (struct)
* for kABI conformance - kABI checking inside the added element is
* effectively switched off.
* For any struct being added by KABI_EXTEND_WITH_SIZE, it is
* recommended its content to be documented as not covered by kABI
* guarantee.
*
* KABI_FILL_HOLE
* Fills a hole in a struct.
*
* Warning: only use if a hole exists for _all_ arches. Use pahole to verify.
*
* KABI_RENAME
* Renames an element without changing its type. This macro can be used in
* bitfields, for example.
*
* NOTE: does not include the final ';'
*
* KABI_REPLACE
* 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.
*
*
* 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 KABI_HIDE_INCLUDE(<linux/poll.h>)
*
* 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 KABI_FAKE_INCLUDE(<linux/rhashtable.h>)
*
* KABI_RESERVE
* Adds a reserved field to a struct. This is done prior to kABI freeze
* for structs that cannot be expanded later using 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
* KABI_RESERVE macros are added to a struct with numbers starting from
* one.
*
* Example usage:
* struct foo {
* int a;
* KABI_RESERVE(1)
* KABI_RESERVE(2)
* };
*
* KABI_USE
* Simple wrappers to replace standard openEuler reserved elements.
*
* KABI_AUX_EMBED
* 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 KABI_EXTEND. See also 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 KABI_AUX_EMBED or KABI_AUX_PTR to the end
* of the base structure. The argument is the name of the base structure,
* without the 'struct' keyword.
*
* 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.
*
* 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 KABI_AUX_SET_SIZE and 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 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;
* KABI_AUX_PTR(foo)
* };
*
* void use(struct foo *f)
* {
* if (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,
* KABI_AUX_INIT_SIZE(foo)
* };
*
* 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 KABI_AUX_PTR.
*
* Example:
*
* struct foo_rh {
* };
*
* struct foo {
* int a;
* KABI_RESERVE(1)
* KABI_USE_AUX_PTR(2, 3, foo)
* };
*
* KABI_AUX_SET_SIZE
* KABI_AUX_INIT_SIZE
* Calculates and stores the size of the auxiliary structure.
*
* KABI_AUX_SET_SIZE is for dynamically allocated base structs,
* KABI_AUX_INIT_SIZE is for statically allocated case structs.
*
* These macros must be called from the allocation (KABI_AUX_SET_SIZE)
* or declaration (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 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.
*
* 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 KABI_AUX_EMBED,
* KABI_AUX_PTR and KABI_USE_AUX_PTR.
*
* 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.
*
* This macro does the opposite: it changes the symbol checksum without
* actually changing anything about the exported symbol. It is useful for
* symbols that are not whitelisted, we're changing them in an
* incompatible way and want to prevent 3rd party modules to silently
* corrupt memory. Instead, by changing the symbol checksum, such modules
* won't be loaded by the kernel. This macro should only be used as a
* last resort when all other KABI workarounds have failed.
*
* KABI_EXCLUDE
* !!! WARNING: DANGEROUS, DO NOT USE unless you are aware of all the !!!
* !!! implications. This should be used ONLY EXCEPTIONALLY and only !!!
* !!! under specific circumstances. Very likely, this macro does not !!!
* !!! do what you expect it to do. Note that any usage of this macro !!!
* !!! MUST be paired with a KABI_FORCE_CHANGE annotation of !!!
* !!! a suitable symbol (or an equivalent safeguard) and the commit !!!
* !!! log MUST explain why the chosen solution is appropriate. !!!
*
* Exclude the element from checksum generation. Any such element is
* considered not to be part of the kABI whitelist and may be changed at
* will. Note however that it's the responsibility of the developer
* changing the element to ensure 3rd party drivers using this element
* won't panic, for example by not allowing them to be loaded. That can
* be achieved by changing another, non-whitelisted symbol they use,
* either by nature of the change or by using KABI_FORCE_CHANGE.
*
* Also note that any change to the element must preserve its size. Change
* of the size is not allowed and would constitute a silent kABI breakage.
* Beware that the KABI_EXCLUDE macro does not do any size checks.
*
* KABI_BROKEN_INSERT
* 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 KABI_EXCLUDE.
* In this case, the warning for KABI_EXCLUDE applies.
*
* A detailed explanation of correctness of every KABI_BROKEN_* macro
* use is especially important.
*
* KABI_BROKEN_INSERT_BLOCK
* KABI_BROKEN_REMOVE_BLOCK
* A version of 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 ';'.
*
* 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 KABI_BROKEN macros, use of this indicates a kABI breakage.
*
* KABI_BROKEN_INSERT_ENUM
* 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.
*
* 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.
*/
#ifdef __GENKSYMS__
# define KABI_CONST
# define KABI_ADD_MODIFIER(_new)
# define KABI_EXTEND(_new)
# define KABI_FILL_HOLE(_new)
# define KABI_FORCE_CHANGE(ver) __attribute__((kabi_change ## ver))
# define KABI_RENAME(_orig, _new) _orig
# define KABI_HIDE_INCLUDE(_file) <linux/kabi.h>
# define KABI_FAKE_INCLUDE(_file) _file
# define KABI_BROKEN_INSERT(_new)
# define KABI_BROKEN_REMOVE(_orig) _orig;
# define KABI_BROKEN_INSERT_BLOCK(_new)
# define KABI_BROKEN_REMOVE_BLOCK(_orig) _orig
# define KABI_BROKEN_REPLACE(_orig, _new) _orig;
# define KABI_BROKEN_INSERT_ENUM(_new)
# define KABI_BROKEN_REMOVE_ENUM(_orig) _orig,
# define KABI_EXTEND_ENUM(_new)
# define _KABI_DEPRECATE(_type, _orig) _type _orig
# define _KABI_DEPRECATE_FN(_type, _orig, _args...) _type (*_orig)(_args)
# define _KABI_REPLACE(_orig, _new) _orig
# define _KABI_EXCLUDE(_elem)
#else
# define KABI_ALIGN_WARNING ". Disable CONFIG_KABI_SIZE_ALIGN_CHECKS if debugging."
# define KABI_CONST const
# define KABI_ADD_MODIFIER(_new) _new
# define KABI_EXTEND(_new) _new;
# define KABI_FILL_HOLE(_new) _new;
# define KABI_FORCE_CHANGE(ver)
# define KABI_RENAME(_orig, _new) _new
# define KABI_HIDE_INCLUDE(_file) _file
# define KABI_FAKE_INCLUDE(_file) <linux/kabi.h>
# define KABI_BROKEN_INSERT(_new) _new;
# define KABI_BROKEN_REMOVE(_orig)
# define KABI_BROKEN_INSERT_BLOCK(_new) _new
# define KABI_BROKEN_REMOVE_BLOCK(_orig)
# define KABI_BROKEN_REPLACE(_orig, _new) _new;
# define KABI_BROKEN_INSERT_ENUM(_new) _new,
# define KABI_BROKEN_REMOVE_ENUM(_orig)
# define KABI_EXTEND_ENUM(_new) _new,
#if IS_BUILTIN(CONFIG_KABI_SIZE_ALIGN_CHECKS)
# define __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) KABI_ALIGN_WARNING); \
_Static_assert(__alignof__(struct{_new;}) <= __alignof__(struct{_orig;}), \
__FILE__ ":" __stringify(__LINE__) ": " __stringify(_orig) " is not aligned the same as " __stringify(_new) KABI_ALIGN_WARNING); \
}
# define __ABI_CHECK_SIZE(_item, _size) \
_Static_assert(sizeof(struct{_item;}) <= _size, \
__FILE__ ":" __stringify(__LINE__) ": " __stringify(_item) " is larger than the reserved size (" __stringify(_size) " bytes)" RH_KABI_ALIGN_WARNING)
#else
# define __KABI_CHECK_SIZE_ALIGN(_orig, _new)
# define __KABI_CHECK_SIZE(_item, _size)
#endif
# define _KABI_DEPRECATE(_type, _orig) _type kabi_reserved_##_orig
# define _KABI_DEPRECATE_FN(_type, _orig, _args...) \
_type (* kabi_reserved_##_orig)(_args)
# define _KABI_REPLACE(_orig, _new) \
union { \
_new; \
struct { \
_orig; \
} __UNIQUE_ID(kabi_hide); \
__KABI_CHECK_SIZE_ALIGN(_orig, _new); \
}
# define _KABI_EXCLUDE(_elem) _elem
#endif /* __GENKSYMS__ */
/* semicolon added wrappers for the KABI_REPLACE macros */
# define KABI_DEPRECATE(_type, _orig) _KABI_DEPRECATE(_type, _orig);
# define KABI_DEPRECATE_FN(_type, _orig, _args...) \
_KABI_DEPRECATE_FN(_type, _orig, _args);
# define KABI_REPLACE(_orig, _new) _KABI_REPLACE(_orig, _new);
/*
* Macro for breaking up a random element into two smaller chunks using an
* anonymous struct inside an anonymous union.
*/
# define KABI_REPLACE2(orig, _new1, _new2) KABI_REPLACE(orig, struct{ _new1; _new2;})
/*
* We tried to standardize on openEuler reserved names. These wrappers
* leverage those common names making it easier to read and find in the
* code.
*/
# define _KABI_RESERVE(n) unsigned long kabi_reserved##n
# define KABI_RESERVE(n) _KABI_RESERVE(n);
/*
* Simple wrappers to replace standard openEuler reserved elements.
*/
# define KABI_USE(n, _new) KABI_REPLACE(_KABI_RESERVE(n), _new)
/*
* Macros for breaking up a reserved element into two smaller chunks using
* an anonymous struct inside an anonymous union.
*/
# define KABI_USE2(n, _new1, _new2) KABI_REPLACE(_KABI_RESERVE(n), struct{ _new1; _new2; })
#define KABI_EXCLUDE(_elem) _KABI_EXCLUDE(_elem);
#define KABI_EXTEND_WITH_SIZE(_new, _size) \
KABI_EXTEND(union { \
_new; \
unsigned long KABI_UNIQUE_ID[_size]; \
__KABI_CHECK_SIZE(_new, 8 * (_size)); \
})
#define _KABI_AUX_PTR(_struct) \
size_t _struct##_size_rh; \
_KABI_EXCLUDE(struct _struct##_rh *_rh)
#define KABI_AUX_PTR(_struct) \
_KABI_AUX_PTR(_struct);
#define _KABI_AUX_EMBED(_struct) \
size_t _struct##_size_rh; \
_KABI_EXCLUDE(struct _struct##_rh _rh)
#define KABI_AUX_EMBED(_struct) \
_KABI_AUX_EMBED(_struct);
#define KABI_USE_AUX_PTR(n1, n2, _struct) \
KABI_USE(n1, n2, \
struct { KABI_AUX_PTR(_struct) })
/*
* 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
* KABI_SIZE_AND_EXTEND, 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 KABI_AUX_SET_SIZE(_name, _struct) ({ \
(_name)->_struct##_size_rh = sizeof(struct _struct##_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
* KABI_SIZE_AND_EXTEND, and it MUST be called from the declaration site
* regardless of being allocated in the kernel or a module.
*/
#define KABI_AUX_INIT_SIZE(_struct) \
._struct##_size_rh = sizeof(struct _struct##_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 KABI_SIZE_AND_EXTEND or KABI_SIZE_AND_EXTEND_PTR is
* used.
*/
#define KABI_AUX(_ptr, _struct, _field) ({ \
size_t __off = offsetof(struct _struct##_rh, _field); \
(_ptr)->_struct##_size_rh > __off ? true : false; \
})
#endif /* _LINUX_KABI_H */
Hi xiexiuqi, welcome to the openEuler Community.
I'm the Bot here serving you. You can find the instructions on how to interact with me at
https://gitee.com/openeuler/community/blob/master/en/sig-infrastructure/command.md.
If you have any questions, please contact the SIG: Kernel, and any of the maintainers: @Xie XiuQi, @YangYingliang, @成坚 (CHENG Jian).
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。
登录 后才可以发表评论