From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.codeaurora.org by pdx-caf-mail.web.codeaurora.org (Dovecot) with LMTP id 1hpAO77JG1uCPwAAmS7hNA ; Sat, 09 Jun 2018 12:36:18 +0000 Received: by smtp.codeaurora.org (Postfix, from userid 1000) id D78CB607BB; Sat, 9 Jun 2018 12:36:18 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on pdx-caf-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI autolearn=unavailable autolearn_force=no version=3.4.0 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by smtp.codeaurora.org (Postfix) with ESMTP id 7012C602FC; Sat, 9 Jun 2018 12:36:18 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 smtp.codeaurora.org 7012C602FC Authentication-Results: pdx-caf-mail.web.codeaurora.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: pdx-caf-mail.web.codeaurora.org; spf=none smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753553AbeFIMgQ (ORCPT + 25 others); Sat, 9 Jun 2018 08:36:16 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:38402 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1753388AbeFIMgN (ORCPT ); Sat, 9 Jun 2018 08:36:13 -0400 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:'' Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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() -- 2.9.5