Lines Matching +full:4 +full:- +full:ring
4 * Unified block-device I/O interface for Xen guest OSes.
24 * Copyright (c) 2003-2004, Keir Fraser
31 #include "ring.h"
35 * Front->back notifications: When enqueuing a new request, sending a
37 * hold-off mechanism provided by the ring macros). Backends must set
40 * Back->front notifications: When enqueuing a new response, sending a
42 * hold-off mechanism provided by the ring macros). Frontends must set
80 *------------------ Backend Device Identification (PRIVATE) ------------------
95 * physical-device
102 * physical-device-path
115 * direct-io-safe
121 * https://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html
136 *--------------------------------- Features ---------------------------------
138 * feature-barrier
147 * feature-flush-cache
156 * feature-discard
165 * feature-persistent
181 * and fall back to non-persistent mode. Backend implementations may
193 *----------------------- Request Transport Parameters ------------------------
195 * max-ring-page-order
200 * The maximum supported size of the request ring buffer in units of
201 * lb(machine pages). (e.g. 0 == 1 page, 1 = 2 pages, 2 == 4 pages,
204 * max-ring-pages
209 * The maximum supported size of the request ring buffer in units of
212 *------------------------- Backend Device Properties -------------------------
214 * discard-enable
223 * discard-alignment
226 * Notes: 4, 5
231 * discard-granularity
233 * Default Value: <"sector-size">
234 * Notes: 4
239 * discard-secure
254 * sector-size
261 * set to 512, unless the frontend advertizes a non-zero value
262 * in its "feature-large-sector-size" xenbus node. (See below).
264 * physical-sector-size
266 * Default Value: <"sector-size">
269 * must be an integer multiple of "sector-size".
274 * The size of the backend device, expressed in units of "sector-size".
275 * The product of "sector-size" and "sectors" must also be an integer
276 * multiple of "physical-sector-size", if that node is present.
282 *----------------------- Request Transport Parameters -----------------------
284 * event-channel
288 * in the ring buffer.
290 * ring-ref
295 * the sole page in a single page sized ring buffer.
297 * ring-ref%u
301 * For a frontend providing a multi-page ring, a "number of ring pages"
303 * permission for the backend to map the page of the ring located
310 * The machine ABI rules governing the format of all ring request and
313 * ring-page-order
316 * Maximum Value: MAX(ffs(max-ring-pages) - 1, max-ring-page-order)
319 * The size of the frontend allocated request ring buffer in units
320 * of lb(machine pages). (e.g. 0 == 1 page, 1 = 2 pages, 2 == 4 pages,
323 * num-ring-pages
326 * Maximum Value: MAX(max-ring-pages,(0x1 << max-ring-page-order))
329 * The size of the frontend allocated request ring buffer in units of
332 *--------------------------------- Features ---------------------------------
334 * feature-persistent
341 * access (even when it should be read-only). If the frontend hits the
355 * feature-large-sector-size
360 * interpret all sector-based quantities in terms of the "sector-size"
366 *------------------------- Virtual Device Properties -------------------------
368 * device-type
371 * virtual-device
378 * See docs/misc/vbd-interface.txt for details on the format of this
382 * -----
383 * (1) Multi-page ring buffer scheme first developed in the Citrix XenServer
385 * (2) Multi-page ring buffer scheme first used in some RedHat distributions
388 * (3) Support for multi-page ring buffers was implemented independently,
391 * identical ring parameters, adjusted for unit differences, to the
393 * (4) Devices that support discard functionality may internally allocate space
396 * backend should provide both discard-granularity and discard-alignment.
398 * Backends supporting discard should include discard-granularity and
399 * discard-alignment even if it supports discarding individual sectors.
400 * Frontends should assume discard-alignment == 0 and discard-granularity
402 * (5) The discard-alignment parameter allows a physical device to be
405 * (6) When there is only a single page allocated to the request ring,
406 * 'ring-ref' is used to communicate the grant reference for this
407 * page to the backend. When using a multi-page ring, the 'ring-ref'
408 * node is not created. Instead 'ring-ref0' - 'ring-refN' are used.
414 * with write access, even when they should be mapped read-only, since
420 *(10) The discard-secure property may be present and will be set to 1 if the
427 * If supported, the backend will write the key "multi-queue-max-queues" to
431 * key "multi-queue-num-queues" with the number they wish to use, which must be
433 * "multi-queue-max-queues".
435 * For frontends requesting just one queue, the usual event-channel and
436 * ring-ref keys are written as before, simplifying the backend processing
438 * multi-queue feature, and one that does, but requested only one queue.
441 * event-channel and ring-ref keys, instead writing those keys under sub-keys
442 * having the name "queue-N" where N is the integer ID of the queue/ring for
445 * queue-related keys:
447 * /local/domain/1/device/vbd/0/multi-queue-num-queues = "2"
448 * /local/domain/1/device/vbd/0/queue-0 = ""
449 * /local/domain/1/device/vbd/0/queue-0/ring-ref = "<ring-ref#0>"
450 * /local/domain/1/device/vbd/0/queue-0/event-channel = "<evtchn#0>"
451 * /local/domain/1/device/vbd/0/queue-1 = ""
452 * /local/domain/1/device/vbd/0/queue-1/ring-ref = "<ring-ref#1>"
453 * /local/domain/1/device/vbd/0/queue-1/event-channel = "<evtchn#1>"
456 * feature multi-page ring buffer.
457 * For example, a frontend requests two queues/rings and the size of each ring
460 * /local/domain/1/device/vbd/0/multi-queue-num-queues = "2"
461 * /local/domain/1/device/vbd/0/ring-page-order = "1"
462 * /local/domain/1/device/vbd/0/queue-0 = ""
463 * /local/domain/1/device/vbd/0/queue-0/ring-ref0 = "<ring-ref#0>"
464 * /local/domain/1/device/vbd/0/queue-0/ring-ref1 = "<ring-ref#1>"
465 * /local/domain/1/device/vbd/0/queue-0/event-channel = "<evtchn#0>"
466 * /local/domain/1/device/vbd/0/queue-1 = ""
467 * /local/domain/1/device/vbd/0/queue-1/ring-ref0 = "<ring-ref#2>"
468 * /local/domain/1/device/vbd/0/queue-1/ring-ref1 = "<ring-ref#3>"
469 * /local/domain/1/device/vbd/0/queue-1/event-channel = "<evtchn#1>"
498 * request ring.
508 * o Connect to the request ring and
557 * Optional. See "feature-barrier" XenBus node documentation above.
564 * Optional. See "feature-flush-cache" XenBus node documentation above.
571 #define BLKIF_OP_RESERVED_1 4
584 * e07154r6-Data_Set_Management_Proposal_for_ATA-ACS2.doc
588 * Optional. See "feature-discard", "discard-alignment",
589 * "discard-granularity", and "discard-secure" in the XenBus node
595 * Recognized if "feature-max-indirect-segments" in present in the backend
596 * xenbus info. The "feature-max-indirect-segments" node contains the maximum
614 * create the "feature-max-indirect-segments" node!
621 * NB. This could be 12 if the ring indexes weren't stored in the same page.
633 * blkif_request_indirect are sector-based quantities. See the description
634 * of the "feature-large-sector-size" frontend xenbus node above for
645 * Starting ring element for any I/O request.
664 #define BLKIF_DISCARD_SECURE (1<<0) /* ignored if discard-secure=0 */
697 #define BLKIF_RSP_EOPNOTSUPP -2
698 /* Operation failed for some unspecified reason (-EIO). */
699 #define BLKIF_RSP_ERROR -1
704 * Generate blkif ring structures and types.
717 * c-file-style: "BSD"
718 * c-basic-offset: 4
719 * tab-width: 4
720 * indent-tabs-mode: nil