From patchwork Wed Jun 27 12:45:48 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ming Lei X-Patchwork-Id: 10491465 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 9331A602B3 for ; Wed, 27 Jun 2018 12:50:53 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8209528E54 for ; Wed, 27 Jun 2018 12:50:53 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 7F5AF28E98; Wed, 27 Jun 2018 12:50:53 +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 1196228E9D for ; Wed, 27 Jun 2018 12:50:53 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 1CD6C6B0298; Wed, 27 Jun 2018 08:50:52 -0400 (EDT) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id 17D8D6B0299; Wed, 27 Jun 2018 08:50:52 -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 06CDE6B029A; Wed, 27 Jun 2018 08:50:52 -0400 (EDT) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from mail-qt0-f198.google.com (mail-qt0-f198.google.com [209.85.216.198]) by kanga.kvack.org (Postfix) with ESMTP id D527A6B0298 for ; Wed, 27 Jun 2018 08:50:51 -0400 (EDT) Received: by mail-qt0-f198.google.com with SMTP id 12-v6so1792215qtq.8 for ; Wed, 27 Jun 2018 05:50:51 -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=AtcimxthIaVCGJL56bpnJ5osFyv2NY61aRfqkoMfQ9c=; b=qeTZEN5DBPptt0C6PqupdY2YIFTWZJXHnTvHJPYlQ85ju+qEF0r0Vpb3M5VJ4IDbRe PV+TT3iLDJGLPgD62OHM/CwphKs+nY/C6Q02vdlzQQcBZgOwLeXpfuPrP+P4CbG5iS+s veUxeGVxB2X/edhkJIGrXslp9HYi8hCXhKQOW1Tf265pD9z05UmurNP6IlODAMkHU/4B V3mSXnmqzqX9FCWqRLrM2bMMqnHB4iYPa3mRZf9ih/MDdaFWx0L6Xm/g2aAVMq6Xju8D hRDR5CxHwPEO4NnjRVlumLTwD0N8HukQl1xztbWIbC84xaDGrDuFuskmYbK4vXX+v2uX wuyg== 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: APt69E0iQIMoqevmtGX7tEDTRVsQYCmyE54ZHZnRRguBCFwtfgPszbOW nRk7Kc+Hhv+GGh65+X8SQw5dC7it0UfnUohDVjyzv4cJ2gzOQ48pF2ST4LNLt9hbDQ+N1+3bv8Y kuQmJsB1oh09xjkR6gkaDMLme6KGoQ686ObNmJC8sCVIOQUaat4kRgwTu2EmR/TUDCA== X-Received: by 2002:a37:8ec4:: with SMTP id q187-v6mr5058172qkd.28.1530103851644; Wed, 27 Jun 2018 05:50:51 -0700 (PDT) X-Google-Smtp-Source: AAOMgpfXvmOSCUeRJ1dELDikz1DzIDuISP6qyXVPO2UXxZblgGgjqZ2MMCJ5U4ovefAfNV3PweOf X-Received: by 2002:a37:8ec4:: with SMTP id q187-v6mr5058135qkd.28.1530103850969; Wed, 27 Jun 2018 05:50:50 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1530103850; cv=none; d=google.com; s=arc-20160816; b=X/xsvMYbnOuzi6W5gkZTnPeHnEZfK9lq2viTP9bnck6XqHH6QfAnm9xIJbnTiUm4uc ucFWNg3u+Kmkp1lApCq//wKdmKJAPuxQBxtQ824aPBZBcbh+wdRg2XfkP26w0yi0Cg4m WQmTyuD+I1D0KAkpN8XMQgFS02XzxjgzMDk2vfdrtdo8JszMUHOf5n0r0H9Vcp2VpYPm 1s7Ju5ID74MePVAXLgNBBexFF15EEn1tG5gMON7Y22WdvaewLw4r7vePh1DOTGpvZ87M v0fJDisyZn7NmjOLEO+uzF1oI7M6o94Z7RusbYUsisWEZ0X7Cvb5E+zZ7FuI/B1UYsMJ u64w== 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=AtcimxthIaVCGJL56bpnJ5osFyv2NY61aRfqkoMfQ9c=; b=Wk+qZr4JKwsdOoBSx9XOSYdbE/S6YfQDO6m1Ag2gnmdkwL2qeF2oMKVXDpSvwK91oO iYZVI7nvjDBGV/oA1hDvZbYIdEQswdjFYadlZnp35oPDhpbEg/vaLOw46MMDX0BEu7do PTBp/jx7G8w6Mn1Hj8v8brzQEP5SGFLZ1xTtGq0GD0SJHpwFAam3LjJAIVhTDycnSkKW 2/TygGsI7E4hQtRzvmEnq3vXcd5DpN5HHhOtuzPP/VWSnL0aZMxdI/TF/1IDz4oQqk8L Ywm0SBxqDm90K7wS+5h11eXFYEAlmHYaVWNEII6p/R5LgDXuRvl0cvUUHiBDQPw3kfUn JaeA== 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 n10-v6si3941819qtn.198.2018.06.27.05.50.50 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 27 Jun 2018 05:50:50 -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-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 9ACD4BF578; Wed, 27 Jun 2018 12:50:50 +0000 (UTC) Received: from localhost (ovpn-12-44.pek2.redhat.com [10.72.12.44]) by smtp.corp.redhat.com (Postfix) with ESMTP id 857AA1C5B9; Wed, 27 Jun 2018 12:50:39 +0000 (UTC) From: Ming Lei To: Jens Axboe , Christoph Hellwig , Kent Overstreet Cc: David Sterba , Huang Ying , Mike Snitzer , 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 V7 24/24] block: document usage of bio iterator helpers Date: Wed, 27 Jun 2018 20:45:48 +0800 Message-Id: <20180627124548.3456-25-ming.lei@redhat.com> In-Reply-To: <20180627124548.3456-1-ming.lei@redhat.com> References: <20180627124548.3456-1-ming.lei@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.11.54.5 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.2]); Wed, 27 Jun 2018 12:50:50 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.2]); Wed, 27 Jun 2018 12:50:50 +0000 (UTC) for IP:'10.11.54.5' DOMAIN:'int-mx05.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 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.txt index 25689584e6e0..f63af564ae89 100644 --- a/Documentation/block/biovecs.txt +++ b/Documentation/block/biovecs.txt @@ -117,3 +117,30 @@ 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_first_bvec_all() + bio_first_page_all() + bio_last_bvec_all() + +* The following helpers iterate over singlepage bvec, and the local +variable of 'struct bio_vec' or the reference records single page io +vector during the itearation: + + bio_for_each_segment() + bio_for_each_segment_all() + +* The following helper iterates over multipage bvec, and each bvec 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_bvec()