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