1 .. SPDX-License-Identifier: BSD-3-Clause 1 .. SPDX-License-Identifier: BSD-3-Clause
2 2
3 ===================================== 3 =====================================
4 Using Netlink protocol specifications 4 Using Netlink protocol specifications
5 ===================================== 5 =====================================
6 6
7 This document is a quick starting guide for us 7 This document is a quick starting guide for using Netlink protocol
8 specifications. For more detailed description 8 specifications. For more detailed description of the specs see :doc:`specs`.
9 9
10 Simple CLI 10 Simple CLI
11 ========== 11 ==========
12 12
13 Kernel comes with a simple CLI tool which shou 13 Kernel comes with a simple CLI tool which should be useful when
14 developing Netlink related code. The tool is i 14 developing Netlink related code. The tool is implemented in Python
15 and can use a YAML specification to issue Netl 15 and can use a YAML specification to issue Netlink requests
16 to the kernel. Only Generic Netlink is support 16 to the kernel. Only Generic Netlink is supported.
17 17
18 The tool is located at ``tools/net/ynl/cli.py` 18 The tool is located at ``tools/net/ynl/cli.py``. It accepts
19 a handul of arguments, the most important ones 19 a handul of arguments, the most important ones are:
20 20
21 - ``--spec`` - point to the spec file 21 - ``--spec`` - point to the spec file
22 - ``--do $name`` / ``--dump $name`` - issue r 22 - ``--do $name`` / ``--dump $name`` - issue request ``$name``
23 - ``--json $attrs`` - provide attributes for 23 - ``--json $attrs`` - provide attributes for the request
24 - ``--subscribe $group`` - receive notificati 24 - ``--subscribe $group`` - receive notifications from ``$group``
25 25
26 YAML specs can be found under ``Documentation/ 26 YAML specs can be found under ``Documentation/netlink/specs/``.
27 27
28 Example use:: 28 Example use::
29 29
30 $ ./tools/net/ynl/cli.py --spec Documentatio 30 $ ./tools/net/ynl/cli.py --spec Documentation/netlink/specs/ethtool.yaml \
31 --do rings-get \ 31 --do rings-get \
32 --json '{"header":{"dev-index": 18}}' 32 --json '{"header":{"dev-index": 18}}'
33 {'header': {'dev-index': 18, 'dev-name': 'en 33 {'header': {'dev-index': 18, 'dev-name': 'eni1np1'},
34 'rx': 0, 34 'rx': 0,
35 'rx-jumbo': 0, 35 'rx-jumbo': 0,
36 'rx-jumbo-max': 4096, 36 'rx-jumbo-max': 4096,
37 'rx-max': 4096, 37 'rx-max': 4096,
38 'rx-mini': 0, 38 'rx-mini': 0,
39 'rx-mini-max': 4096, 39 'rx-mini-max': 4096,
40 'tx': 0, 40 'tx': 0,
41 'tx-max': 4096, 41 'tx-max': 4096,
42 'tx-push': 0} 42 'tx-push': 0}
43 43
44 The input arguments are parsed as JSON, while 44 The input arguments are parsed as JSON, while the output is only
45 Python-pretty-printed. This is because some Ne 45 Python-pretty-printed. This is because some Netlink types can't
46 be expressed as JSON directly. If such attribu 46 be expressed as JSON directly. If such attributes are needed in
47 the input some hacking of the script will be n 47 the input some hacking of the script will be necessary.
48 48
49 The spec and Netlink internals are factored ou 49 The spec and Netlink internals are factored out as a standalone
50 library - it should be easy to write Python to 50 library - it should be easy to write Python tools / tests reusing
51 code from ``cli.py``. 51 code from ``cli.py``.
52 52
53 Generating kernel code 53 Generating kernel code
54 ====================== 54 ======================
55 55
56 ``tools/net/ynl/ynl-regen.sh`` scans the kerne 56 ``tools/net/ynl/ynl-regen.sh`` scans the kernel tree in search of
57 auto-generated files which need to be updated. 57 auto-generated files which need to be updated. Using this tool is the easiest
58 way to generate / update auto-generated code. 58 way to generate / update auto-generated code.
59 59
60 By default code is re-generated only if spec i 60 By default code is re-generated only if spec is newer than the source,
61 to force regeneration use ``-f``. 61 to force regeneration use ``-f``.
62 62
63 ``ynl-regen.sh`` searches for ``YNL-GEN`` in t 63 ``ynl-regen.sh`` searches for ``YNL-GEN`` in the contents of files
64 (note that it only scans files in the git inde 64 (note that it only scans files in the git index, that is only files
65 tracked by git!) For instance the ``fou_nl.c`` 65 tracked by git!) For instance the ``fou_nl.c`` kernel source contains::
66 66
67 /* Documentation/netlink/specs/fou.yaml * 67 /* Documentation/netlink/specs/fou.yaml */
68 /* YNL-GEN kernel source */ 68 /* YNL-GEN kernel source */
69 69
70 ``ynl-regen.sh`` will find this marker and rep 70 ``ynl-regen.sh`` will find this marker and replace the file with
71 kernel source based on fou.yaml. 71 kernel source based on fou.yaml.
72 72
73 The simplest way to generate a new file based 73 The simplest way to generate a new file based on a spec is to add
74 the two marker lines like above to a file, add 74 the two marker lines like above to a file, add that file to git,
75 and run the regeneration tool. Grep the tree f 75 and run the regeneration tool. Grep the tree for ``YNL-GEN``
76 to see other examples. 76 to see other examples.
77 77
78 The code generation itself is performed by ``t 78 The code generation itself is performed by ``tools/net/ynl/ynl-gen-c.py``
79 but it takes a few arguments so calling it dir 79 but it takes a few arguments so calling it directly for each file
80 quickly becomes tedious. 80 quickly becomes tedious.
81 <<
82 YNL lib <<
83 ======= <<
84 <<
85 ``tools/net/ynl/lib/`` contains an implementat <<
86 (based on libmnl) which integrates with code g <<
87 ``tools/net/ynl/ynl-gen-c.py`` to create easy <<
88 <<
89 YNL basics <<
90 ---------- <<
91 <<
92 The YNL library consists of two parts - the ge <<
93 prefix by ``ynl_``) and per-family auto-genera <<
94 with the name of the family). <<
95 <<
96 To create a YNL socket call ynl_sock_create() <<
97 struct (family structs are exported by the aut <<
98 ynl_sock_destroy() closes the socket. <<
99 <<
100 YNL requests <<
101 ------------ <<
102 <<
103 Steps for issuing YNL requests are best explai <<
104 All the functions and types in this example co <<
105 code (for the netdev family in this case): <<
106 <<
107 .. code-block:: c <<
108 <<
109 // 0. Request and response pointers <<
110 struct netdev_dev_get_req *req; <<
111 struct netdev_dev_get_rsp *d; <<
112 <<
113 // 1. Allocate a request <<
114 req = netdev_dev_get_req_alloc(); <<
115 // 2. Set request parameters (as needed) <<
116 netdev_dev_get_req_set_ifindex(req, ifindex <<
117 <<
118 // 3. Issues the request <<
119 d = netdev_dev_get(ys, req); <<
120 // 4. Free the request arguments <<
121 netdev_dev_get_req_free(req); <<
122 // 5. Error check (the return value from st <<
123 if (!d) { <<
124 // 6. Print the YNL-generated error <<
125 fprintf(stderr, "YNL: %s\n", ys->err.m <<
126 return -1; <<
127 } <<
128 <<
129 // ... do stuff with the response @d <<
130 <<
131 // 7. Free response <<
132 netdev_dev_get_rsp_free(d); <<
133 <<
134 YNL dumps <<
135 --------- <<
136 <<
137 Performing dumps follows similar pattern as re <<
138 Dumps return a list of objects terminated by a <<
139 or NULL on error. Use ``ynl_dump_foreach()`` t <<
140 the result. <<
141 <<
142 YNL notifications <<
143 ----------------- <<
144 <<
145 YNL lib supports using the same socket for not <<
146 requests. In case notifications arrive during <<
147 they are queued internally and can be retrieve <<
148 <<
149 To subscribed to notifications use ``ynl_subsc <<
150 The notifications have to be read out from the <<
151 ``ynl_socket_get_fd()`` returns the underlying <<
152 be plugged into appropriate asynchronous IO AP <<
153 or ``select``. <<
154 <<
155 Notifications can be retrieved using ``ynl_ntf <<
156 to be freed using ``ynl_ntf_free()``. Since we <<
157 type upfront the notifications are returned as <<
158 and user is expected to cast them to the appro <<
159 on the ``cmd`` member. <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.