From nobody Sat Apr 11 23:24:02 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1F37CC6FD19 for ; Fri, 10 Mar 2023 20:16:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231389AbjCJUQZ (ORCPT ); Fri, 10 Mar 2023 15:16:25 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39648 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230433AbjCJUQW (ORCPT ); Fri, 10 Mar 2023 15:16:22 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B214212DC3E for ; Fri, 10 Mar 2023 12:15:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1678479332; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ySNF9VklMnLNMFFSlXUm9DSmVb0PMck6UAVDHRxOWTI=; b=P1hLghfHsbIaPuvscqZ/FXZh5pqzAWAnm1FjyvKCDSPaT5VDfGS6FBa3Y1BCe4FcanXHce nCFTlWebXu81yue/BABIWl9I54WQdUd8YckHMIsAePoS7aTXgvAgzYb7L2OlMuVpnf8cJ2 DF4njTNVn2m8CswWB5RQ5YdcB+CU0sU= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-67-l6gRyfhQNuOgRsi4_uQD8A-1; Fri, 10 Mar 2023 15:15:28 -0500 X-MC-Unique: l6gRyfhQNuOgRsi4_uQD8A-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id D3A5E858F09; Fri, 10 Mar 2023 20:15:27 +0000 (UTC) Received: from green.redhat.com (unknown [10.2.16.147]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1EA8C4014CF3; Fri, 10 Mar 2023 20:15:27 +0000 (UTC) From: Eric Blake To: josef@toxicpanda.com, linux-block@vger.kernel.org, nbd@other.debian.org Cc: philipp.reisner@linbit.com, lars.ellenberg@linbit.com, christoph.boehmwalder@linbit.com, corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 1/3] uapi nbd: improve doc links to userspace spec Date: Fri, 10 Mar 2023 14:15:23 -0600 Message-Id: <20230310201525.2615385-2-eblake@redhat.com> In-Reply-To: <20230310201525.2615385-1-eblake@redhat.com> References: <20230310201525.2615385-1-eblake@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.2 Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" The uapi 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. The documentation file also had a stale link to sourceforge; nbd ditched that several years ago in favor of github. Signed-off-by: Eric Blake Reviewed-by: Ming Lei --- Documentation/admin-guide/blockdev/nbd.rst | 2 +- include/uapi/linux/nbd.h | 15 ++++++++++++--- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/Documentation/admin-guide/blockdev/nbd.rst b/Documentation/adm= in-guide/blockdev/nbd.rst index d78dfe559dcf..faf2ac4b1509 100644 --- a/Documentation/admin-guide/blockdev/nbd.rst +++ b/Documentation/admin-guide/blockdev/nbd.rst @@ -14,7 +14,7 @@ to borrow disk space from another computer. Unlike NFS, it is possible to put any filesystem on it, etc. For more information, or to download the nbd-client and nbd-server -tools, go to http://nbd.sf.net/. +tools, go to https://github.com/NetworkBlockDevice/nbd. The nbd kernel module need only be installed on the client system, as the nbd-server is completely in userspace. In fact, diff --git a/include/uapi/linux/nbd.h b/include/uapi/linux/nbd.h index 20d6cc91435d..8797387caaf7 100644 --- a/include/uapi/linux/nbd.h +++ b/include/uapi/linux/nbd.h @@ -11,6 +11,8 @@ * Cleanup PARANOIA usage & code. * 2004/02/19 Paul Clements * Removed PARANOIA, plus various cleanup and comments + * 2023 Copyright Red Hat + * Link to userspace extensions. */ #ifndef _UAPILINUX_NBD_H @@ -30,12 +32,18 @@ #define NBD_SET_TIMEOUT _IO( 0xab, 9 ) #define NBD_SET_FLAGS _IO( 0xab, 10) +/* + * See also https://github.com/NetworkBlockDevice/nbd/blob/master/doc/prot= o.md + * for additional userspace extensions not yet utilized in the kernel modu= le. + */ + enum { NBD_CMD_READ =3D 0, NBD_CMD_WRITE =3D 1, NBD_CMD_DISC =3D 2, NBD_CMD_FLUSH =3D 3, NBD_CMD_TRIM =3D 4 + /* userspace defines additional extension commands */ }; /* values for flags field, these are server interaction specific. */ @@ -64,14 +72,15 @@ enum { #define NBD_REQUEST_MAGIC 0x25609513 #define NBD_REPLY_MAGIC 0x67446698 /* Do *not* use magics: 0x12560953 0x96744668. */ +/* magic 0x668e33ef for structured reply not supported by kernel yet */ /* * This is the packet used for communication between client and * server. All data are in network byte order. */ struct nbd_request { - __be32 magic; - __be32 type; /* =3D=3D READ || =3D=3D WRITE */ + __be32 magic; /* NBD_REQUEST_MAGIC */ + __be32 type; /* See NBD_CMD_* */ char handle[8]; __be64 from; __be32 len; @@ -82,7 +91,7 @@ struct nbd_request { * it has completed an I/O request (or an error occurs). */ struct nbd_reply { - __be32 magic; + __be32 magic; /* NBD_REPLY_MAGIC */ __be32 error; /* 0 =3D ok, else error */ char handle[8]; /* handle you got from request */ }; --=20 2.39.2 From nobody Sat Apr 11 23:24:02 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 96275C76186 for ; Fri, 10 Mar 2023 20:16:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231454AbjCJUQe (ORCPT ); Fri, 10 Mar 2023 15:16:34 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40148 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230284AbjCJUQ0 (ORCPT ); Fri, 10 Mar 2023 15:16:26 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CE3DC12E14B for ; Fri, 10 Mar 2023 12:15:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1678479333; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ppIa7KL6T1jyviPGvoaICUIPVqm/wSOFkhdUqjpubIE=; b=FcWcD3HZNoHRQiP6hJPRsGbzKI2ahulqg3zSO6RNB3BG0tO1GerLCDh8yKsWttiG8QAmQC y1mH+BUQ7COCzPimigTqRnClq8e3YlUNEEmjTKg4GmIITQr0z9ZQk6Q6TG80FmOS41XxFa QwjLiS21LlAbZK83ZLP9j5XFA8AtwdI= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-179-lbKHM_LDMR6GQI_jhdVRew-1; Fri, 10 Mar 2023 15:15:29 -0500 X-MC-Unique: lbKHM_LDMR6GQI_jhdVRew-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id B1B9285CBE0; Fri, 10 Mar 2023 20:15:28 +0000 (UTC) Received: from green.redhat.com (unknown [10.2.16.147]) by smtp.corp.redhat.com (Postfix) with ESMTP id F0A004014CF3; Fri, 10 Mar 2023 20:15:27 +0000 (UTC) From: Eric Blake To: josef@toxicpanda.com, linux-block@vger.kernel.org, nbd@other.debian.org Cc: philipp.reisner@linbit.com, lars.ellenberg@linbit.com, christoph.boehmwalder@linbit.com, corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 2/3] uapi nbd: add cookie alias to handle Date: Fri, 10 Mar 2023 14:15:24 -0600 Message-Id: <20230310201525.2615385-3-eblake@redhat.com> In-Reply-To: <20230310201525.2615385-1-eblake@redhat.com> References: <20230310201525.2615385-1-eblake@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.2 Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" The uapi 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 client-side NBD implementations (both servers and clients) have instead used 'u64 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: https://lists.debian.org/nbd/2023/03/msg00031.html 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 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 --- include/uapi/linux/nbd.h | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/include/uapi/linux/nbd.h b/include/uapi/linux/nbd.h index 8797387caaf7..f58f2043f62e 100644 --- a/include/uapi/linux/nbd.h +++ b/include/uapi/linux/nbd.h @@ -81,7 +81,10 @@ enum { struct nbd_request { __be32 magic; /* NBD_REQUEST_MAGIC */ __be32 type; /* See NBD_CMD_* */ - char handle[8]; + union { + char handle[8]; + __be64 cookie; + }; __be64 from; __be32 len; } __attribute__((packed)); @@ -93,6 +96,9 @@ struct nbd_request { struct nbd_reply { __be32 magic; /* NBD_REPLY_MAGIC */ __be32 error; /* 0 =3D ok, else error */ - char handle[8]; /* handle you got from request */ + union { + char handle[8]; /* handle you got from request */ + __be64 cookie; + }; }; #endif /* _UAPILINUX_NBD_H */ --=20 2.39.2 From nobody Sat Apr 11 23:24:02 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id EC60CC6FA99 for ; Fri, 10 Mar 2023 20:16:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231384AbjCJUQh (ORCPT ); Fri, 10 Mar 2023 15:16:37 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39678 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229933AbjCJUQ1 (ORCPT ); Fri, 10 Mar 2023 15:16:27 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8ACD512CBE8 for ; Fri, 10 Mar 2023 12:15:36 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1678479335; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Qbf3haIGUbZxNkBMJMJQ815E2aix9OEBTv2ECdqvLKY=; b=f1L5jAIS5hMQilXgSlghnOAO+ebOi6b/O3vN+3MkOPVoNom44kf5CWZf0Mwj718hsUJ/s1 XVuTVgcftJaJyh1V4viiBMpccLst7WcH2u0qNvvdBR0sJMzbT+7ApTvCHmj0ckGfxRwzdP 9N6RcT16smxIlsDr0Uyu0Rd2Sq6GCmw= Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-349-xlH238XMOMmsWX3UtP1IVg-1; Fri, 10 Mar 2023 15:15:30 -0500 X-MC-Unique: xlH238XMOMmsWX3UtP1IVg-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 8DD093C025D2; Fri, 10 Mar 2023 20:15:29 +0000 (UTC) Received: from green.redhat.com (unknown [10.2.16.147]) by smtp.corp.redhat.com (Postfix) with ESMTP id CF0B64014CF3; Fri, 10 Mar 2023 20:15:28 +0000 (UTC) From: Eric Blake To: josef@toxicpanda.com, linux-block@vger.kernel.org, nbd@other.debian.org Cc: philipp.reisner@linbit.com, lars.ellenberg@linbit.com, christoph.boehmwalder@linbit.com, corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 3/3] block nbd: use req.cookie instead of req.handle Date: Fri, 10 Mar 2023 14:15:25 -0600 Message-Id: <20230310201525.2615385-4-eblake@redhat.com> In-Reply-To: <20230310201525.2615385-1-eblake@redhat.com> References: <20230310201525.2615385-1-eblake@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.2 Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" A good compiler should not compile this any differently, but it seems nicer to avoid memcpy() when integer assignment will work. Signed-off-by: Eric Blake --- drivers/block/nbd.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/drivers/block/nbd.c b/drivers/block/nbd.c index 592cfa8b765a..672fb8d1ce67 100644 --- a/drivers/block/nbd.c +++ b/drivers/block/nbd.c @@ -606,7 +606,7 @@ static int nbd_send_cmd(struct nbd_device *nbd, struct = nbd_cmd *cmd, int index) request.len =3D htonl(size); } handle =3D nbd_cmd_handle(cmd); - memcpy(request.handle, &handle, sizeof(handle)); + request.cookie =3D handle; trace_nbd_send_request(&request, nbd->index, blk_mq_rq_from_pdu(cmd)); @@ -732,7 +732,7 @@ static struct nbd_cmd *nbd_handle_reply(struct nbd_devi= ce *nbd, int index, u32 tag; int ret =3D 0; - memcpy(&handle, reply->handle, sizeof(handle)); + handle =3D reply->cookie; tag =3D nbd_handle_to_tag(handle); hwq =3D blk_mq_unique_tag_to_hwq(tag); if (hwq < nbd->tag_set.nr_hw_queues) --=20 2.39.2