From patchwork Fri Sep 21 20:34:46 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bart Van Assche X-Patchwork-Id: 10610963 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id B9E48112B for ; Fri, 21 Sep 2018 20:35:13 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A76602E7A5 for ; Fri, 21 Sep 2018 20:35:13 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 997F12E7AF; Fri, 21 Sep 2018 20:35:13 +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.8 required=2.0 tests=BAYES_00,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI,T_DKIM_INVALID autolearn=ham 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 F03532E7A5 for ; Fri, 21 Sep 2018 20:35:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2391307AbeIVCZo (ORCPT ); Fri, 21 Sep 2018 22:25:44 -0400 Received: from out002.mailprotect.be ([83.217.72.86]:53125 "EHLO out002.mailprotect.be" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2390726AbeIVCZo (ORCPT ); Fri, 21 Sep 2018 22:25:44 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=mailprotect.be; s=mail; h=Content-Transfer-Encoding:MIME-Version:Message-Id :Date:Subject:Cc:To:From:reply-to:sender:bcc:in-reply-to:references: content-type; bh=IhBwacimTSvNFfiw2WIgXpuwlfoZ8A6MGODdj5QeBy0=; b=dGX1GjmDxEzY kkWCIrJuZSnrL5c/nPj9Karyb/0s/Kjlw+Kpo5yMRuvbLl3+ox3PxLsWE48N45+jjyYNUn/b+38bB Ho30CC1CBARABNp2gKojYfZwJ2vLRKIYEpVZm1DLB4oc/0RE2JVX9gzQZXul+TFSBgRo6AUOrh2UL Czma3XWRb022ldPvSVnmDUhI6s4skamlIapE/f+z5qsf8lu7uopXuUfwyIiL+UDDFT3XxOgAGXiln XT1Tqzl3i8nkxS3wcT/TLbu74o+xiH7DvsFQmZDQZorN56+ESl0T9/zIK4CNmbwXMYVBSMs+m4IVW kjcr5TKcik0Zgb+g0pLa2Q==; Received: from smtp-auth.mailprotect.be ([178.208.39.155]) by com-mpt-out002.mailprotect.be with esmtp (Exim 4.89) (envelope-from ) id 1g3S8m-0009E3-PP; Fri, 21 Sep 2018 22:35:05 +0200 Received: from desktop-bart.svl.corp.google.com (unknown [104.133.8.89]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp-auth.mailprotect.be (Postfix) with ESMTPSA id 0C60DC05E8; Fri, 21 Sep 2018 22:35:02 +0200 (CEST) From: Bart Van Assche To: Jens Axboe Cc: linux-block@vger.kernel.org, Christoph Hellwig , Bart Van Assche , Ming Lei , Jianchao Wang , Hannes Reinecke Subject: [PATCH v2] blk-mq: Document the functions that iterate over requests Date: Fri, 21 Sep 2018 13:34:46 -0700 Message-Id: <20180921203446.50541-1-bvanassche@acm.org> X-Mailer: git-send-email 2.19.0.444.g18242da7ef-goog MIME-Version: 1.0 X-Originating-IP: 178.208.39.155 X-SpamExperts-Domain: mailprotect.be X-SpamExperts-Username: 178.208.39.128/27 Authentication-Results: mailprotect.be; auth=pass smtp.auth=178.208.39.128/27@mailprotect.be X-SpamExperts-Outgoing-Class: ham X-SpamExperts-Outgoing-Evidence: Combined (0.06) X-Recommended-Action: accept X-Filter-ID: EX5BVjFpneJeBchSMxfU5lxPTBgphtmqQXg4IiL4Rx5602E9L7XzfQH6nu9C/Fh9KJzpNe6xgvOx q3u0UDjvO1tLifGj39bI0bcPyaJsYTaOqZpfO3PVJjdazu3l6Zm3CrxbKqqxVb1b/D8J7mjn9ilV cTJ2PzGYt6C/dLANFNC9eBrzwetNxEiSKDRqnfKMchy245qaCGq3TeWvoSybAt5ZBZ2f8Z/psVOj OL3ZCmxiDKqBZt+RmZBAoK6NQJjaVp7WPywSoBmEqvfQgs/XPKExp+t6xDxCrwB74FlhsbVBpc/A iUjjK788fU1YN0ZF92/D/BjhGANPyPkzeJiqdaNC0PpwOV6SFcEdeyqLTjyE0xjF6dsTRoHhG8aQ N7LrRchVnrL31hEN27oXUXX97IY81H0aFIAPf0OWDj9gA/aw2Nu8WYjpk1Kk9QbuPdIsLaGN5WBh mfRSYvk+FCkc5mfDqJPXXQOUUzZFhjNWLUSFs5ZZrz9c88D+kBbOzVSeRAwX31WVY5lWjWxuGSRu xQRTOzXtAFqmlXKuoIRKQUXJWpF10FaRlitjRBYDhWErqRd6WieF7oa3pi5AXxG7O7wqyT5p50x8 1ZKcmzCu2U0MYXjcg+ubAS2aK8x2z/k9c/DXtHJOj+IrynVpkScfoDYmeia6OdwdbV7tRBaP0E7u DFeHsKFQTpBp9R1uNwjHsFdDzqgpYxz1gf6QkX8e0GiH1Wgh6RAenBR+licROGZg1O8eK4R4qHG6 QTLxSJR2/h2Amb+vW26kupNW5oxcZi99x8RhCQjRhbCNZXXvwaabx378FvdOVl+Nb14Iux6ZJaUh D7vchngIwfZsyzeNkVPrerClVGpV+33LuLT1d6aLBDMrD7q/cJogwbqzsuokQn9L13hwqq/Kpmrt Csfc8s/hvMooY9beeDYzOMSMGiAMdYTry9nTdJvho3e/BB8kFZBt1eugw95QTItIeeH6s2bjO41F yBEqIaDudcVplPHrW4f10UKD7BhDyH0dji1mFiP14vQusCQKKNH5Uhvre9bjhHdGDk23I3DRRLBo sIUZqJNdbvPaUyoCdu6Y7CHSp9cgmo7MsDGVTbSSdhQQLqd4DkMeE6vLWiswimQ+UQiGpS+C6BPA IEs8PiiVo3Eb4WEXGR/0smTWjW9+vScyJiv1hoYQcdpBWDBalfTrXFTYzd7SyrNgso6MqW98yhpd X-Report-Abuse-To: spam@com-mpt-mgt001.mailprotect.be Sender: linux-block-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Make it easier to understand the purpose of the functions that iterate over requests by documenting their purpose. Fix several minor spelling and grammer mistakes in comments in these functions. Signed-off-by: Bart Van Assche Reviewed-by: Johannes Thumshirn Cc: Christoph Hellwig Cc: Ming Lei Cc: Jianchao Wang Cc: Hannes Reinecke --- Changes compared to v1: converted to kernel-doc format. block/blk-mq-tag.c | 71 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 7 deletions(-) diff --git a/block/blk-mq-tag.c b/block/blk-mq-tag.c index 94e1ed667b6e..40d1667bceac 100644 --- a/block/blk-mq-tag.c +++ b/block/blk-mq-tag.c @@ -232,13 +232,26 @@ static bool bt_iter(struct sbitmap *bitmap, unsigned int bitnr, void *data) /* * We can hit rq == NULL here, because the tagging functions - * test and set the bit before assining ->rqs[]. + * test and set the bit before assigning ->rqs[]. */ if (rq && rq->q == hctx->queue) iter_data->fn(hctx, rq, iter_data->data, reserved); return true; } +/** + * bt_for_each - iterate over the requests associated with a hardware queue + * @hctx: Hardware queue to examine. + * @bt: sbitmap to examine. This is either the breserved_tags member + * or the bitmap_tags member of struct blk_mq_tags. + * @fn: Pointer to the function that will be called for each request + * associated with @hctx that has been assigned a driver tag. + * @fn will be called as follows: @fn(@hctx, rq, @data, @reserved) + * where rq is a pointer to a request. + * @data: Will be passed as third argument to @fn. + * @reserved: Indicates whether @bt is the breserved_tags member or the + * bitmap_tags member of struct blk_mq_tags. + */ static void bt_for_each(struct blk_mq_hw_ctx *hctx, struct sbitmap_queue *bt, busy_iter_fn *fn, void *data, bool reserved) { @@ -280,6 +293,18 @@ static bool bt_tags_iter(struct sbitmap *bitmap, unsigned int bitnr, void *data) return true; } +/** + * bt_tags_for_each - iterate over the requests in a tag map + * @tags: Tag map to iterate over. + * @bt: sbitmap to examine. This is either the breserved_tags member + * or the bitmap_tags member of struct blk_mq_tags. + * @fn: Pointer to the function that will be called for each started + * request. @fn will be called as follows: @fn(rq, @data, + * @reserved) where rq is a pointer to a request. + * @data: Will be passed as second argument to @fn. + * @reserved: Indicates whether @bt is the breserved_tags member or the + * bitmap_tags member of struct blk_mq_tags. + */ static void bt_tags_for_each(struct blk_mq_tags *tags, struct sbitmap_queue *bt, busy_tag_iter_fn *fn, void *data, bool reserved) { @@ -294,6 +319,15 @@ static void bt_tags_for_each(struct blk_mq_tags *tags, struct sbitmap_queue *bt, sbitmap_for_each_set(&bt->sb, bt_tags_iter, &iter_data); } +/** + * blk_mq_all_tag_busy_iter - iterate over all started requests in a tag map + * @tags: Tag map to iterate over. + * @fn: Pointer to the function that will be called for each started + * request. @fn will be called as follows: @fn(rq, @priv, + * reserved) where rq is a pointer to a request. 'reserved' + * indicates whether or not @rq is a reserved request. + * @priv: Will be passed as second argument to @fn. + */ static void blk_mq_all_tag_busy_iter(struct blk_mq_tags *tags, busy_tag_iter_fn *fn, void *priv) { @@ -302,6 +336,15 @@ static void blk_mq_all_tag_busy_iter(struct blk_mq_tags *tags, bt_tags_for_each(tags, &tags->bitmap_tags, fn, priv, false); } +/** + * blk_mq_tagset_busy_iter - iterate over all started requests in a tag set + * @tagset: Tag set to iterate over. + * @fn: Pointer to the function that will be called for each started + * request. @fn will be called as follows: @fn(rq, @priv, + * reserved) where rq is a pointer to a request. 'reserved' + * indicates whether or not @rq is a reserved request. + * @priv: Will be passed as second argument to @fn. + */ void blk_mq_tagset_busy_iter(struct blk_mq_tag_set *tagset, busy_tag_iter_fn *fn, void *priv) { @@ -314,6 +357,20 @@ void blk_mq_tagset_busy_iter(struct blk_mq_tag_set *tagset, } EXPORT_SYMBOL(blk_mq_tagset_busy_iter); +/** + * blk_mq_queue_tag_busy_iter - iterate over all requests with a driver tag + * @q: Request queue to examine. + * @fn: Pointer to the function that will be called for each request + * on @q. @fn will be called as follows: @fn(hctx, rq, @priv, + * reserved) where rq is a pointer to a request and hctx points + * to the hardware queue associated with the request. 'reserved' + * indicates whether or not @rq is a reserved request. + * @priv: Will be passed as third argument to @fn. + * + * Note: if @q->tag_set is shared with other request queues then @fn will be + * called for all requests on all queues that share that tag set and not only + * for requests associated with @q. + */ void blk_mq_queue_tag_busy_iter(struct request_queue *q, busy_iter_fn *fn, void *priv) { @@ -321,11 +378,11 @@ void blk_mq_queue_tag_busy_iter(struct request_queue *q, busy_iter_fn *fn, int i; /* - * __blk_mq_update_nr_hw_queues will update the nr_hw_queues and - * queue_hw_ctx after freeze the queue. So we could use q_usage_counter - * to avoid race with it. __blk_mq_update_nr_hw_queues will users - * synchronize_rcu to ensure all of the users go out of the critical - * section below and see zeroed q_usage_counter. + * __blk_mq_update_nr_hw_queues() updates nr_hw_queues and queue_hw_ctx + * while the queue is frozen. So we can use q_usage_counter to avoid + * racing with it. __blk_mq_update_nr_hw_queues() uses + * synchronize_rcu() to ensure this function left the critical section + * below. */ rcu_read_lock(); if (percpu_ref_is_zero(&q->q_usage_counter)) { @@ -337,7 +394,7 @@ void blk_mq_queue_tag_busy_iter(struct request_queue *q, busy_iter_fn *fn, struct blk_mq_tags *tags = hctx->tags; /* - * If not software queues are currently mapped to this + * If no software queues are currently mapped to this * hardware queue, there's nothing to check */ if (!blk_mq_hw_queue_mapped(hctx))