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