interface/io/blkif.h

1 /* SPDX-License-Identifier: MIT */
5  * Unified block-device I/O interface for Xen guest OSes.
7  * Copyright (c) 2003-2004, Keir Fraser
18  * Front->back notifications: When enqueuing a new request, sending a
20  * hold-off mechanism provided by the ring macros). Backends must set
23  * Back->front notifications: When enqueuing a new response, sending a
25  * hold-off mechanism provided by the ring macros). Frontends must set
37  * The two halves of a Xen block driver utilize nodes within the XenStore to
63  *------------------ Backend Device Identification (PRIVATE) ------------------
76  *      handler (ie: a block device) for blkback to use.
78  * physical-device
85  * physical-device-path
89  *      NetBSD and Linux this is always a block device, while on FreeBSD
90  *      it can be either a block device or a regular file.
98  * direct-io-safe
104  *        https://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html
119  *--------------------------------- Features ---------------------------------
121  * feature-barrier
130  * feature-flush-cache
139  * feature-discard
148  * feature-persistent
164  *      and fall back to non-persistent mode. Backend implementations may
176  *----------------------- Request Transport Parameters ------------------------
178  * max-ring-page-order
187  * max-ring-pages
195  *------------------------- Backend Device Properties -------------------------
197  * discard-enable
206  * discard-alignment
211  *      The offset, in bytes from the beginning of the virtual block device,
214  * discard-granularity
216  *      Default Value:  <"sector-size">
222  * discard-secure
237  * sector-size
240  *      The logical block size, in bytes, of the underlying storage. This
244  *            set to 512, unless the frontend advertizes a non-zero value
245  *            in its "feature-large-sector-size" xenbus node. (See below).
247  * physical-sector-size
249  *      Default Value:  <"sector-size">
251  *      The physical block size, in bytes, of the backend storage. This
252  *      must be an integer multiple of "sector-size".
257  *      The size of the backend device, expressed in units of "sector-size".
258  *      The product of "sector-size" and "sectors" must also be an integer
259  *      multiple of "physical-sector-size", if that node is present.
265  *----------------------- Request Transport Parameters -----------------------
267  * event-channel
273  * ring-ref
280  * ring-ref%u
284  *      For a frontend providing a multi-page ring, a "number of ring pages"
296  * ring-page-order
299  *      Maximum Value:  MAX(ffs(max-ring-pages) - 1, max-ring-page-order)
306  * num-ring-pages
309  *      Maximum Value:  MAX(max-ring-pages,(0x1 << max-ring-page-order))
315  *--------------------------------- Features ---------------------------------
317  * feature-persistent
324  *      access (even when it should be read-only). If the frontend hits the
338  * feature-large-sector-size
343  *      interpret all sector-based quantities in terms of the "sector-size"
346  *      that the frontend requires that the logical block size is 512 as it
357  *------------------------- Virtual Device Properties -------------------------
359  * device-type
362  * virtual-device
369  *      See docs/misc/vbd-interface.txt for details on the format of this
373  * -----
374  * (1) Multi-page ring buffer scheme first developed in the Citrix XenServer
376  * (2) Multi-page ring buffer scheme first used in some RedHat distributions
379  * (3) Support for multi-page ring buffers was implemented independently,
381  *     For full interoperability, block front and backends should publish
386  *     block size. If the backing device has such discardable extents the
387  *     backend should provide both discard-granularity and discard-alignment.
389  *     Backends supporting discard should include discard-granularity and
390  *     discard-alignment even if it supports discarding individual sectors.
391  *     Frontends should assume discard-alignment == 0 and discard-granularity
393  * (5) The discard-alignment parameter allows a physical device to be
397  *     'ring-ref' is used to communicate the grant reference for this
398  *     page to the backend.  When using a multi-page ring, the 'ring-ref'
399  *     node is not created.  Instead 'ring-ref0' - 'ring-refN' are used.
405  *     with write access, even when they should be mapped read-only, since
411  *(10) The discard-secure property may be present and will be set to 1 if the
418  * If supported, the backend will write the key "multi-queue-max-queues" to
422  * key "multi-queue-num-queues" with the number they wish to use, which must be
424  * "multi-queue-max-queues".
426  * For frontends requesting just one queue, the usual event-channel and
427  * ring-ref keys are written as before, simplifying the backend processing
429  * multi-queue feature, and one that does, but requested only one queue.
432  * event-channel and ring-ref keys, instead writing those keys under sub-keys
433  * having the name "queue-N" where N is the integer ID of the queue/ring for
436  * queue-related keys:
438  * /local/domain/1/device/vbd/0/multi-queue-num-queues = "2"
439  * /local/domain/1/device/vbd/0/queue-0 = ""
440  * /local/domain/1/device/vbd/0/queue-0/ring-ref = "<ring-ref#0>"
441  * /local/domain/1/device/vbd/0/queue-0/event-channel = "<evtchn#0>"
442  * /local/domain/1/device/vbd/0/queue-1 = ""
443  * /local/domain/1/device/vbd/0/queue-1/ring-ref = "<ring-ref#1>"
444  * /local/domain/1/device/vbd/0/queue-1/event-channel = "<evtchn#1>"
447  * feature multi-page ring buffer.
451  * /local/domain/1/device/vbd/0/multi-queue-num-queues = "2"
452  * /local/domain/1/device/vbd/0/ring-page-order = "1"
453  * /local/domain/1/device/vbd/0/queue-0 = ""
454  * /local/domain/1/device/vbd/0/queue-0/ring-ref0 = "<ring-ref#0>"
455  * /local/domain/1/device/vbd/0/queue-0/ring-ref1 = "<ring-ref#1>"
456  * /local/domain/1/device/vbd/0/queue-0/event-channel = "<evtchn#0>"
457  * /local/domain/1/device/vbd/0/queue-1 = ""
458  * /local/domain/1/device/vbd/0/queue-1/ring-ref0 = "<ring-ref#2>"
459  * /local/domain/1/device/vbd/0/queue-1/ring-ref1 = "<ring-ref#3>"
460  * /local/domain/1/device/vbd/0/queue-1/event-channel = "<evtchn#1>"
548  * Optional.  See "feature-barrier" XenBus node documentation above.
555  * Optional.  See "feature-flush-cache" XenBus node documentation above.
575  *     e07154r6-Data_Set_Management_Proposal_for_ATA-ACS2.doc
579  * Optional.  See "feature-discard", "discard-alignment",
580  * "discard-granularity", and "discard-secure" in the XenBus node
586  * Recognized if "feature-max-indirect-segments" in present in the backend
587  * xenbus info. The "feature-max-indirect-segments" node contains the maximum
605  * create the "feature-max-indirect-segments" node!
624  * blkif_request_indirect are sector-based quantities. See the description
625  * of the "feature-large-sector-size" frontend xenbus node above for
655 #define BLKIF_DISCARD_SECURE (1<<0)  /* ignored if discard-secure=0      */
688 #define BLKIF_RSP_EOPNOTSUPP  -2
689  /* Operation failed for some unspecified reason (-EIO). */
690 #define BLKIF_RSP_ERROR       -1
708  * c-file-style: "BSD"
709  * c-basic-offset: 4
710  * tab-width: 4
711  * indent-tabs-mode: nil