Skip to content

Commit 2686eb8

Browse files
ebblakeaxboe
authored andcommitted
uapi nbd: add cookie alias to handle
The uapi <linux/nbd.h> header declares a 'char handle[8]' per request; which is overloaded in English (are you referring to "handle" the verb, such as handling a signal or writing a callback handler, or "handle" the noun, the value used in a lookup table to correlate a response back to the request). Many user-space NBD implementations (both servers and clients) have instead used 'uint64_t cookie' or similar, as it is easier to directly assign an integer than to futz around with memcpy. In fact, upstream documentation is now encouraging this shift in terminology: NetworkBlockDevice/nbd@ca4392eb2b Accomplish this by use of an anonymous union to provide the alias for anyone getting the definition from the uapi; this does not break existing clients, while exposing the nicer name for those who prefer it. Note that block/nbd.c still uses the term handle (in fact, it actually combines a 32-bit cookie and a 32-bit tag into the 64-bit handle), but that internal usage is not changed by the public uapi, since no compliant NBD server has any reason to inspect or alter the 64 bits sent over the socket. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Josef Bacik <josef@toxicpanda.com> Link: https://lore.kernel.org/r/20230410180611.1051618-3-eblake@redhat.com Signed-off-by: Jens Axboe <axboe@kernel.dk>
1 parent daf376a commit 2686eb8

File tree

1 file changed

+9
-3
lines changed

1 file changed

+9
-3
lines changed

include/uapi/linux/nbd.h

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
* 2004/02/19 Paul Clements
1313
* Removed PARANOIA, plus various cleanup and comments
1414
* 2023 Copyright Red Hat
15-
* Link to userspace extensions.
15+
* Link to userspace extensions, favor cookie over handle.
1616
*/
1717

1818
#ifndef _UAPILINUX_NBD_H
@@ -81,7 +81,10 @@ enum {
8181
struct nbd_request {
8282
__be32 magic; /* NBD_REQUEST_MAGIC */
8383
__be32 type; /* See NBD_CMD_* */
84-
char handle[8];
84+
union {
85+
__be64 cookie; /* Opaque identifier for request */
86+
char handle[8]; /* older spelling of cookie */
87+
};
8588
__be64 from;
8689
__be32 len;
8790
} __attribute__((packed));
@@ -93,6 +96,9 @@ struct nbd_request {
9396
struct nbd_reply {
9497
__be32 magic; /* NBD_REPLY_MAGIC */
9598
__be32 error; /* 0 = ok, else error */
96-
char handle[8]; /* handle you got from request */
99+
union {
100+
__be64 cookie; /* Opaque identifier from request */
101+
char handle[8]; /* older spelling of cookie */
102+
};
97103
};
98104
#endif /* _UAPILINUX_NBD_H */

0 commit comments

Comments
 (0)