Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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__ */