]> CyberLeo.Net >> Repos - FreeBSD/releng/9.2.git/blob - sys/xen/interface/io/blkif.h
- Copy stable/9 to releng/9.2 as part of the 9.2-RELEASE cycle.
[FreeBSD/releng/9.2.git] / sys / xen / interface / io / blkif.h
1 /******************************************************************************
2  * blkif.h
3  *
4  * Unified block-device I/O interface for Xen guest OSes.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  * DEALINGS IN THE SOFTWARE.
23  *
24  * Copyright (c) 2003-2004, Keir Fraser
25  * Copyright (c) 2012, Spectra Logic Corporation
26  */
27
28 #ifndef __XEN_PUBLIC_IO_BLKIF_H__
29 #define __XEN_PUBLIC_IO_BLKIF_H__
30
31 #include <xen/interface/io/ring.h>
32 #include <xen/interface/grant_table.h>
33
34 /*
35  * Front->back notifications: When enqueuing a new request, sending a
36  * notification can be made conditional on req_event (i.e., the generic
37  * hold-off mechanism provided by the ring macros). Backends must set
38  * req_event appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()).
39  *
40  * Back->front notifications: When enqueuing a new response, sending a
41  * notification can be made conditional on rsp_event (i.e., the generic
42  * hold-off mechanism provided by the ring macros). Frontends must set
43  * rsp_event appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()).
44  */
45
46 #ifndef blkif_vdev_t
47 #define blkif_vdev_t   uint16_t
48 #endif
49 #define blkif_sector_t uint64_t
50
51 /*
52  * Feature and Parameter Negotiation
53  * =================================
54  * The two halves of a Xen block driver utilize nodes within the XenStore to
55  * communicate capabilities and to negotiate operating parameters.  This
56  * section enumerates these nodes which reside in the respective front and
57  * backend portions of the XenStore, following the XenBus convention.
58  *
59  * All data in the XenStore is stored as strings.  Nodes specifying numeric
60  * values are encoded in decimal.  Integer value ranges listed below are
61  * expressed as fixed sized integer types capable of storing the conversion
62  * of a properly formated node string, without loss of information.
63  *
64  * Any specified default value is in effect if the corresponding XenBus node
65  * is not present in the XenStore.
66  *
67  * XenStore nodes in sections marked "PRIVATE" are solely for use by the
68  * driver side whose XenBus tree contains them.
69  *
70  * See the XenBus state transition diagram below for details on when XenBus
71  * nodes must be published and when they can be queried.
72  *
73  *****************************************************************************
74  *                            Backend XenBus Nodes
75  *****************************************************************************
76  *
77  *------------------ Backend Device Identification (PRIVATE) ------------------
78  *
79  * mode
80  *      Values:         "r" (read only), "w" (writable)
81  *
82  *      The read or write access permissions to the backing store to be
83  *      granted to the frontend.
84  *
85  * params
86  *      Values:         string
87  *
88  *      A free formatted string providing sufficient information for the
89  *      backend driver to open the backing device.  (e.g. the path to the
90  *      file or block device representing the backing store.)
91  *
92  * type
93  *      Values:         "file", "phy", "tap"
94  *
95  *      The type of the backing device/object.
96  *
97  *--------------------------------- Features ---------------------------------
98  *
99  * feature-barrier
100  *      Values:         0/1 (boolean)
101  *      Default Value:  0
102  *
103  *      A value of "1" indicates that the backend can process requests
104  *      containing the BLKIF_OP_WRITE_BARRIER request opcode.  Requests
105  *      of this type may still be returned at any time with the
106  *      BLKIF_RSP_EOPNOTSUPP result code.
107  *
108  * feature-flush-cache
109  *      Values:         0/1 (boolean)
110  *      Default Value:  0
111  *
112  *      A value of "1" indicates that the backend can process requests
113  *      containing the BLKIF_OP_FLUSH_DISKCACHE request opcode.  Requests
114  *      of this type may still be returned at any time with the
115  *      BLKIF_RSP_EOPNOTSUPP result code.
116  *
117  * feature-discard
118  *      Values:         0/1 (boolean)
119  *      Default Value:  0
120  *
121  *      A value of "1" indicates that the backend can process requests
122  *      containing the BLKIF_OP_DISCARD request opcode.  Requests
123  *      of this type may still be returned at any time with the
124  *      BLKIF_RSP_EOPNOTSUPP result code.
125  *
126  *----------------------- Request Transport Parameters ------------------------
127  *
128  * max-ring-page-order
129  *      Values:         <uint32_t>
130  *      Default Value:  0
131  *      Notes:          1, 3
132  *
133  *      The maximum supported size of the request ring buffer in units of
134  *      lb(machine pages). (e.g. 0 == 1 page,  1 = 2 pages, 2 == 4 pages,
135  *      etc.).
136  *
137  * max-ring-pages
138  *      Values:         <uint32_t>
139  *      Default Value:  1
140  *      Notes:          2, 3
141  *
142  *      The maximum supported size of the request ring buffer in units of
143  *      machine pages.  The value must be a power of 2.
144  *
145  * max-requests         <uint32_t>
146  *      Default Value:  BLKIF_MAX_RING_REQUESTS(PAGE_SIZE)
147  *      Maximum Value:  BLKIF_MAX_RING_REQUESTS(PAGE_SIZE * max-ring-pages)
148  *
149  *      The maximum number of concurrent, logical requests that will be
150  *      issued by the backend.
151  *
152  *      Note: A logical request may span multiple ring entries.
153  *
154  * max-request-segments
155  *      Values:         <uint8_t>
156  *      Default Value:  BLKIF_MAX_SEGMENTS_PER_HEADER_BLOCK
157  *      Maximum Value:  BLKIF_MAX_SEGMENTS_PER_REQUEST
158  *
159  *      The maximum value of blkif_request.nr_segments supported by
160  *      the backend.
161  *
162  * max-request-size
163  *      Values:         <uint32_t>
164  *      Default Value:  BLKIF_MAX_SEGMENTS_PER_HEADER_BLOCK * PAGE_SIZE
165  *      Maximum Value:  BLKIF_MAX_SEGMENTS_PER_REQUEST * PAGE_SIZE
166  *
167  *      The maximum amount of data, in bytes, that can be referenced by a
168  *      request type that accesses frontend memory (currently BLKIF_OP_READ,
169  *      BLKIF_OP_WRITE, or BLKIF_OP_WRITE_BARRIER).
170  *
171  *------------------------- Backend Device Properties -------------------------
172  *
173  * discard-aligment
174  *      Values:         <uint32_t>
175  *      Default Value:  0
176  *      Notes:          4, 5
177  *
178  *      The offset, in bytes from the beginning of the virtual block device,
179  *      to the first, addressable, discard extent on the underlying device.
180  *
181  * discard-granularity
182  *      Values:         <uint32_t>
183  *      Default Value:  <"sector-size">
184  *      Notes:          4
185  *
186  *      The size, in bytes, of the individually addressable discard extents
187  *      of the underlying device.
188  *
189  * discard-secure
190  *      Values:         0/1 (boolean)
191  *      Default Value:  0
192  *
193  *      A value of "1" indicates that the backend can process BLKIF_OP_DISCARD
194  *      requests with the BLKIF_DISCARD_SECURE flag set.
195  *
196  * info
197  *      Values:         <uint32_t> (bitmap)
198  *
199  *      A collection of bit flags describing attributes of the backing
200  *      device.  The VDISK_* macros define the meaning of each bit
201  *      location.
202  *
203  * sector-size
204  *      Values:         <uint32_t>
205  *
206  *      The native sector size, in bytes, of the backend device.
207  *
208  * sectors
209  *      Values:         <uint64_t>
210  *
211  *      The size of the backend device, expressed in units of its native
212  *      sector size ("sector-size").
213  *
214  *****************************************************************************
215  *                            Frontend XenBus Nodes
216  *****************************************************************************
217  *
218  *----------------------- Request Transport Parameters -----------------------
219  *
220  * event-channel
221  *      Values:         <uint32_t>
222  *
223  *      The identifier of the Xen event channel used to signal activity
224  *      in the ring buffer.
225  *
226  * ring-ref
227  *      Values:         <uint32_t>
228  *      Notes:          6
229  *
230  *      The Xen grant reference granting permission for the backend to map
231  *      the sole page in a single page sized ring buffer.
232  *
233  * ring-ref%u
234  *      Values:         <uint32_t>
235  *      Notes:          6
236  *
237  *      For a frontend providing a multi-page ring, a "num-ring-pages" sized
238  *      list of nodes, each containing a Xen grant reference granting
239  *      permission for the backend to map the page of the ring located
240  *      at page index "%u".  Page indexes are zero based.
241  *
242  * protocol
243  *      Values:         string (XEN_IO_PROTO_ABI_*)
244  *      Default Value:  XEN_IO_PROTO_ABI_NATIVE
245  *
246  *      The machine ABI rules governing the format of all ring request and
247  *      response structures.
248  *
249  * ring-page-order
250  *      Values:         <uint32_t>
251  *      Default Value:  0
252  *      Maximum Value:  MAX(ffs(max-ring-pages) - 1, max-ring-page-order)
253  *      Notes:          1, 3
254  *
255  *      The size of the frontend allocated request ring buffer in units
256  *      of lb(machine pages). (e.g. 0 == 1 page, 1 = 2 pages, 2 == 4 pages,
257  *      etc.).
258  *
259  * num-ring-pages
260  *      Values:         <uint32_t>
261  *      Default Value:  1
262  *      Maximum Value:  MAX(max-ring-pages,(0x1 << max-ring-page-order))
263  *      Notes:          2, 3
264  *
265  *      The size of the frontend allocated request ring buffer in units of
266  *      machine pages.  The value must be a power of 2.
267  *
268  * max-requests
269  *      Values:         <uint32_t>
270  *      Default Value:  BLKIF_MAX_RING_REQUESTS(PAGE_SIZE)
271  *      Maximum Value:  BLKIF_MAX_RING_REQUESTS(PAGE_SIZE * max-ring_pages)
272  *
273  *      The maximum number of concurrent, logical requests that will be
274  *      issued by the frontend.
275  *
276  *      Note: A logical request may span multiple ring entries.
277  *
278  * max-request-segments
279  *      Values:         <uint8_t>
280  *      Default Value:  BLKIF_MAX_SEGMENTS_PER_HEADER_BLOCK
281  *      Maximum Value:  MIN(255, backend/max-request-segments)
282  *
283  *      The maximum value the frontend will set in the
284  *      blkif_request.nr_segments field.
285  *
286  * max-request-size
287  *      Values:         <uint32_t>
288  *      Default Value:  BLKIF_MAX_SEGMENTS_PER_HEADER_BLOCK * PAGE_SIZE
289  *      Maximum Value:  max-request-segments * PAGE_SIZE
290  *
291  *      The maximum amount of data, in bytes, that can be referenced by
292  *      a request type that accesses frontend memory (currently BLKIF_OP_READ,
293  *      BLKIF_OP_WRITE, or BLKIF_OP_WRITE_BARRIER).
294  *
295  *------------------------- Virtual Device Properties -------------------------
296  *
297  * device-type
298  *      Values:         "disk", "cdrom", "floppy", etc.
299  *
300  * virtual-device
301  *      Values:         <uint32_t>
302  *
303  *      A value indicating the physical device to virtualize within the
304  *      frontend's domain.  (e.g. "The first ATA disk", "The third SCSI
305  *      disk", etc.)
306  *
307  *      See docs/misc/vbd-interface.txt for details on the format of this
308  *      value.
309  *
310  * Notes
311  * -----
312  * (1) Multi-page ring buffer scheme first developed in the Citrix XenServer
313  *     PV drivers.
314  * (2) Multi-page ring buffer scheme first used in some RedHat distributions
315  *     including a distribution deployed on certain nodes of the Amazon
316  *     EC2 cluster.
317  * (3) Support for multi-page ring buffers was implemented independently,
318  *     in slightly different forms, by both Citrix and RedHat/Amazon.
319  *     For full interoperability, block front and backends should publish
320  *     identical ring parameters, adjusted for unit differences, to the
321  *     XenStore nodes used in both schemes.
322  * (4) Devices that support discard functionality may internally allocate
323  *     space (discardable extents) in units that are larger than the
324  *     exported logical block size.
325  * (5) The discard-alignment parameter allows a physical device to be
326  *     partitioned into virtual devices that do not necessarily begin or
327  *     end on a discardable extent boundary.
328  * (6) When there is only a single page allocated to the request ring,
329  *     'ring-ref' is used to communicate the grant reference for this
330  *     page to the backend.  When using a multi-page ring, the 'ring-ref'
331  *     node is not created.  Instead 'ring-ref0' - 'ring-refN' are used.
332  */
333
334 /*
335  * STATE DIAGRAMS
336  *
337  *****************************************************************************
338  *                                   Startup                                 *
339  *****************************************************************************
340  *
341  * Tool stack creates front and back nodes with state XenbusStateInitialising.
342  *
343  * Front                                Back
344  * =================================    =====================================
345  * XenbusStateInitialising              XenbusStateInitialising
346  *  o Query virtual device               o Query backend device identification
347  *    properties.                          data.
348  *  o Setup OS device instance.          o Open and validate backend device.
349  *                                       o Publish backend features and
350  *                                         transport parameters.
351  *                                                      |
352  *                                                      |
353  *                                                      V
354  *                                      XenbusStateInitWait
355  *
356  * o Query backend features and
357  *   transport parameters.
358  * o Allocate and initialize the
359  *   request ring.
360  * o Publish transport parameters
361  *   that will be in effect during
362  *   this connection.
363  *              |
364  *              |
365  *              V
366  * XenbusStateInitialised
367  *
368  *                                       o Query frontend transport parameters.
369  *                                       o Connect to the request ring and
370  *                                         event channel.
371  *                                       o Publish backend device properties.
372  *                                                      |
373  *                                                      |
374  *                                                      V
375  *                                      XenbusStateConnected
376  *
377  *  o Query backend device properties.
378  *  o Finalize OS virtual device
379  *    instance.
380  *              |
381  *              |
382  *              V
383  * XenbusStateConnected
384  *
385  * Note: Drivers that do not support any optional features, or the negotiation
386  *       of transport parameters, can skip certain states in the state machine:
387  *
388  *       o A frontend may transition to XenbusStateInitialised without
389  *         waiting for the backend to enter XenbusStateInitWait.  In this
390  *         case, default transport parameters are in effect and any
391  *         transport parameters published by the frontend must contain
392  *         their default values.
393  *
394  *       o A backend may transition to XenbusStateInitialised, bypassing
395  *         XenbusStateInitWait, without waiting for the frontend to first
396  *         enter the XenbusStateInitialised state.  In this case, default
397  *         transport parameters are in effect and any transport parameters
398  *         published by the backend must contain their default values.
399  *
400  *       Drivers that support optional features and/or transport parameter
401  *       negotiation must tolerate these additional state transition paths.
402  *       In general this means performing the work of any skipped state
403  *       transition, if it has not already been performed, in addition to the
404  *       work associated with entry into the current state.
405  */
406
407 /*
408  * REQUEST CODES.
409  */
410 #define BLKIF_OP_READ              0
411 #define BLKIF_OP_WRITE             1
412 /*
413  * All writes issued prior to a request with the BLKIF_OP_WRITE_BARRIER
414  * operation code ("barrier request") must be completed prior to the
415  * execution of the barrier request.  All writes issued after the barrier
416  * request must not execute until after the completion of the barrier request.
417  *
418  * Optional.  See "feature-barrier" XenBus node documentation above.
419  */
420 #define BLKIF_OP_WRITE_BARRIER     2
421 /*
422  * Commit any uncommitted contents of the backing device's volatile cache
423  * to stable storage.
424  *
425  * Optional.  See "feature-flush-cache" XenBus node documentation above.
426  */
427 #define BLKIF_OP_FLUSH_DISKCACHE   3
428 /*
429  * Used in SLES sources for device specific command packet
430  * contained within the request. Reserved for that purpose.
431  */
432 #define BLKIF_OP_RESERVED_1        4
433 /*
434  * Indicate to the backend device that a region of storage is no longer in
435  * use, and may be discarded at any time without impact to the client.  If
436  * the BLKIF_DISCARD_SECURE flag is set on the request, all copies of the
437  * discarded region on the device must be rendered unrecoverable before the
438  * command returns.
439  *
440  * This operation is analogous to performing a trim (ATA) or unamp (SCSI),
441  * command on a native device.
442  *
443  * More information about trim/unmap operations can be found at:
444  * http://t13.org/Documents/UploadedDocuments/docs2008/
445  *     e07154r6-Data_Set_Management_Proposal_for_ATA-ACS2.doc
446  * http://www.seagate.com/staticfiles/support/disc/manuals/
447  *     Interface%20manuals/100293068c.pdf
448  *
449  * Optional.  See "feature-discard", "discard-alignment",
450  * "discard-granularity", and "discard-secure" in the XenBus node
451  * documentation above.
452  */
453 #define BLKIF_OP_DISCARD           5
454
455 /*
456  * Maximum scatter/gather segments associated with a request header block.
457  * This is carefully chosen so that sizeof(blkif_ring_t) <= PAGE_SIZE.
458  * NB. This could be 12 if the ring indexes weren't stored in the same page.
459  */
460 #define BLKIF_MAX_SEGMENTS_PER_HEADER_BLOCK  11
461
462 /*
463  * Maximum scatter/gather segments associated with a segment block.
464  */
465 #define BLKIF_MAX_SEGMENTS_PER_SEGMENT_BLOCK 14
466
467 /*
468  * Maximum scatter/gather segments per request (header + segment blocks).
469  */
470 #define BLKIF_MAX_SEGMENTS_PER_REQUEST 255
471
472 /*
473  * NB. first_sect and last_sect in blkif_request_segment, as well as
474  * sector_number in blkif_request, are always expressed in 512-byte units.
475  * However they must be properly aligned to the real sector size of the
476  * physical disk, which is reported in the "sector-size" node in the backend
477  * xenbus info. Also the xenbus "sectors" node is expressed in 512-byte units.
478  */
479 struct blkif_request_segment {
480     grant_ref_t gref;        /* reference to I/O buffer frame        */
481     /* @first_sect: first sector in frame to transfer (inclusive).   */
482     /* @last_sect: last sector in frame to transfer (inclusive).     */
483     uint8_t     first_sect, last_sect;
484 };
485 typedef struct blkif_request_segment blkif_request_segment_t;
486
487 /*
488  * Starting ring element for any I/O request.
489  *
490  * One or more segment blocks can be inserted into the request ring
491  * just after a blkif_request_t, allowing requests to operate on
492  * up to BLKIF_MAX_SEGMENTS_PER_REQUEST.
493  *
494  * BLKIF_SEGS_TO_BLOCKS() can be used on blkif_requst.nr_segments
495  * to determine the number of contiguous ring entries associated
496  * with this request.
497  *
498  * Note:  Due to the way Xen request rings operate, the producer and
499  *        consumer indices of the ring must be incremented by the
500  *        BLKIF_SEGS_TO_BLOCKS() value of the associated request.
501  *        (e.g. a response to a 3 ring entry request must also consume
502  *        3 entries in the ring, even though only the first ring entry
503  *        in the response has any data.)
504  */
505 struct blkif_request {
506     uint8_t        operation;    /* BLKIF_OP_???                         */
507     uint8_t        nr_segments;  /* number of segments                   */
508     blkif_vdev_t   handle;       /* only for read/write requests         */
509     uint64_t       id;           /* private guest value, echoed in resp  */
510     blkif_sector_t sector_number;/* start sector idx on disk (r/w only)  */
511     blkif_request_segment_t seg[BLKIF_MAX_SEGMENTS_PER_HEADER_BLOCK];
512 };
513 typedef struct blkif_request blkif_request_t;
514
515 /*
516  * A segment block is a ring request structure that contains only
517  * segment data.
518  *
519  * sizeof(struct blkif_segment_block) <= sizeof(struct blkif_request)
520  */
521 struct blkif_segment_block {
522     blkif_request_segment_t seg[BLKIF_MAX_SEGMENTS_PER_SEGMENT_BLOCK];
523 };
524 typedef struct blkif_segment_block blkif_segment_block_t;
525
526 /*
527  * Cast to this structure when blkif_request.operation == BLKIF_OP_DISCARD
528  * sizeof(struct blkif_request_discard) <= sizeof(struct blkif_request)
529  */
530 struct blkif_request_discard {
531     uint8_t        operation;    /* BLKIF_OP_DISCARD                     */
532     uint8_t        flag;         /* BLKIF_DISCARD_SECURE or zero         */
533 #define BLKIF_DISCARD_SECURE (1<<0)  /* ignored if discard-secure=0      */
534     blkif_vdev_t   handle;       /* same as for read/write requests      */
535     uint64_t       id;           /* private guest value, echoed in resp  */
536     blkif_sector_t sector_number;/* start sector idx on disk             */
537     uint64_t       nr_sectors;   /* number of contiguous sectors to discard*/
538 };
539 typedef struct blkif_request_discard blkif_request_discard_t;
540
541 struct blkif_response {
542     uint64_t        id;              /* copied from request */
543     uint8_t         operation;       /* copied from request */
544     int16_t         status;          /* BLKIF_RSP_???       */
545 };
546 typedef struct blkif_response blkif_response_t;
547
548 /*
549  * STATUS RETURN CODES.
550  */
551  /* Operation not supported (only happens on barrier writes). */
552 #define BLKIF_RSP_EOPNOTSUPP  -2
553  /* Operation failed for some unspecified reason (-EIO). */
554 #define BLKIF_RSP_ERROR       -1
555  /* Operation completed successfully. */
556 #define BLKIF_RSP_OKAY         0
557
558 /*
559  * Generate blkif ring structures and types.
560  */
561 DEFINE_RING_TYPES(blkif, struct blkif_request, struct blkif_response);
562
563 /*
564  * Index to, and treat as a segment block, an entry in the ring.
565  */
566 #define BLKRING_GET_SEG_BLOCK(_r, _idx)                                 \
567     (((blkif_segment_block_t *)RING_GET_REQUEST(_r, _idx))->seg)
568
569 /*
570  * The number of ring request blocks required to handle an I/O
571  * request containing _segs segments.
572  */
573 #define BLKIF_SEGS_TO_BLOCKS(_segs)                                     \
574     ((((_segs - BLKIF_MAX_SEGMENTS_PER_HEADER_BLOCK)                    \
575      + (BLKIF_MAX_SEGMENTS_PER_SEGMENT_BLOCK - 1))                      \
576     / BLKIF_MAX_SEGMENTS_PER_SEGMENT_BLOCK) + /*header_block*/1)
577
578 #define VDISK_CDROM        0x1
579 #define VDISK_REMOVABLE    0x2
580 #define VDISK_READONLY     0x4
581
582 #endif /* __XEN_PUBLIC_IO_BLKIF_H__ */
583
584 /*
585  * Local variables:
586  * mode: C
587  * c-set-style: "BSD"
588  * c-basic-offset: 4
589  * tab-width: 4
590  * indent-tabs-mode: nil
591  * End:
592  */