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