* [PATCH] netlink: specs: add specification for NBD
@ 2026-02-15 18:03 Hristo Venev
2026-02-17 12:17 ` Donald Hunter
0 siblings, 1 reply; 5+ messages in thread
From: Hristo Venev @ 2026-02-15 18:03 UTC (permalink / raw)
To: Donald Hunter, Jakub Kicinski
Cc: David S. Miller, Eric Dumazet, Paolo Abeni, Simon Horman, netdev,
Josef Bacik, Jens Axboe, linux-block, nbd, Hristo Venev
This patch adds an initial YNL specification for NBD. The specification
can be used to produce a UAPI header that is equivalent to the one
currently shipped in the kernel.
The spec appears to be accurate enough so that commands can be issued
with pyynl.
Signed-off-by: Hristo Venev <hristo@venev.name>
---
Documentation/netlink/specs/nbd.yaml | 206 +++++++++++++++++++++++++++
1 file changed, 206 insertions(+)
create mode 100644 Documentation/netlink/specs/nbd.yaml
diff --git a/Documentation/netlink/specs/nbd.yaml b/Documentation/netlink/specs/nbd.yaml
new file mode 100644
index 0000000000000..a84912a867d91
--- /dev/null
+++ b/Documentation/netlink/specs/nbd.yaml
@@ -0,0 +1,206 @@
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+---
+name: nbd
+protocol: genetlink-c
+uapi-header: linux/nbd-netlink.h
+doc: See :file:`drivers/block/nbd.c`
+
+c-family-name: nbd-genl-family-name
+c-version-name: nbd-genl-version
+max-by-define: true
+
+attribute-sets:
+ -
+ name: nbd-attrs
+ name-prefix: nbd-attr-
+ doc: Configuration policy attributes, used for CONNECT
+ attributes:
+ -
+ name: unspec
+ value: 0
+ type: unused
+ -
+ name: index
+ type: u32
+ -
+ name: size-bytes
+ type: u64
+ -
+ name: block-size-bytes
+ type: u64
+ -
+ name: timeout
+ type: u64
+ -
+ name: server-flags
+ type: u64
+ -
+ name: client-flags
+ type: u64
+ -
+ name: sockets
+ type: nest
+ nested-attributes: sock-item-attrs
+ -
+ name: dead-conn-timeout
+ type: u64
+ -
+ name: device-list
+ type: nest
+ nested-attributes: device-item-attrs
+ -
+ name: backend-identifier
+ type: string
+ -
+ name: device-item-attrs
+ name-prefix: nbd-device-item-
+ doc: |
+ This is the format for multiple devices with :code:`NBD_ATTR_DEVICE_LIST`
+
+ .. code-block::
+
+ [NBD_ATTR_DEVICE_LIST]
+ [NBD_DEVICE_ITEM]
+ [NBD_DEVICE_INDEX]
+ [NBD_DEVICE_CONNECTED]
+ attributes:
+ -
+ name: unspec
+ value: 0
+ type: unused
+ -
+ name: item
+ name-prefix: nbd-device-
+ type: nest
+ nested-attributes: device-attrs
+ multi-attr: true
+ -
+ name: device-attrs
+ name-prefix: nbd-device-
+ attr-max-name: nbd-device-attr-max
+ attributes:
+ -
+ name: unspec
+ value: 0
+ type: unused
+ -
+ name: index
+ type: u32
+ -
+ name: connected
+ type: u8
+ -
+ name: sock-item-attrs
+ name-prefix: nbd-sock-item-
+ doc: |
+ This is the format for multiple sockets with :code:`NBD_ATTR_SOCKETS`
+
+ .. code-block::
+
+ [NBD_ATTR_SOCKETS]
+ [NBD_SOCK_ITEM]
+ [NBD_SOCK_FD]
+ [NBD_SOCK_ITEM]
+ [NBD_SOCK_FD]
+ attributes:
+ -
+ name: unspec
+ value: 0
+ type: unused
+ -
+ name: item
+ name-prefix: nbd-sock-
+ type: nest
+ nested-attributes: sock-attrs
+ multi-attr: true
+ -
+ name: sock-attrs
+ name-prefix: nbd-sock-
+ attributes:
+ -
+ name: unspec
+ value: 0
+ type: unused
+ -
+ name: fd
+ type: u32
+
+operations:
+ enum-model: unified
+ name-prefix: nbd-cmd-
+ list:
+ -
+ name: unspec
+ value: 0
+ doc: NBD_CMD_UNSPEC
+ -
+ name: connect
+ doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_connect()`
+ attribute-set: nbd-attrs
+ dont-validate: [strict]
+ do:
+ request:
+ attributes:
+ - index
+ - size-bytes
+ - block-size-bytes
+ - timeout
+ - server-flags
+ - client-flags
+ - sockets
+ - dead-conn-timeout
+ - backend-identifier
+ reply:
+ attributes:
+ - index
+ -
+ name: disconnect
+ doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_disconnect()`
+ attribute-set: nbd-attrs
+ dont-validate: [strict]
+ do:
+ request:
+ attributes:
+ - index
+ -
+ name: reconfigure
+ doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_reconfigure()`
+ attribute-set: nbd-attrs
+ dont-validate: [strict]
+ do:
+ request:
+ attributes:
+ - index
+ - size-bytes
+ - block-size-bytes
+ - timeout
+ - client-flags
+ - sockets
+ - dead-conn-timeout
+ - backend-identifier
+ -
+ name: link-dead
+ doc: See :file:`drivers/block/nbd.c`, :code:`nbd_mark_nsock_dead()` / :code:`nbd_dead_link_work()`
+ attribute-set: nbd-attrs
+ event:
+ attributes:
+ - index
+ mcgrp: nbd_mc_group
+ -
+ name: status
+ doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_status()`
+ attribute-set: nbd-attrs
+ dont-validate: [strict]
+ do:
+ request:
+ attributes:
+ - index
+ reply:
+ attributes:
+ - device-list
+
+mcast-groups:
+ list:
+ -
+ name: nbd_mc_group
+ c-define-name: nbd-genl-mcast-group-name
--
2.53.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] netlink: specs: add specification for NBD
2026-02-15 18:03 [PATCH] netlink: specs: add specification for NBD Hristo Venev
@ 2026-02-17 12:17 ` Donald Hunter
2026-02-17 17:40 ` Hristo Venev
0 siblings, 1 reply; 5+ messages in thread
From: Donald Hunter @ 2026-02-17 12:17 UTC (permalink / raw)
To: Hristo Venev
Cc: Jakub Kicinski, David S. Miller, Eric Dumazet, Paolo Abeni,
Simon Horman, netdev, Josef Bacik, Jens Axboe, linux-block, nbd
Hristo Venev <hristo@venev.name> writes:
> This patch adds an initial YNL specification for NBD. The specification
> can be used to produce a UAPI header that is equivalent to the one
> currently shipped in the kernel.
>
> The spec appears to be accurate enough so that commands can be issued
> with pyynl.
>
> Signed-off-by: Hristo Venev <hristo@venev.name>
> ---
> Documentation/netlink/specs/nbd.yaml | 206 +++++++++++++++++++++++++++
> 1 file changed, 206 insertions(+)
> create mode 100644 Documentation/netlink/specs/nbd.yaml
There are yamllint errors:
make -C tools/net/ynl lint
make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
yamllint ../../../Documentation/netlink/specs
../../../Documentation/netlink/specs/nbd.yaml
159:81 error line too long (104 > 80 characters) (line-length)
169:6 error syntax error: expected <block end>, but found '<block mapping start>' (syntax)
170:7 error wrong indentation: expected 5 but found 6 (indentation)
>
> diff --git a/Documentation/netlink/specs/nbd.yaml b/Documentation/netlink/specs/nbd.yaml
> new file mode 100644
> index 0000000000000..a84912a867d91
> --- /dev/null
> +++ b/Documentation/netlink/specs/nbd.yaml
> @@ -0,0 +1,206 @@
> +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
> +---
> +name: nbd
> +protocol: genetlink-c
> +uapi-header: linux/nbd-netlink.h
> +doc: See :file:`drivers/block/nbd.c`
Prefer to see a meaningful doc string here.
> +
> +c-family-name: nbd-genl-family-name
> +c-version-name: nbd-genl-version
> +max-by-define: true
> +
> +attribute-sets:
> + -
> + name: nbd-attrs
> + name-prefix: nbd-attr-
> + doc: Configuration policy attributes, used for CONNECT
> + attributes:
> + -
> + name: unspec
> + value: 0
> + type: unused
No need for unspec in the attribute list, ynl codegen does the right thing.
> + -
> + name: index
> + type: u32
> + -
> + name: size-bytes
> + type: u64
> + -
> + name: block-size-bytes
> + type: u64
> + -
> + name: timeout
> + type: u64
> + -
> + name: server-flags
> + type: u64
> + -
> + name: client-flags
> + type: u64
> + -
> + name: sockets
> + type: nest
> + nested-attributes: sock-item-attrs
> + -
> + name: dead-conn-timeout
> + type: u64
> + -
> + name: device-list
> + type: nest
> + nested-attributes: device-item-attrs
> + -
> + name: backend-identifier
> + type: string
> + -
> + name: device-item-attrs
> + name-prefix: nbd-device-item-
> + doc: |
> + This is the format for multiple devices with :code:`NBD_ATTR_DEVICE_LIST`
> +
> + .. code-block::
> +
> + [NBD_ATTR_DEVICE_LIST]
> + [NBD_DEVICE_ITEM]
> + [NBD_DEVICE_INDEX]
> + [NBD_DEVICE_CONNECTED]
> + attributes:
> + -
> + name: unspec
> + value: 0
> + type: unused
Not required.
> + -
> + name: item
> + name-prefix: nbd-device-
> + type: nest
> + nested-attributes: device-attrs
> + multi-attr: true
> + -
> + name: device-attrs
> + name-prefix: nbd-device-
> + attr-max-name: nbd-device-attr-max
> + attributes:
> + -
> + name: unspec
> + value: 0
> + type: unused
Not required.
> + -
> + name: index
> + type: u32
> + -
> + name: connected
> + type: u8
> + -
> + name: sock-item-attrs
> + name-prefix: nbd-sock-item-
> + doc: |
> + This is the format for multiple sockets with :code:`NBD_ATTR_SOCKETS`
> +
> + .. code-block::
> +
> + [NBD_ATTR_SOCKETS]
> + [NBD_SOCK_ITEM]
> + [NBD_SOCK_FD]
> + [NBD_SOCK_ITEM]
> + [NBD_SOCK_FD]
> + attributes:
> + -
> + name: unspec
> + value: 0
> + type: unused
Not required.
> + -
> + name: item
> + name-prefix: nbd-sock-
> + type: nest
> + nested-attributes: sock-attrs
> + multi-attr: true
> + -
> + name: sock-attrs
> + name-prefix: nbd-sock-
> + attributes:
> + -
> + name: unspec
> + value: 0
> + type: unused
Not required.
> + -
> + name: fd
> + type: u32
> +
> +operations:
> + enum-model: unified
> + name-prefix: nbd-cmd-
> + list:
> + -
> + name: unspec
> + value: 0
> + doc: NBD_CMD_UNSPEC
Not required.
> + -
> + name: connect
> + doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_connect()`
Prefer to see meaningful doc string (same for other ops)
> + attribute-set: nbd-attrs
> + dont-validate: [strict]
nbd.c has strict & dump, should this be [strict, dump] ? (same for other ops)
> + do:
> + request:
> + attributes:
> + - index
> + - size-bytes
> + - block-size-bytes
> + - timeout
> + - server-flags
> + - client-flags
> + - sockets
> + - dead-conn-timeout
> + - backend-identifier
> + reply:
> + attributes:
> + - index
> + -
> + name: disconnect
> + doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_disconnect()`
> + attribute-set: nbd-attrs
> + dont-validate: [strict]
> + do:
> + request:
> + attributes:
> + - index
> + -
> + name: reconfigure
> + doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_reconfigure()`
> + attribute-set: nbd-attrs
> + dont-validate: [strict]
> + do:
> + request:
> + attributes:
> + - index
> + - size-bytes
> + - block-size-bytes
> + - timeout
> + - client-flags
> + - sockets
> + - dead-conn-timeout
> + - backend-identifier
> + -
> + name: link-dead
> + doc: See :file:`drivers/block/nbd.c`, :code:`nbd_mark_nsock_dead()` / :code:`nbd_dead_link_work()`
> + attribute-set: nbd-attrs
> + event:
> + attributes:
> + - index
> + mcgrp: nbd_mc_group
> + -
> + name: status
> + doc: See :file:`drivers/block/nbd.c`, :code:`nbd_genl_status()`
> + attribute-set: nbd-attrs
> + dont-validate: [strict]
> + do:
> + request:
> + attributes:
> + - index
> + reply:
> + attributes:
> + - device-list
> +
> +mcast-groups:
> + list:
> + -
> + name: nbd_mc_group
> + c-define-name: nbd-genl-mcast-group-name
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] netlink: specs: add specification for NBD
2026-02-17 12:17 ` Donald Hunter
@ 2026-02-17 17:40 ` Hristo Venev
2026-02-18 11:28 ` Donald Hunter
2026-02-23 9:40 ` Wouter Verhelst
0 siblings, 2 replies; 5+ messages in thread
From: Hristo Venev @ 2026-02-17 17:40 UTC (permalink / raw)
To: Donald Hunter
Cc: Jakub Kicinski, David S. Miller, Eric Dumazet, Paolo Abeni,
Simon Horman, netdev, Josef Bacik, Jens Axboe, linux-block, nbd
On Tue, 2026-02-17 at 12:17 +0000, Donald Hunter wrote:
> There are yamllint errors:
>
> make -C tools/net/ynl lint
> make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
> yamllint ../../../Documentation/netlink/specs
> ../../../Documentation/netlink/specs/nbd.yaml
> 159:81 error line too long (104 > 80 characters) (line-
> length)
> 169:6 error syntax error: expected <block end>, but found
> '<block mapping start>' (syntax)
> 170:7 error wrong indentation: expected 5 but found 6
> (indentation)
Thanks, I will fix the lint errors in v2.
> > +doc: See :file:`drivers/block/nbd.c`
>
> Prefer to see a meaningful doc string here.
I will add more proper documentation in v2. I couldn't find any
existing documentation of this netlink interface, so I guess I will
write it myself.
> > +attribute-sets:
> > + -
> > + name: nbd-attrs
> > + name-prefix: nbd-attr-
> > + doc: Configuration policy attributes, used for CONNECT
> > + attributes:
> > + -
> > + name: unspec
> > + value: 0
> > + type: unused
>
> No need for unspec in the attribute list, ynl codegen does the right
> thing.
For me `pyynl.ynl_gen_c --mode uapi --header` no longer generates
`NBD_ATTR_UNSPEC` if I remove this. Is there a YNL property to specify
the name of the zero value of the attribute set? If not, should I
remove it anyway, changing the generated header?
> > + name: device-item-attrs
> > + name-prefix: nbd-device-item-
> > + doc: |
> > + This is the format for multiple devices with
> > :code:`NBD_ATTR_DEVICE_LIST`
> > +
> > + .. code-block::
> > +
> > + [NBD_ATTR_DEVICE_LIST]
> > + [NBD_DEVICE_ITEM]
> > + [NBD_DEVICE_INDEX]
> > + [NBD_DEVICE_CONNECTED]
> > + attributes:
> > + -
> > + name: unspec
> > + value: 0
> > + type: unused
>
> Not required.
The same question applies here.
> > + name: device-attrs
> > + name-prefix: nbd-device-
> > + attr-max-name: nbd-device-attr-max
> > + attributes:
> > + -
> > + name: unspec
> > + value: 0
> > + type: unused
>
> Not required.
The same question applies here.
> > + name: sock-item-attrs
> > + name-prefix: nbd-sock-item-
> > + doc: |
> > + This is the format for multiple sockets with
> > :code:`NBD_ATTR_SOCKETS`
> > +
> > + .. code-block::
> > +
> > + [NBD_ATTR_SOCKETS]
> > + [NBD_SOCK_ITEM]
> > + [NBD_SOCK_FD]
> > + [NBD_SOCK_ITEM]
> > + [NBD_SOCK_FD]
> > + attributes:
> > + -
> > + name: unspec
> > + value: 0
> > + type: unused
>
> Not required.
The same question applies here.
> > + name: sock-attrs
> > + name-prefix: nbd-sock-
> > + attributes:
> > + -
> > + name: unspec
> > + value: 0
> > + type: unused
>
> Not required.
The same question applies here.
> > +operations:
> > + enum-model: unified
> > + name-prefix: nbd-cmd-
> > + list:
> > + -
> > + name: unspec
> > + value: 0
> > + doc: NBD_CMD_UNSPEC
A similar question applies here. If I remove this, `pyynl.ynl_gen_c
--mode uapi --header` no longer generates `NBD_CMD_UNSPEC`. Is there a
YNL property to generate it? If not, should I remove it anyway?
> > + -
> > + name: connect
> > + doc: See :file:`drivers/block/nbd.c`,
> > :code:`nbd_genl_connect()`
>
> Prefer to see meaningful doc string (same for other ops)
I guess I will have to document the four operations in v2 as well.
> > + attribute-set: nbd-attrs
> > + dont-validate: [strict]
>
> nbd.c has strict & dump, should this be [strict, dump] ? (same for
> other ops)
The NBD operations don't have `dump`, only `do`, so adding `dump` to
`dont-validate` does not change the output of `pyynl.ynl_gen_c --mode
kernel --source`. Should I add it anyway?
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] netlink: specs: add specification for NBD
2026-02-17 17:40 ` Hristo Venev
@ 2026-02-18 11:28 ` Donald Hunter
2026-02-23 9:40 ` Wouter Verhelst
1 sibling, 0 replies; 5+ messages in thread
From: Donald Hunter @ 2026-02-18 11:28 UTC (permalink / raw)
To: Hristo Venev
Cc: Jakub Kicinski, David S. Miller, Eric Dumazet, Paolo Abeni,
Simon Horman, netdev, Josef Bacik, Jens Axboe, linux-block, nbd
Hristo Venev <hristo@venev.name> writes:
> On Tue, 2026-02-17 at 12:17 +0000, Donald Hunter wrote:
>> There are yamllint errors:
>>
>> make -C tools/net/ynl lint
>> make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
>> yamllint ../../../Documentation/netlink/specs
>> ../../../Documentation/netlink/specs/nbd.yaml
>> 159:81 error line too long (104 > 80 characters) (line-
>> length)
>> 169:6 error syntax error: expected <block end>, but found
>> '<block mapping start>' (syntax)
>> 170:7 error wrong indentation: expected 5 but found 6
>> (indentation)
>
> Thanks, I will fix the lint errors in v2.
>
>> > +doc: See :file:`drivers/block/nbd.c`
>>
>> Prefer to see a meaningful doc string here.
>
> I will add more proper documentation in v2. I couldn't find any
> existing documentation of this netlink interface, so I guess I will
> write it myself.
>
>> > +attribute-sets:
>> > + -
>> > + name: nbd-attrs
>> > + name-prefix: nbd-attr-
>> > + doc: Configuration policy attributes, used for CONNECT
>> > + attributes:
>> > + -
>> > + name: unspec
>> > + value: 0
>> > + type: unused
>>
>> No need for unspec in the attribute list, ynl codegen does the right
>> thing.
>
> For me `pyynl.ynl_gen_c --mode uapi --header` no longer generates
> `NBD_ATTR_UNSPEC` if I remove this. Is there a YNL property to specify
> the name of the zero value of the attribute set? If not, should I
> remove it anyway, changing the generated header?
Oh sorry, if your goal is 100% equivalence then I guess you need it. We
have the same in "fou" for example.
>> > +operations:
>> > + enum-model: unified
>> > + name-prefix: nbd-cmd-
>> > + list:
>> > + -
>> > + name: unspec
>> > + value: 0
>> > + doc: NBD_CMD_UNSPEC
>
> A similar question applies here. If I remove this, `pyynl.ynl_gen_c
> --mode uapi --header` no longer generates `NBD_CMD_UNSPEC`. Is there a
> YNL property to generate it? If not, should I remove it anyway?
You'll need to keep it for equivalence.
>> > + -
>> > + name: connect
>> > + doc: See :file:`drivers/block/nbd.c`,
>> > :code:`nbd_genl_connect()`
>>
>> Prefer to see meaningful doc string (same for other ops)
>
> I guess I will have to document the four operations in v2 as well.
>
>> > + attribute-set: nbd-attrs
>> > + dont-validate: [strict]
>>
>> nbd.c has strict & dump, should this be [strict, dump] ? (same for
>> other ops)
>
> The NBD operations don't have `dump`, only `do`, so adding `dump` to
> `dont-validate` does not change the output of `pyynl.ynl_gen_c --mode
> kernel --source`. Should I add it anyway?
Ah, so it's redundant in nbd.c.
Thanks,
Donald.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] netlink: specs: add specification for NBD
2026-02-17 17:40 ` Hristo Venev
2026-02-18 11:28 ` Donald Hunter
@ 2026-02-23 9:40 ` Wouter Verhelst
1 sibling, 0 replies; 5+ messages in thread
From: Wouter Verhelst @ 2026-02-23 9:40 UTC (permalink / raw)
To: Hristo Venev
Cc: Donald Hunter, Jakub Kicinski, David S. Miller, Eric Dumazet,
Paolo Abeni, Simon Horman, netdev, Josef Bacik, Jens Axboe,
linux-block, nbd
On Tue, Feb 17, 2026 at 07:40:33PM +0200, Hristo Venev wrote:
> On Tue, 2026-02-17 at 12:17 +0000, Donald Hunter wrote:
> > There are yamllint errors:
> >
> > make -C tools/net/ynl lint
> > make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
> > yamllint ../../../Documentation/netlink/specs
> > ../../../Documentation/netlink/specs/nbd.yaml
> > 159:81 error line too long (104 > 80 characters) (line-
> > length)
> > 169:6 error syntax error: expected <block end>, but found
> > '<block mapping start>' (syntax)
> > 170:7 error wrong indentation: expected 5 but found 6
> > (indentation)
>
> Thanks, I will fix the lint errors in v2.
>
> > > +doc: See :file:`drivers/block/nbd.c`
> >
> > Prefer to see a meaningful doc string here.
>
> I will add more proper documentation in v2. I couldn't find any
> existing documentation of this netlink interface, so I guess I will
> write it myself.
As luck would have it, before I saw this message, I had been wanting to
work on some of the messages that nbd-client still needed, and so I
asked an LLM to analyze the code and generate some docs for me.
Heed the "LLM" part. It's probably not perfect. But it could be a good
starting point. Or not. At any rate, you can find it here:
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/netlink-proto.md
--
"I never had a C in history!"
"Yeah, but there was so much less of it when you were my age!"
-- Joe Brockmeier recounting a conversation with his father, cfgmgmtcamp 2026, Ghent
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2026-03-04 12:12 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-02-15 18:03 [PATCH] netlink: specs: add specification for NBD Hristo Venev
2026-02-17 12:17 ` Donald Hunter
2026-02-17 17:40 ` Hristo Venev
2026-02-18 11:28 ` Donald Hunter
2026-02-23 9:40 ` Wouter Verhelst
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox