1.. SPDX-License-Identifier: BSD-3-Clause
2
3=====================================
4Using Netlink protocol specifications
5=====================================
6
7This document is a quick starting guide for using Netlink protocol
8specifications. For more detailed description of the specs see :doc:`specs`.
9
10Simple CLI
11==========
12
13Kernel comes with a simple CLI tool which should be useful when
14developing Netlink related code. The tool is implemented in Python
15and can use a YAML specification to issue Netlink requests
16to the kernel. Only Generic Netlink is supported.
17
18The tool is located at ``tools/net/ynl/cli.py``. It accepts
19a handul of arguments, the most important ones are:
20
21 - ``--spec`` - point to the spec file
22 - ``--do $name`` / ``--dump $name`` - issue request ``$name``
23 - ``--json $attrs`` - provide attributes for the request
24 - ``--subscribe $group`` - receive notifications from ``$group``
25
26YAML specs can be found under ``Documentation/netlink/specs/``.
27
28Example use::
29
30  $ ./tools/net/ynl/cli.py --spec Documentation/netlink/specs/ethtool.yaml \
31        --do rings-get \
32	--json '{"header":{"dev-index": 18}}'
33  {'header': {'dev-index': 18, 'dev-name': 'eni1np1'},
34   'rx': 0,
35   'rx-jumbo': 0,
36   'rx-jumbo-max': 4096,
37   'rx-max': 4096,
38   'rx-mini': 0,
39   'rx-mini-max': 4096,
40   'tx': 0,
41   'tx-max': 4096,
42   'tx-push': 0}
43
44The input arguments are parsed as JSON, while the output is only
45Python-pretty-printed. This is because some Netlink types can't
46be expressed as JSON directly. If such attributes are needed in
47the input some hacking of the script will be necessary.
48
49The spec and Netlink internals are factored out as a standalone
50library - it should be easy to write Python tools / tests reusing
51code from ``cli.py``.
52
53Generating kernel code
54======================
55
56``tools/net/ynl/ynl-regen.sh`` scans the kernel tree in search of
57auto-generated files which need to be updated. Using this tool is the easiest
58way to generate / update auto-generated code.
59
60By default code is re-generated only if spec is newer than the source,
61to force regeneration use ``-f``.
62
63``ynl-regen.sh`` searches for ``YNL-GEN`` in the contents of files
64(note that it only scans files in the git index, that is only files
65tracked by git!) For instance the ``fou_nl.c`` kernel source contains::
66
67  /*	Documentation/netlink/specs/fou.yaml */
68  /* YNL-GEN kernel source */
69
70``ynl-regen.sh`` will find this marker and replace the file with
71kernel source based on fou.yaml.
72
73The simplest way to generate a new file based on a spec is to add
74the two marker lines like above to a file, add that file to git,
75and run the regeneration tool. Grep the tree for ``YNL-GEN``
76to see other examples.
77
78The code generation itself is performed by ``tools/net/ynl/ynl-gen-c.py``
79but it takes a few arguments so calling it directly for each file
80quickly becomes tedious.
81