1.. SPDX-License-Identifier: BSD-3-Clause
2
3==============================
4Netlink spec C code generation
5==============================
6
7This document describes how Netlink specifications are used to render
8C code (uAPI, policies etc.). It also defines the additional properties
9allowed in older families by the ``genetlink-c`` protocol level,
10to control the naming.
11
12For brevity this document refers to ``name`` properties of various
13objects by the object type. For example ``$attr`` is the value
14of ``name`` in an attribute, and ``$family`` is the name of the
15family (the global ``name`` property).
16
17The upper case is used to denote literal values, e.g. ``$family-CMD``
18means the concatenation of ``$family``, a dash character, and the literal
19``CMD``.
20
21The names of ``#defines`` and enum values are always converted to upper case,
22and with dashes (``-``) replaced by underscores (``_``).
23
24If the constructed name is a C keyword, an extra underscore is
25appended (``do`` -> ``do_``).
26
27Globals
28=======
29
30``c-family-name`` controls the name of the ``#define`` for the family
31name, default is ``$family-FAMILY-NAME``.
32
33``c-version-name`` controls the name of the ``#define`` for the version
34of the family, default is ``$family-FAMILY-VERSION``.
35
36``max-by-define`` selects if max values for enums are defined as a
37``#define`` rather than inside the enum.
38
39Definitions
40===========
41
42Constants
43---------
44
45Every constant is rendered as a ``#define``.
46The name of the constant is ``$family-$constant`` and the value
47is rendered as a string or integer according to its type in the spec.
48
49Enums and flags
50---------------
51
52Enums are named ``$family-$enum``. The full name can be set directly
53or suppressed by specifying the ``enum-name`` property.
54Default entry name is ``$family-$enum-$entry``.
55If ``name-prefix`` is specified it replaces the ``$family-$enum``
56portion of the entry name.
57
58Boolean ``render-max`` controls creation of the max values
59(which are enabled by default for attribute enums).
60
61Attributes
62==========
63
64Each attribute set (excluding fractional sets) is rendered as an enum.
65
66Attribute enums are traditionally unnamed in netlink headers.
67If naming is desired ``enum-name`` can be used to specify the name.
68
69The default attribute name prefix is ``$family-A`` if the name of the set
70is the same as the name of the family and ``$family-A-$set`` if the names
71differ. The prefix can be overridden by the ``name-prefix`` property of a set.
72The rest of the section will refer to the prefix as ``$pfx``.
73
74Attributes are named ``$pfx-$attribute``.
75
76Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX``
77which are used for sizing attribute tables.
78These two names can be specified directly with the ``attr-cnt-name``
79and ``attr-max-name`` properties respectively.
80
81If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name``
82will be specified as a ``#define`` rather than an enum value.
83
84Operations
85==========
86
87Operations are named ``$family-CMD-$operation``.
88If ``name-prefix`` is specified it replaces the ``$family-CMD``
89portion of the name.
90
91Similarly to attribute enums operation enums end with special count and max
92attributes. For operations those attributes can be renamed with
93``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define``
94is ``true``.
95
96Multicast groups
97================
98
99Each multicast group gets a define rendered into the kernel uAPI header.
100The name of the define is ``$family-MCGRP-$group``, and can be overwritten
101with the ``c-define-name`` property.
102
103Code generation
104===============
105
106uAPI header is assumed to come from ``<linux/$family.h>`` in the default header
107search path. It can be changed using the ``uapi-header`` global property.
108