From patchwork Sat Jun 9 12:30:14 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ming Lei X-Patchwork-Id: 10455651 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id EF742601F7 for ; Sat, 9 Jun 2018 12:36:15 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DF8071FF83 for ; Sat, 9 Jun 2018 12:36:15 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D4513223A6; Sat, 9 Jun 2018 12:36:15 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.9 required=2.0 tests=BAYES_00, MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 71B9B1FF83 for ; Sat, 9 Jun 2018 12:36:15 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 7700B6B029C; Sat, 9 Jun 2018 08:36:14 -0400 (EDT) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id 7209A6B029E; Sat, 9 Jun 2018 08:36:14 -0400 (EDT) X-Original-To: int-list-linux-mm@kvack.org X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 637216B029F; Sat, 9 Jun 2018 08:36:14 -0400 (EDT) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from mail-qk0-f197.google.com (mail-qk0-f197.google.com [209.85.220.197]) by kanga.kvack.org (Postfix) with ESMTP id 39D846B029C for ; Sat, 9 Jun 2018 08:36:14 -0400 (EDT) Received: by mail-qk0-f197.google.com with SMTP id l29-v6so15557627qkh.1 for ; Sat, 09 Jun 2018 05:36:14 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-original-authentication-results:x-gm-message-state:from:to:cc :subject:date:message-id:in-reply-to:references; bh=lRfQ7fIEPfr2sLnMmoppNJZNzi9lzi/nped66Q6OpiU=; b=k4F6ru3sZ0e4wjTXr73nBNH+6lxjQDmKLIvzty11cKTPOsiwhE6uL5iVfV5dC8r6DZ tEOPd1mdKeVt2TlhlPQeHpHh08TXEgFYylV1zgOyyBki0HN6ni+gVQFyfTauv7fEL3IO 9gSN72xYHc3YgjL/f0LtgRvj1d+aWviH2EA5k4NVG+d9WrbImvwB6s8XDBMpSYfxJTYK 1aVCyQAlQLu9sMiF+IHx01eGKxqFFaF+lzGPelsVS7Oxu+6vkMaYsbgyy9HOYE7EP1Mw hyrxyvVNZ3cfVDMBB6fs6RJn5CuX8KLDOVXbUiBumhZ3bGby4dxaDGI3jzwUfEN21uKt Enyg== X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of ming.lei@redhat.com designates 66.187.233.73 as permitted sender) smtp.mailfrom=ming.lei@redhat.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=redhat.com X-Gm-Message-State: APt69E0gFmqfUBBxxO5Qc/5OmziD8SlTFfmGgffGZb2/314PUPq0WueX 3tijdpc/xrJzNpDMP700z6DR5tu1O8dDnNW6ukceELCNK6WWQWAYj4PSsTFCOxTbnIK4mz5/Zth 61o8SEkHStJau64INea1sU+dTfYryFWrbEDs584Z7FYgujquJs9+CQE3mm0N1Q4EfOw== X-Received: by 2002:ac8:163a:: with SMTP id p55-v6mr9151031qtj.157.1528547774029; Sat, 09 Jun 2018 05:36:14 -0700 (PDT) X-Google-Smtp-Source: ADUXVKLSnOAe+UjOW2stXTx8NGOOhJAoyK11Fo9NAJ7Xmqiqh+WV8Rxgf7qmVEkPQTFGgi8cUJOQ X-Received: by 2002:ac8:163a:: with SMTP id p55-v6mr9151015qtj.157.1528547773437; Sat, 09 Jun 2018 05:36:13 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1528547773; cv=none; d=google.com; s=arc-20160816; b=q3zhJNF400HQb0vpBDnHmmrpNomIVcEz7d/Q0t8A4FPs+l3h0QSSbijz+V/RN/O1CH Qy1aS5Dzes6yKYTxsnuFpYMSYjLxv9rFJtyzMFQhDmQNpOTGkQpHoYBAEySQggl4FEDE gJ3MwXFl9v0hRNbQmkjVvEwnUng3DdKIBea2mlTd0Ja3sfpxe+KeNJYTBZxmOcF81UO5 cB6O4Dlh35Txf5LVhtQJ2X9/7YoVdtIBq9M+dUezghcAFc1woSqIcznaPXcfdSu0H0m3 63fGnkIPoW8nywb/muUWG+TUCFeY+tJqXrmfBr1CW2uoquGuF9I3l8kwJ1tK3AwK/Lh+ 5ORg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=references:in-reply-to:message-id:date:subject:cc:to:from :arc-authentication-results; bh=lRfQ7fIEPfr2sLnMmoppNJZNzi9lzi/nped66Q6OpiU=; b=KkEmNkO/pG9GIGrXfJZ1NVwXV3qxVKMticUh+ZSEz0oCBnypTo3wFyEPp5aatYsu7T L6p/lJzh4BgYWnXHXE3G3hubU0LCIyZ30eSsukk06dCv+OFvKud8H9gRCglcDy323dgZ PFAW63AVLKlD8SAqxU/RrrKWEhtnL9GwDxfbdHGsza/d0JkKG5fADo7fQnTeGiDC9EmR cKb6W2fmvmmBU0/KewvNUdz1bGTh2TCuzmGQyoAjPJNkUFTUcWJJ7EOJybv0mAD1abFd lHgg//m6CgBKTSSQWafepKHPd5ztDWDT+5JziqPZnGRgKh/3kohsSKWikcUAMaKxDz2P hj4w== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ming.lei@redhat.com designates 66.187.233.73 as permitted sender) smtp.mailfrom=ming.lei@redhat.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from mx1.redhat.com (mx3-rdu2.redhat.com. [66.187.233.73]) by mx.google.com with ESMTPS id v19-v6si2845035qkb.310.2018.06.09.05.36.13 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 09 Jun 2018 05:36:13 -0700 (PDT) Received-SPF: pass (google.com: domain of ming.lei@redhat.com designates 66.187.233.73 as permitted sender) client-ip=66.187.233.73; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ming.lei@redhat.com designates 66.187.233.73 as permitted sender) smtp.mailfrom=ming.lei@redhat.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 04C63818BAF3; Sat, 9 Jun 2018 12:36:13 +0000 (UTC) Received: from localhost (ovpn-12-40.pek2.redhat.com [10.72.12.40]) by smtp.corp.redhat.com (Postfix) with ESMTP id D96A41116709; Sat, 9 Jun 2018 12:36:01 +0000 (UTC) From: Ming Lei To: Jens Axboe , Christoph Hellwig , Alexander Viro , Kent Overstreet Cc: David Sterba , Huang Ying , linux-kernel@vger.kernel.org, linux-block@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-mm@kvack.org, Theodore Ts'o , "Darrick J . Wong" , Coly Li , Filipe Manana , Randy Dunlap , Ming Lei Subject: [PATCH V6 30/30] block: document usage of bio iterator helpers Date: Sat, 9 Jun 2018 20:30:14 +0800 Message-Id: <20180609123014.8861-31-ming.lei@redhat.com> In-Reply-To: <20180609123014.8861-1-ming.lei@redhat.com> References: <20180609123014.8861-1-ming.lei@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Sat, 09 Jun 2018 12:36:13 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Sat, 09 Jun 2018 12:36:13 +0000 (UTC) for IP:'10.11.54.3' DOMAIN:'int-mx03.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'ming.lei@redhat.com' RCPT:'' X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: X-Virus-Scanned: ClamAV using ClamSMTP Now multipage bvec is supported, and some helpers may return page by page, and some may return segment by segment, this patch documents the usage for helping us use them correctly. Signed-off-by: Ming Lei --- Documentation/block/biovecs.txt | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.txt index 25689584e6e0..3ab72566141f 100644 --- a/Documentation/block/biovecs.txt +++ b/Documentation/block/biovecs.txt @@ -117,3 +117,33 @@ Other implications: size limitations and the limitations of the underlying devices. Thus there's no need to define ->merge_bvec_fn() callbacks for individual block drivers. + +Usage of helpers: +================= + +* The following helpers, whose names have the suffix "_all", can only be +used on non-BIO_CLONED bio, and usually they are used by filesystem code, +and driver shouldn't use them because bio may have been split before they +got to the driver: + + bio_for_each_chunk_segment_all() + bio_for_each_chunk_all() + bio_pages_all() + bio_first_bvec_all() + bio_first_page_all() + bio_last_bvec_all() + +* The following helpers iterate bio page by page, and the local variable of +'struct bio_vec' or the reference records single page io vector during the +iteration: + + bio_for_each_segment() + bio_for_each_segment_all() + +* The following helpers iterate bio chunk by chunk, and each chunk may +include multiple physically contiguous pages, and the local variable of +'struct bio_vec' or the reference records multi page io vector during the +iteration: + + bio_for_each_chunk() + bio_for_each_chunk_all()