Documentation/userspace-api/netlink/c-code-gen.rst

   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.