1 .. SPDX-License-Identifier: BSD-3-Clause
2
3 =====================================
4 Using Netlink protocol specifications
5 =====================================
6
7 This document is a quick starting guide for us
8 specifications. For more detailed description
9
10 Simple CLI
11 ==========
12
13 Kernel comes with a simple CLI tool which shou
14 developing Netlink related code. The tool is i
15 and can use a YAML specification to issue Netl
16 to the kernel. Only Generic Netlink is support
17
18 The tool is located at ``tools/net/ynl/cli.py`
19 a handul of arguments, the most important ones
20
21 - ``--spec`` - point to the spec file
22 - ``--do $name`` / ``--dump $name`` - issue r
23 - ``--json $attrs`` - provide attributes for
24 - ``--subscribe $group`` - receive notificati
25
26 YAML specs can be found under ``Documentation/
27
28 Example use::
29
30 $ ./tools/net/ynl/cli.py --spec Documentatio
31 --do rings-get \
32 --json '{"header":{"dev-index": 18}}'
33 {'header': {'dev-index': 18, 'dev-name': 'en
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
44 The input arguments are parsed as JSON, while
45 Python-pretty-printed. This is because some Ne
46 be expressed as JSON directly. If such attribu
47 the input some hacking of the script will be n
48
49 The spec and Netlink internals are factored ou
50 library - it should be easy to write Python to
51 code from ``cli.py``.
52
53 Generating kernel code
54 ======================
55
56 ``tools/net/ynl/ynl-regen.sh`` scans the kerne
57 auto-generated files which need to be updated.
58 way to generate / update auto-generated code.
59
60 By default code is re-generated only if spec i
61 to force regeneration use ``-f``.
62
63 ``ynl-regen.sh`` searches for ``YNL-GEN`` in t
64 (note that it only scans files in the git inde
65 tracked by git!) For instance the ``fou_nl.c``
66
67 /* Documentation/netlink/specs/fou.yaml *
68 /* YNL-GEN kernel source */
69
70 ``ynl-regen.sh`` will find this marker and rep
71 kernel source based on fou.yaml.
72
73 The simplest way to generate a new file based
74 the two marker lines like above to a file, add
75 and run the regeneration tool. Grep the tree f
76 to see other examples.
77
78 The code generation itself is performed by ``t
79 but it takes a few arguments so calling it dir
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.