From nobody Mon Oct 27 14:11:16 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1761309110; cv=none; d=zohomail.com; s=zohoarc; b=T34JePD1YUccWBA8Xn5treDeiQmPwxI2hMfyfvLziaJkGl8QR1eYCj2T+bJdOp+pQejplr7jtcrSTG9EXHf4/LfV6pZXHx6BPxajalxXEObtpvbUFlUNiJuRto+3beowbv6q+HsjusiHEphfMcGMTg4HkYgykl4YbyT7YmNsNUk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1761309110; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=vY6HOny8OWLBaW+1NOLRFvxDRZBqkxO95+48/OAZED0=; b=lwk0F9vHiD1qB7/xwF09RX5YCTSehXDcVWGtWXVjsDgCEIUVrCkPhVVn3veoEPvksZ2m3ksxKmNykzsKHY6ci/HU3QCQhtV6UJsDCOB3BbOBTY41ITMHbnb+4nWNYrjfRckGxjGKuCPf2x9X4y2SliNQfC7rQU575mf1QCtBBa0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1761309109896308.109164589668; Fri, 24 Oct 2025 05:31:49 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1vCGwg-0005yh-Vi; Fri, 24 Oct 2025 08:31:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1vCGwe-0005y3-P2 for qemu-devel@nongnu.org; Fri, 24 Oct 2025 08:31:01 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1vCGwc-00067E-1F for qemu-devel@nongnu.org; Fri, 24 Oct 2025 08:31:00 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-326-JMhYRBYKN3aT0_uW87Azmg-1; Fri, 24 Oct 2025 08:30:54 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 2CA011800637; Fri, 24 Oct 2025 12:30:53 +0000 (UTC) Received: from merkur.fritz.box (unknown [10.45.225.249]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id DADAC19540EB; Fri, 24 Oct 2025 12:30:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1761309055; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=vY6HOny8OWLBaW+1NOLRFvxDRZBqkxO95+48/OAZED0=; b=BB0Ou/Yk5d+cHeLNeTmb1cSjNJzPnG59cBkeApxXNep3htUAy+vMxATxPEiXXnxOXDfZkR xJTfunYLPDJhIGHokPpDjU6Zi57zv3Zw7xyWsLfI3YegfXTf64Ad3qtnlglasalWjRaMTE 5YzpOjW0fq/7AhFn1QMzljqP9VH+lrM= X-MC-Unique: JMhYRBYKN3aT0_uW87Azmg-1 X-Mimecast-MFC-AGG-ID: JMhYRBYKN3aT0_uW87Azmg_1761309053 From: Kevin Wolf To: qemu-block@nongnu.org Cc: kwolf@redhat.com, eblake@redhat.com, armbru@redhat.com, qemu-devel@nongnu.org, hreitz@redhat.com Subject: [PATCH v2 1/4] block: Improve comments in BlockLimits Date: Fri, 24 Oct 2025 14:30:37 +0200 Message-ID: <20251024123041.51254-2-kwolf@redhat.com> In-Reply-To: <20251024123041.51254-1-kwolf@redhat.com> References: <20251024123041.51254-1-kwolf@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=kwolf@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1761309120863158500 Content-Type: text/plain; charset="utf-8" Patches to expose the limits in QAPI have made clear that the existing documentation of BlockLimits could be improved: The meaning of min_mem_alignment and opt_mem_alignment could be clearer, and talking about better alignment values isn't helpful when we only detect these values and never choose them. Make the changes in the BlockLimits documentation now, so that the patches exposing the fields in QAPI can use descriptions consistent with it. Signed-off-by: Kevin Wolf Reviewed-by: Eric Blake --- include/block/block_int-common.h | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/include/block/block_int-common.h b/include/block/block_int-com= mon.h index 034c0634c8..5206f32d53 100644 --- a/include/block/block_int-common.h +++ b/include/block/block_int-common.h @@ -817,10 +817,10 @@ typedef struct BlockLimits { int64_t max_pdiscard; =20 /* - * Optimal alignment for discard requests in bytes. A power of 2 - * is best but not mandatory. Must be a multiple of - * bl.request_alignment, and must be less than max_pdiscard if - * that is set. May be 0 if bl.request_alignment is good enough + * Optimal alignment for discard requests in bytes. Note that this doe= sn't + * have to be a power of two. Must be a multiple of bl.request_alignme= nt, + * and must be less than max_pdiscard if that is set. May be 0 if + * bl.request_alignment is good enough. */ uint32_t pdiscard_alignment; =20 @@ -831,11 +831,10 @@ typedef struct BlockLimits { int64_t max_pwrite_zeroes; =20 /* - * Optimal alignment for write zeroes requests in bytes. A power - * of 2 is best but not mandatory. Must be a multiple of - * bl.request_alignment, and must be less than max_pwrite_zeroes - * if that is set. May be 0 if bl.request_alignment is good - * enough + * Optimal alignment for write zeroes requests in bytes. Note that this + * doesn't have to be a power of two. Must be a multiple of + * bl.request_alignment, and must be less than max_pwrite_zeroes if th= at is + * set. May be 0 if bl.request_alignment is good enough. */ uint32_t pwrite_zeroes_alignment; =20 @@ -863,18 +862,23 @@ typedef struct BlockLimits { uint64_t max_hw_transfer; =20 /* - * Maximal number of scatter/gather elements allowed by the hardware. + * Maximum number of scatter/gather elements allowed by the hardware. * Applies whenever transfers to the device bypass the kernel I/O * scheduler, for example with SG_IO. If larger than max_iov * or if zero, blk_get_max_hw_iov will fall back to max_iov. */ int max_hw_iov; =20 - - /* memory alignment, in bytes so that no bounce buffer is needed */ + /* + * Minimal required memory alignment in bytes for zero-copy I/O to suc= ceed. + * For unaligned requests, a bounce buffer will be used. + */ size_t min_mem_alignment; =20 - /* memory alignment, in bytes, for bounce buffer */ + /* + * Optimal memory alignment in bytes. This is the alignment used for a= ny + * buffer allocations QEMU performs internally. + */ size_t opt_mem_alignment; =20 /* maximum number of iovec elements */ --=20 2.51.0