Documentation/kbuild/gendwarfksyms.rst

Source file repositories/reference/linux-study-clean/Documentation/kbuild/gendwarfksyms.rst

File Facts

System
Linux kernel
Corpus path
Documentation/kbuild/gendwarfksyms.rst
Extension
.rst
Size
14573 bytes
Lines
419
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct s {
		/* definition */
	};

	KABI_DECLONLY(s);

Adding enumerators
~~~~~~~~~~~~~~~~~~

For enums, all enumerators and their values are included in calculating
symbol versions, which becomes a problem if we later need to add more
enumerators without changing symbol versions. The `enumerator_ignore`
rule allows us to hide named enumerators from the input.

The rule fields are expected to be as follows:

- `type`: "enumerator_ignore"
- `target`: The fully qualified name of the target enum
  (as shown in **--dump-dies** output) and the name of the
  enumerator field separated by a space.
- `value`: This field is ignored.

Using the `__KABI_RULE` macro, this rule can be defined as::

	#define KABI_ENUMERATOR_IGNORE(fqn, field) \
		__KABI_RULE(enumerator_ignore, fqn field, )

Example usage::

	enum e {
		A, B, C, D,
	};

	KABI_ENUMERATOR_IGNORE(e, B);
	KABI_ENUMERATOR_IGNORE(e, C);

If the enum additionally includes an end marker and new values must
be added in the middle, we may need to use the old value for the last
enumerator when calculating versions. The `enumerator_value` rule allows
us to override the value of an enumerator for version calculation:

- `type`: "enumerator_value"
- `target`: The fully qualified name of the target enum
  (as shown in **--dump-dies** output) and the name of the
  enumerator field separated by a space.
- `value`: Integer value used for the field.

Using the `__KABI_RULE` macro, this rule can be defined as::

	#define KABI_ENUMERATOR_VALUE(fqn, field, value) \
		__KABI_RULE(enumerator_value, fqn field, value)

Example usage::

	enum e {
		A, B, C, LAST,
	};

	KABI_ENUMERATOR_IGNORE(e, C);
	KABI_ENUMERATOR_VALUE(e, LAST, 2);

Managing structure size changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A data structure can be partially opaque to modules if its allocation is
handled by the core kernel, and modules only need to access some of its
members. In this situation, it's possible to append new members to the
structure without breaking the ABI, as long as the layout for the original
members remains unchanged.

Annotation

Implementation Notes