kabi.h

  1/* SPDX-License-Identifier: GPL-2.0 */
  2/*
  3 * Copyright (C) 2024 Google LLC
  4 *
  5 * Example macros for maintaining kABI stability.
  6 *
  7 * This file is based on android_kabi.h, which has the following notice:
  8 *
  9 * Heavily influenced by rh_kabi.h which came from the RHEL/CENTOS kernel
 10 * and was:
 11 *	Copyright (c) 2014 Don Zickus
 12 *	Copyright (c) 2015-2018 Jiri Benc
 13 *	Copyright (c) 2015 Sabrina Dubroca, Hannes Frederic Sowa
 14 *	Copyright (c) 2016-2018 Prarit Bhargava
 15 *	Copyright (c) 2017 Paolo Abeni, Larry Woodman
 16 */
 17
 18#ifndef __KABI_H__
 19#define __KABI_H__
 20
 21/* Kernel macros for userspace testing. */
 22#ifndef __aligned
 23#define __aligned(x) __attribute__((__aligned__(x)))
 24#endif
 25#ifndef __used
 26#define __used __attribute__((__used__))
 27#endif
 28#ifndef __section
 29#define __section(section) __attribute__((__section__(section)))
 30#endif
 31#ifndef __PASTE
 32#define ___PASTE(a, b) a##b
 33#define __PASTE(a, b) ___PASTE(a, b)
 34#endif
 35#ifndef __stringify
 36#define __stringify_1(x...) #x
 37#define __stringify(x...) __stringify_1(x)
 38#endif
 39
 40#define ___KABI_RULE(hint, target, value)                            \
 41	static const char __PASTE(__gendwarfksyms_rule_,             \
 42				  __COUNTER__)[] __used __aligned(1) \
 43		__section(".discard.gendwarfksyms.kabi_rules") =     \
 44			"1\0" #hint "\0" target "\0" value
 45
 46#define __KABI_RULE(hint, target, value) \
 47	___KABI_RULE(hint, #target, #value)
 48
 49#define __KABI_NORMAL_SIZE_ALIGN(_orig, _new)                                             \
 50	union {                                                                           \
 51		_Static_assert(                                                           \
 52			sizeof(struct { _new; }) <= sizeof(struct { _orig; }),            \
 53			__FILE__ ":" __stringify(__LINE__) ": " __stringify(              \
 54				_new) " is larger than " __stringify(_orig));             \
 55		_Static_assert(                                                           \
 56			__alignof__(struct { _new; }) <=                                  \
 57				__alignof__(struct { _orig; }),                           \
 58			__FILE__ ":" __stringify(__LINE__) ": " __stringify(              \
 59				_orig) " is not aligned the same as " __stringify(_new)); \
 60	}
 61
 62#define __KABI_REPLACE(_orig, _new)                    \
 63	union {                                        \
 64		_new;                                  \
 65		struct {                               \
 66			_orig;                         \
 67		};                                     \
 68		__KABI_NORMAL_SIZE_ALIGN(_orig, _new); \
 69	}
 70
 71/*
 72 * KABI_DECLONLY(fqn)
 73 *   Treat the struct/union/enum fqn as a declaration, i.e. even if
 74 *   a definition is available, don't expand the contents.
 75 */
 76#define KABI_DECLONLY(fqn) __KABI_RULE(declonly, fqn, )
 77
 78/*
 79 * KABI_ENUMERATOR_IGNORE(fqn, field)
 80 *   When expanding enum fqn, skip the provided field. This makes it
 81 *   possible to hide added enum fields from versioning.
 82 */
 83#define KABI_ENUMERATOR_IGNORE(fqn, field) \
 84	__KABI_RULE(enumerator_ignore, fqn field, )
 85
 86/*
 87 * KABI_ENUMERATOR_VALUE(fqn, field, value)
 88 *   When expanding enum fqn, use the provided value for the
 89 *   specified field. This makes it possible to override enumerator
 90 *   values when calculating versions.
 91 */
 92#define KABI_ENUMERATOR_VALUE(fqn, field, value) \
 93	__KABI_RULE(enumerator_value, fqn field, value)
 94
 95/*
 96 * KABI_BYTE_SIZE(fqn, value)
 97 *   Set the byte_size attribute for the struct/union/enum fqn to
 98 *   value bytes.
 99 */
100#define KABI_BYTE_SIZE(fqn, value) __KABI_RULE(byte_size, fqn, value)
101
102/*
103 * KABI_TYPE_STRING(type, str)
104 *   For the given type, override the type string used in symtypes
105 *   output and version calculation with str.
106 */
107#define KABI_TYPE_STRING(type, str) ___KABI_RULE(type_string, type, str)
108
109/*
110 * KABI_RESERVE
111 *   Reserve some "padding" in a structure for use by LTS backports.
112 *   This is normally placed at the end of a structure.
113 *   number: the "number" of the padding variable in the structure.  Start with
114 *   1 and go up.
115 */
116#define KABI_RESERVE(n) unsigned long __kabi_reserved##n
117
118/*
119 * KABI_RESERVE_ARRAY
120 *   Same as _BACKPORT_RESERVE but allocates an array with the specified
121 *   size in bytes.
122 */
123#define KABI_RESERVE_ARRAY(n, s) \
124	unsigned char __aligned(8) __kabi_reserved##n[s]
125
126/*
127 * KABI_IGNORE
128 *   Add a new field that's ignored in versioning.
129 */
130#define KABI_IGNORE(n, _new)                     \
131	union {                                  \
132		_new;                            \
133		unsigned char __kabi_ignored##n; \
134	}
135
136/*
137 * KABI_REPLACE
138 *   Replace a field with a compatible new field.
139 */
140#define KABI_REPLACE(_oldtype, _oldname, _new) \
141	__KABI_REPLACE(_oldtype __kabi_renamed##_oldname, struct { _new; })
142
143/*
144 * KABI_USE(number, _new)
145 *   Use a previous padding entry that was defined with KABI_RESERVE
146 *   number: the previous "number" of the padding variable
147 *   _new: the variable to use now instead of the padding variable
148 */
149#define KABI_USE(number, _new) __KABI_REPLACE(KABI_RESERVE(number), _new)
150
151/*
152 * KABI_USE2(number, _new1, _new2)
153 *   Use a previous padding entry that was defined with KABI_RESERVE for
154 *   two new variables that fit into 64 bits.  This is good for when you do not
155 *   want to "burn" a 64bit padding variable for a smaller variable size if not
156 *   needed.
157 */
158#define KABI_USE2(number, _new1, _new2)        \
159	__KABI_REPLACE(                        \
160		KABI_RESERVE(number), struct { \
161			_new1;                 \
162			_new2;                 \
163		})
164/*
165 * KABI_USE_ARRAY(number, bytes, _new)
166 *   Use a previous padding entry that was defined with KABI_RESERVE_ARRAY
167 *   number: the previous "number" of the padding variable
168 *   bytes: the size in bytes reserved for the array
169 *   _new: the variable to use now instead of the padding variable
170 */
171#define KABI_USE_ARRAY(number, bytes, _new) \
172	__KABI_REPLACE(KABI_RESERVE_ARRAY(number, bytes), _new)
173
174#endif /* __KABI_H__ */