From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S1751912AbbIEMkp (ORCPT <rfc822;w@1wt.eu>);
	Sat, 5 Sep 2015 08:40:45 -0400
Received: from aserp1040.oracle.com ([141.146.126.69]:43493 "EHLO
	aserp1040.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
	with ESMTP id S1750810AbbIEMkg (ORCPT
	<rfc822;linux-kernel@vger.kernel.org>);
	Sat, 5 Sep 2015 08:40:36 -0400
From: Bob Liu <bob.liu@oracle.com>
To: xen-devel@lists.xen.org
Cc: david.vrabel@citrix.com, linux-kernel@vger.kernel.org,
        roger.pau@citrix.com, konrad.wilk@oracle.com,
        felipe.franciosi@citrix.com, axboe@fb.com, hch@infradead.org,
        avanzini.arianna@gmail.com, rafal.mielniczuk@citrix.com,
        boris.ostrovsky@oracle.com, jonathan.davies@citrix.com,
        Bob Liu <bob.liu@oracle.com>
Subject: [PATCH v3 2/9] xen-block: add document for mutli hardware queues/rings
Date: Sat,  5 Sep 2015 20:39:35 +0800
Message-Id: <1441456782-31318-3-git-send-email-bob.liu@oracle.com>
X-Mailer: git-send-email 1.7.10.4
In-Reply-To: <1441456782-31318-1-git-send-email-bob.liu@oracle.com>
References: <1441456782-31318-1-git-send-email-bob.liu@oracle.com>
X-Source-IP: userv0021.oracle.com [156.151.31.71]
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Document multi queues/rings of xen-block.

Signed-off-by: Bob Liu <bob.liu@oracle.com>
---
 include/xen/interface/io/blkif.h |   32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/include/xen/interface/io/blkif.h b/include/xen/interface/io/blkif.h
index c33e1c4..b453b70 100644
--- a/include/xen/interface/io/blkif.h
+++ b/include/xen/interface/io/blkif.h
@@ -28,6 +28,38 @@ typedef uint16_t blkif_vdev_t;
 typedef uint64_t blkif_sector_t;
 
 /*
+ * Multiple hardware queues/rings:
+ * If supported, the backend will write the key "multi-queue-max-queues" to
+ * the directory for that vbd, and set its value to the maximum supported
+ * number of queues.
+ * Frontends that are aware of this feature and wish to use it can write the
+ * key "multi-queue-num-queues", set to the number they wish to use, which
+ * must be greater than zero, and no more than the value reported by the backend
+ * in "multi-queue-max-queues".
+ *
+ * For frontends requesting just one queue, the usual event-channel and
+ * ring-ref keys are written as before, simplifying the backend processing
+ * to avoid distinguishing between a frontend that doesn't understand the
+ * multi-queue feature, and one that does, but requested only one queue.
+ *
+ * Frontends requesting two or more queues must not write the toplevel
+ * event-channeland ring-ref keys, instead writing those keys under sub-keys
+ * having the name "queue-N" where N is the integer ID of the queue/ring for
+ * which those keys belong. Queues are indexed from zero.
+ * For example, a frontend with two queues must write the following set of
+ * queue-related keys:
+ *
+ * /local/domain/1/device/vbd/0/multi-queue-num-queues = "2"
+ * /local/domain/1/device/vbd/0/queue-0 = ""
+ * /local/domain/1/device/vbd/0/queue-0/ring-ref = "<ring-ref>"
+ * /local/domain/1/device/vbd/0/queue-0/event-channel = "<evtchn>"
+ * /local/domain/1/device/vbd/0/queue-1 = ""
+ * /local/domain/1/device/vbd/0/queue-1/ring-ref = "<ring-ref>"
+ * /local/domain/1/device/vbd/0/queue-1/event-channel = "<evtchn>"
+ *
+ */
+
+/*
  * REQUEST CODES.
  */
 #define BLKIF_OP_READ              0
-- 
1.7.10.4