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: 10426153 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 9E754602D8 for ; Fri, 25 May 2018 03:52:55 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8DC63295A6 for ; Fri, 25 May 2018 03:52:55 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 81A0D295B3; Fri, 25 May 2018 03:52:55 +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 183B2295A6 for ; Fri, 25 May 2018 03:52:55 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id EE21F6B02CC; Thu, 24 May 2018 23:52:53 -0400 (EDT) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id EB88D6B02CE; Thu, 24 May 2018 23:52:53 -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 DCFE66B02CF; Thu, 24 May 2018 23:52:53 -0400 (EDT) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from mail-qt0-f200.google.com (mail-qt0-f200.google.com [209.85.216.200]) by kanga.kvack.org (Postfix) with ESMTP id B059E6B02CC for ; Thu, 24 May 2018 23:52:53 -0400 (EDT) Received: by mail-qt0-f200.google.com with SMTP id g12-v6so2792844qtj.22 for ; Thu, 24 May 2018 20:52:53 -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=Q8hZ/a/GKODRUZtZw2nxIkPAEeJoO2hDsp2SzrPAukE=; b=ukqUuo5LzngswYjZAP8th18zivl77gv+azzz1Tw8kOBDS+ea33sYp2kJwDC+vSZn2R BZ6ta6I9RRltqzt1mjCb9OGq9i1YaTlEz2XjgrVU8rDJtaE/T7Dk1XWKSsiU5MXa3KNn aFn51Gz++IFOQVSDQDx/19ClvadOZEtBaUhQniKdtDw5qCdERSBAs61NiFt+/D3q+r8Q JqRYIlkD/HeBJxEhzQ8kbPp/cijRvSDaH2WyWfz+yr0Lm1SMQCf4aM1sXZ67sUJwU9Rb ju8h3Ui1EojACUzXGcwjoIKlC66KVJA5d4NWK2+BqPvFYr/zcWdbbKQkNWYEH9uctShR 8VoQ== 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: ALKqPwdziequ4sbHBa+p/+gH99VReINp5B5t0X3gE8+eRKK9EAT27J8k PY9gxQn7QOw7nGL6P+gH2B1BnlBaZeyqg7qdVIQei0kxFxZ9SqktdQK//qjGRoprK/7bQ94n9Fo vEuqEx4CJlIsMS0/YB+WvrNjLxdCSMoB/pt6oLbKRccGd2jR5k4lIZv9/2gpHkU+nCg== X-Received: by 2002:a0c:b0a3:: with SMTP id o32-v6mr611781qvc.246.1527220373522; Thu, 24 May 2018 20:52:53 -0700 (PDT) X-Google-Smtp-Source: ADUXVKLdBj1LN/QZktMarVA08k/L+ywz3g4OqwKrlieOEOC1SuDz1P7W8PGujT4AtXxEwFKgC+vA X-Received: by 2002:a0c:b0a3:: with SMTP id o32-v6mr611765qvc.246.1527220373020; Thu, 24 May 2018 20:52:53 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1527220372; cv=none; d=google.com; s=arc-20160816; b=Ek6qXME9lfo27Beenifv0P5+I4CqZmoCjwJ+NaA6Gy6HmvX+7hXmeIAFG6AnqKR9oN CoHqRFMbEpTKPmNlahC6o/NPGVf6/6RxE4qsTvUcpH2ApZERoZu/xgHg3kcJNetIDR4X b6c4RKYvrdbgtFpFBXz+aCKN3NfWNL6D3HmTXHzDn8oMPvMbTZxzvhgIPQrVysyTPZ4r JsrOJSpwGC4j5NSDLMeeejMj+fRucy29VMFWISXFon1TApkC3bZqSw5gaKX8coEvLXB3 5CO8/UGF9lESZLViSPBPCDGogbFMsQuM4jsxochBFTPOATzDOxFWNd7Hluy8T0mBucpO brZw== 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=Q8hZ/a/GKODRUZtZw2nxIkPAEeJoO2hDsp2SzrPAukE=; b=JdENsTjxXyaU3ZX3aJdIcAuAl2O7eGSC/lkTiYOnOPBakS/xQIWGax8p44l/ARbbYP bx3+0NFC3OUrFhpgUpiW/+LcfHHrQHv1gJIBk9i0B42vbanSYrP3vqoRX0slcNWr6iz4 vTRe7HBflucFX67W4S0iUrZBQNfQx9RZAR2NqK0sAWHCBJAkXohn95o3RM9YvM5eQccU giqHzY9N1Xhw/8s9AhxKiSXPLt66Pd4HsYT9fPoVa3re/heUl5ZnwdeN22UMwuC/+6T5 xqeiMkrXintWsK3B+PLEHPN7onhyYFQwRl+IMXb9fBFIFh/QYdIjc11G+LVbB0QbsBGV kCxg== 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 63-v6si5192788qkz.182.2018.05.24.20.52.52 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 24 May 2018 20:52:52 -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-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:'' 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 | 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()