History

uapi nbd: improve doc links to userspace spec

The uapi <linux/nbd.h> header intentionally documents only the NBD server features that the kernel module will utilize as a client. But while it already had one mention of skipped bits due to userspace extensions, it did not actually direct the reader to the canonical source to learn about those extensions. While touching comments, fix an outdated reference that listed only READ and WRITE as commands.

Eric Blake committed 3 years ago

Commit daf376a1 parent ff53cd51 file · +12 −3Browse files

Showing the changes to include/uapi (1 of 1 file). Show all

Unified · Split

include/uapi/linux/nbd.h+12−3
@@ -11,6 +11,8 @@ · 10 unmodified lines
11 * Cleanup PARANOIA usage & code.11 * Cleanup PARANOIA usage & code.
12 * 2004/02/19 Paul Clements12 * 2004/02/19 Paul Clements
13 * Removed PARANOIA, plus various cleanup and comments13 * Removed PARANOIA, plus various cleanup and comments
14 * 2023 Copyright Red Hat
15 * Link to userspace extensions.
14 */16 */
15 17
16#ifndef _UAPILINUX_NBD_H18#ifndef _UAPILINUX_NBD_H
@@ -30,12 +32,18 @@ · 13 unmodified lines
30#define NBD_SET_TIMEOUT _IO( 0xab, 9 )32#define NBD_SET_TIMEOUT _IO( 0xab, 9 )
31#define NBD_SET_FLAGS _IO( 0xab, 10)33#define NBD_SET_FLAGS _IO( 0xab, 10)
32 34
35/*
36 * See also https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
37 * for additional userspace extensions not yet utilized in the kernel module.
38 */
39
33enum {40enum {
34 NBD_CMD_READ = 0,41 NBD_CMD_READ = 0,
35 NBD_CMD_WRITE = 1,42 NBD_CMD_WRITE = 1,
36 NBD_CMD_DISC = 2,43 NBD_CMD_DISC = 2,
37 NBD_CMD_FLUSH = 3,44 NBD_CMD_FLUSH = 3,
38 NBD_CMD_TRIM = 445 NBD_CMD_TRIM = 4
46 /* userspace defines additional extension commands */
39};47};
40 48
41/* values for flags field, these are server interaction specific. */49/* values for flags field, these are server interaction specific. */
@@ -64,14 +72,15 @@ enum { · 22 unmodified lines
64#define NBD_REQUEST_MAGIC 0x2560951372#define NBD_REQUEST_MAGIC 0x25609513
65#define NBD_REPLY_MAGIC 0x6744669873#define NBD_REPLY_MAGIC 0x67446698
66/* Do *not* use magics: 0x12560953 0x96744668. */74/* Do *not* use magics: 0x12560953 0x96744668. */
75/* magic 0x668e33ef for structured reply not supported by kernel yet */
67 76
68/*77/*
69 * This is the packet used for communication between client and78 * This is the packet used for communication between client and
70 * server. All data are in network byte order.79 * server. All data are in network byte order.
71 */80 */
72struct nbd_request {81struct nbd_request {
73 __be32 magic;82 __be32 magic; /* NBD_REQUEST_MAGIC */
74 __be32 type; /* == READ || == WRITE */83 __be32 type; /* See NBD_CMD_* */
75 char handle[8];84 char handle[8];
76 __be64 from;85 __be64 from;
77 __be32 len;86 __be32 len;
@@ -82,7 +91,7 @@ struct nbd_request { · 4 unmodified lines
82 * it has completed an I/O request (or an error occurs).91 * it has completed an I/O request (or an error occurs).
83 */92 */
84struct nbd_reply {93struct nbd_reply {
85 __be32 magic;94 __be32 magic; /* NBD_REPLY_MAGIC */
86 __be32 error; /* 0 = ok, else error */95 __be32 error; /* 0 = ok, else error */
87 char handle[8]; /* handle you got from request */96 char handle[8]; /* handle you got from request */
88};97};