c-code-gen.rst

  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). These max
 60values are named ``__$pfx-MAX`` and ``$pfx-MAX``. The name
 61of the first value can be overridden via ``enum-cnt-name`` property.
 62
 63Attributes
 64==========
 65
 66Each attribute set (excluding fractional sets) is rendered as an enum.
 67
 68Attribute enums are traditionally unnamed in netlink headers.
 69If naming is desired ``enum-name`` can be used to specify the name.
 70
 71The default attribute name prefix is ``$family-A`` if the name of the set
 72is the same as the name of the family and ``$family-A-$set`` if the names
 73differ. The prefix can be overridden by the ``name-prefix`` property of a set.
 74The rest of the section will refer to the prefix as ``$pfx``.
 75
 76Attributes are named ``$pfx-$attribute``.
 77
 78Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX``
 79which are used for sizing attribute tables.
 80These two names can be specified directly with the ``attr-cnt-name``
 81and ``attr-max-name`` properties respectively.
 82
 83If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name``
 84will be specified as a ``#define`` rather than an enum value.
 85
 86Operations
 87==========
 88
 89Operations are named ``$family-CMD-$operation``.
 90If ``name-prefix`` is specified it replaces the ``$family-CMD``
 91portion of the name.
 92
 93Similarly to attribute enums operation enums end with special count and max
 94attributes. For operations those attributes can be renamed with
 95``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define``
 96is ``true``.
 97
 98Multicast groups
 99================
100
101Each multicast group gets a define rendered into the kernel uAPI header.
102The name of the define is ``$family-MCGRP-$group``, and can be overwritten
103with the ``c-define-name`` property.
104
105Code generation
106===============
107
108uAPI header is assumed to come from ``<linux/$family.h>`` in the default header
109search path. It can be changed using the ``uapi-header`` global property.