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 82YNL 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 89YNL basics 90---------- 91 92The YNL library consists of two parts - the generic code (functions 93prefix by ``ynl_``) and per-family auto-generated code (prefixed 94with the name of the family). 95 96To create a YNL socket call ynl_sock_create() passing the family 97struct (family structs are exported by the auto-generated code). 98ynl_sock_destroy() closes the socket. 99 100YNL requests 101------------ 102 103Steps for issuing YNL requests are best explained on an example. 104All the functions and types in this example come from the auto-generated 105code (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 134YNL dumps 135--------- 136 137Performing dumps follows similar pattern as requests. 138Dumps return a list of objects terminated by a special marker, 139or NULL on error. Use ``ynl_dump_foreach()`` to iterate over 140the result. 141 142YNL notifications 143----------------- 144 145YNL lib supports using the same socket for notifications and 146requests. In case notifications arrive during processing of a request 147they are queued internally and can be retrieved at a later time. 148 149To subscribed to notifications use ``ynl_subscribe()``. 150The notifications have to be read out from the socket, 151``ynl_socket_get_fd()`` returns the underlying socket fd which can 152be plugged into appropriate asynchronous IO API like ``poll``, 153or ``select``. 154 155Notifications can be retrieved using ``ynl_ntf_dequeue()`` and have 156to be freed using ``ynl_ntf_free()``. Since we don't know the notification 157type upfront the notifications are returned as ``struct ynl_ntf_base_type *`` 158and user is expected to cast them to the appropriate full type based 159on the ``cmd`` member. 160