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 using Netlink protocol
8 specifications. For more detailed description of the specs see :doc:`specs`.
9
10 Simple CLI
11 ==========
12
13 Kernel comes with a simple CLI tool which should be useful when
14 developing Netlink related code. The tool is implemented in Python
15 and can use a YAML specification to issue Netlink requests
16 to the kernel. Only Generic Netlink is supported.
17
18 The tool is located at ``tools/net/ynl/cli.py``. It accepts
19 a 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
26 YAML specs can be found under ``Documentation/netlink/specs/``.
27
28 Example 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
44 The input arguments are parsed as JSON, while the output is only
45 Python-pretty-printed. This is because some Netlink types can't
46 be expressed as JSON directly. If such attributes are needed in
47 the input some hacking of the script will be necessary.
48
49 The spec and Netlink internals are factored out as a standalone
50 library - it should be easy to write Python tools / tests reusing
51 code from ``cli.py``.
52
53 Generating kernel code
54 ======================
55
56 ``tools/net/ynl/ynl-regen.sh`` scans the kernel tree in search of
57 auto-generated files which need to be updated. Using this tool is the easiest
58 way to generate / update auto-generated code.
59
60 By default code is re-generated only if spec is newer than the source,
61 to 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
65 tracked 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
71 kernel source based on fou.yaml.
72
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 that file to git,
75 and run the regeneration tool. Grep the tree for ``YNL-GEN``
76 to see other examples.
77
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 directly for each file
80 quickly becomes tedious.
81
82 YNL lib
83 =======
84
85 ``tools/net/ynl/lib/`` contains an implementation of a C library
86 (based on libmnl) which integrates with code generated by
87 ``tools/net/ynl/ynl-gen-c.py`` to create easy to use netlink wrappers.
88
89 YNL basics
90 ----------
91
92 The YNL library consists of two parts - the generic code (functions
93 prefix by ``ynl_``) and per-family auto-generated code (prefixed
94 with the name of the family).
95
96 To create a YNL socket call ynl_sock_create() passing the family
97 struct (family structs are exported by the auto-generated code).
98 ynl_sock_destroy() closes the socket.
99
100 YNL requests
101 ------------
102
103 Steps for issuing YNL requests are best explained on an example.
104 All the functions and types in this example come from the auto-generated
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 step 3)
123 if (!d) {
124 // 6. Print the YNL-generated error
125 fprintf(stderr, "YNL: %s\n", ys->err.msg);
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 requests.
138 Dumps return a list of objects terminated by a special marker,
139 or NULL on error. Use ``ynl_dump_foreach()`` to iterate over
140 the result.
141
142 YNL notifications
143 -----------------
144
145 YNL lib supports using the same socket for notifications and
146 requests. In case notifications arrive during processing of a request
147 they are queued internally and can be retrieved at a later time.
148
149 To subscribed to notifications use ``ynl_subscribe()``.
150 The notifications have to be read out from the socket,
151 ``ynl_socket_get_fd()`` returns the underlying socket fd which can
152 be plugged into appropriate asynchronous IO API like ``poll``,
153 or ``select``.
154
155 Notifications can be retrieved using ``ynl_ntf_dequeue()`` and have
156 to be freed using ``ynl_ntf_free()``. Since we don't know the notification
157 type upfront the notifications are returned as ``struct ynl_ntf_base_type *``
158 and user is expected to cast them to the appropriate full type based
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.