From patchwork Fri May 25 03:46:21 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ming Lei X-Patchwork-Id: 10426157 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 100A0602D6 for ; Fri, 25 May 2018 03:53:03 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 00FC5295A6 for ; Fri, 25 May 2018 03:53:03 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id E9DBC295B3; Fri, 25 May 2018 03:53:02 +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=-7.9 required=2.0 tests=BAYES_00, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=unavailable version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A26D7295A6 for ; Fri, 25 May 2018 03:53:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S935953AbeEYDwy (ORCPT ); Thu, 24 May 2018 23:52:54 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:43604 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S933328AbeEYDwx (ORCPT ); Thu, 24 May 2018 23:52:53 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 9F6BEC12C4; Fri, 25 May 2018 03:52:52 +0000 (UTC) Received: from localhost (ovpn-12-30.pek2.redhat.com [10.72.12.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id C9EA72166BB2; Fri, 25 May 2018 03:52:44 +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 , Ming Lei Subject: [RESEND PATCH V5 33/33] block: document usage of bio iterator helpers Date: Fri, 25 May 2018 11:46:21 +0800 Message-Id: <20180525034621.31147-34-ming.lei@redhat.com> In-Reply-To: <20180525034621.31147-1-ming.lei@redhat.com> References: <20180525034621.31147-1-ming.lei@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.1]); Fri, 25 May 2018 03:52:52 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.1]); Fri, 25 May 2018 03:52:52 +0000 (UTC) for IP:'10.11.54.6' DOMAIN:'int-mx06.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'ming.lei@redhat.com' RCPT:'' Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org 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 | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.txt index b4d238b8d9fc..32a6643caeca 100644 --- a/Documentation/block/biovecs.txt +++ b/Documentation/block/biovecs.txt @@ -117,3 +117,35 @@ 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 which name has suffix of "_all" can only be used on +non-BIO_CLONED bio, and ususally they are used by filesystem code, and driver +shouldn't use them becasue bio may have been splitted before they got to the +driver: + + bio_for_each_segment_all() + bio_for_each_page_all() + bio_pages_all() + bio_first_bvec_all() + bio_first_page_all() + bio_last_bvec_all() + segment_for_each_page_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 +itearation: + + bio_for_each_page() + bio_for_each_page_all() + segment_for_each_page_all() + +* The following helpers iterate bio segment by segment, and each segment may +include multiple physically contiguous pages, and the local variable of +'struct bio_vec' or the reference records multi page io vector during the +itearation: + + bio_for_each_segment() + bio_for_each_segment_all()