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
19  * notification can be made conditional on req_event (i.e., the generic
20  * hold-off mechanism provided by the ring macros). Backends must set
23  * Back->front notifications: When enqueuing a new response, sending a
24  * notification can be made conditional on rsp_event (i.e., the generic
25  * hold-off mechanism provided by the ring macros). Frontends must set
47  * Any specified default value is in effect if the corresponding XenBus node
56  * See the XenBus state transition diagram below for details on when XenBus
63  *------------------ Backend Device Identification (PRIVATE) ------------------
78  * physical-device
85  * physical-device-path
88  *      A string that contains the absolute path to the disk image. On
89  *      NetBSD and Linux this is always a block device, while on FreeBSD
98  * direct-io-safe
100  *      Default Value:  0
104  *        https://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html
119  *--------------------------------- Features ---------------------------------
121  * feature-barrier
123  *      Default Value:  0
130  * feature-flush-cache
132  *      Default Value:  0
139  * feature-discard
141  *      Default Value:  0
148  * feature-persistent
150  *      Default Value:  0
156  *      can map persistently depends on the implementation, but ideally it
164  *      and fall back to non-persistent mode. Backend implementations may
166  *      notifying the frontend depending on memory constraints (this might
176  *----------------------- Request Transport Parameters ------------------------
178  * max-ring-page-order
180  *      Default Value:  0
187  * max-ring-pages
189  *      Default Value:  1
195  *------------------------- Backend Device Properties -------------------------
197  * discard-enable
199  *      Default Value:  1
206  * discard-alignment
208  *      Default Value:  0
212  *      to the first, addressable, discard extent on the underlying device.
214  * discard-granularity
216  *      Default Value:  <"sector-size">
222  * discard-secure
224  *      Default Value:  0
237  * sector-size
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">
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"
291  *      Default Value:  XEN_IO_PROTO_ABI_NATIVE
296  * ring-page-order
298  *      Default Value:  0
299  *      Maximum Value:  MAX(ffs(max-ring-pages) - 1, max-ring-page-order)
306  * num-ring-pages
308  *      Default Value:  1
309  *      Maximum Value:  MAX(max-ring-pages,(0x1 << max-ring-page-order))
315  *--------------------------------- Features ---------------------------------
317  * feature-persistent
319  *      Default Value:  0
324  *      access (even when it should be read-only). If the frontend hits the
338  * feature-large-sector-size
340  *      Default Value:  0
343  *      interpret all sector-based quantities in terms of the "sector-size"
351  *      Default value:  1
355  *      a malicious backend on the other end.
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
377  *     including a distribution deployed on certain nodes of the Amazon
379  * (3) Support for multi-page ring buffers was implemented independently,
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
395  *     end on a discardable extent boundary.
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
407  * (9) Linux implementation doesn't have a limit on the maximum number of
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>"
520  *         case, default transport parameters are in effect and any
522  *         their default values.
526  *         enter the XenbusStateInitialised state.  In this case, default
528  *         published by the backend must contain their default values.
548  * Optional.  See "feature-barrier" XenBus node documentation above.
555  * Optional.  See "feature-flush-cache" XenBus node documentation above.
566  * the BLKIF_DISCARD_SECURE flag is set on the request, all copies of the
567  * discarded region on the device must be rendered unrecoverable before the
571  * command on a native device.
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
643     blkif_sector_t sector_number;/* start sector idx on disk (r/w only)  */
655 #define BLKIF_DISCARD_SECURE (1<<0)  /* ignored if discard-secure=0      */
658     blkif_sector_t sector_number;/* start sector idx on disk             */
668     blkif_sector_t sector_number;/* start sector idx on disk (r/w only)  */
672     uint64_t       pad;          /* Make it 64 byte aligned on i386      */
687  /* Operation not supported (only happens on barrier writes). */
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