1 /******************************************************************************
4 * Unified block-device I/O interface for Xen guest OSes.
6 * Copyright (c) 2003-2004, Keir Fraser
9 #ifndef __XEN_PUBLIC_IO_BLKIF_H__
10 #define __XEN_PUBLIC_IO_BLKIF_H__
13 #include "../grant_table.h"
16 * Front->back notifications: When enqueuing a new request, sending a
17 * notification can be made conditional on req_event (i.e., the generic
18 * hold-off mechanism provided by the ring macros). Backends must set
19 * req_event appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()).
21 * Back->front notifications: When enqueuing a new response, sending a
22 * notification can be made conditional on rsp_event (i.e., the generic
23 * hold-off mechanism provided by the ring macros). Frontends must set
24 * rsp_event appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()).
27 typedef uint16_t blkif_vdev_t;
28 typedef uint64_t blkif_sector_t;
33 #define BLKIF_OP_READ 0
34 #define BLKIF_OP_WRITE 1
36 * Recognised only if "feature-barrier" is present in backend xenbus info.
37 * The "feature_barrier" node contains a boolean indicating whether barrier
38 * requests are likely to succeed or fail. Either way, a barrier request
39 * may fail at any time with BLKIF_RSP_EOPNOTSUPP if it is unsupported by
40 * the underlying block-device hardware. The boolean simply indicates whether
41 * or not it is worthwhile for the frontend to attempt barrier requests.
42 * If a backend does not recognise BLKIF_OP_WRITE_BARRIER, it should *not*
43 * create the "feature-barrier" node!
45 #define BLKIF_OP_WRITE_BARRIER 2
48 * Recognised if "feature-flush-cache" is present in backend xenbus
49 * info. A flush will ask the underlying storage hardware to flush its
50 * non-volatile caches as appropriate. The "feature-flush-cache" node
51 * contains a boolean indicating whether flush requests are likely to
52 * succeed or fail. Either way, a flush request may fail at any time
53 * with BLKIF_RSP_EOPNOTSUPP if it is unsupported by the underlying
54 * block-device hardware. The boolean simply indicates whether or not it
55 * is worthwhile for the frontend to attempt flushes. If a backend does
56 * not recognise BLKIF_OP_WRITE_FLUSH_CACHE, it should *not* create the
57 * "feature-flush-cache" node!
59 #define BLKIF_OP_FLUSH_DISKCACHE 3
62 * Recognised only if "feature-discard" is present in backend xenbus info.
63 * The "feature-discard" node contains a boolean indicating whether trim
64 * (ATA) or unmap (SCSI) - conviently called discard requests are likely
65 * to succeed or fail. Either way, a discard request
66 * may fail at any time with BLKIF_RSP_EOPNOTSUPP if it is unsupported by
67 * the underlying block-device hardware. The boolean simply indicates whether
68 * or not it is worthwhile for the frontend to attempt discard requests.
69 * If a backend does not recognise BLKIF_OP_DISCARD, it should *not*
70 * create the "feature-discard" node!
72 * Discard operation is a request for the underlying block device to mark
73 * extents to be erased. However, discard does not guarantee that the blocks
74 * will be erased from the device - it is just a hint to the device
75 * controller that these blocks are no longer in use. What the device
76 * controller does with that information is left to the controller.
77 * Discard operations are passed with sector_number as the
78 * sector index to begin discard operations at and nr_sectors as the number of
79 * sectors to be discarded. The specified sectors should be discarded if the
80 * underlying block device supports trim (ATA) or unmap (SCSI) operations,
81 * or a BLKIF_RSP_EOPNOTSUPP should be returned.
82 * More information about trim/unmap operations at:
83 * http://t13.org/Documents/UploadedDocuments/docs2008/
84 * e07154r6-Data_Set_Management_Proposal_for_ATA-ACS2.doc
85 * http://www.seagate.com/staticfiles/support/disc/manuals/
86 * Interface%20manuals/100293068c.pdf
88 #define BLKIF_OP_DISCARD 5
91 * Maximum scatter/gather segments per request.
92 * This is carefully chosen so that sizeof(struct blkif_ring) <= PAGE_SIZE.
93 * NB. This could be 12 if the ring indexes weren't stored in the same page.
95 #define BLKIF_MAX_SEGMENTS_PER_REQUEST 11
97 struct blkif_request_rw {
98 blkif_sector_t sector_number;/* start sector idx on disk (r/w only) */
99 struct blkif_request_segment {
100 grant_ref_t gref; /* reference to I/O buffer frame */
101 /* @first_sect: first sector in frame to transfer (inclusive). */
102 /* @last_sect: last sector in frame to transfer (inclusive). */
103 uint8_t first_sect, last_sect;
104 } seg[BLKIF_MAX_SEGMENTS_PER_REQUEST];
107 struct blkif_request_discard {
108 blkif_sector_t sector_number;
112 struct blkif_request {
113 uint8_t operation; /* BLKIF_OP_??? */
114 uint8_t nr_segments; /* number of segments */
115 blkif_vdev_t handle; /* only for read/write requests */
116 uint64_t id; /* private guest value, echoed in resp */
118 struct blkif_request_rw rw;
119 struct blkif_request_discard discard;
123 struct blkif_response {
124 uint64_t id; /* copied from request */
125 uint8_t operation; /* copied from request */
126 int16_t status; /* BLKIF_RSP_??? */
130 * STATUS RETURN CODES.
132 /* Operation not supported (only happens on barrier writes). */
133 #define BLKIF_RSP_EOPNOTSUPP -2
134 /* Operation failed for some unspecified reason (-EIO). */
135 #define BLKIF_RSP_ERROR -1
136 /* Operation completed successfully. */
137 #define BLKIF_RSP_OKAY 0
140 * Generate blkif ring structures and types.
143 DEFINE_RING_TYPES(blkif, struct blkif_request, struct blkif_response);
145 #define VDISK_CDROM 0x1
146 #define VDISK_REMOVABLE 0x2
147 #define VDISK_READONLY 0x4
149 /* Xen-defined major numbers for virtual disks, they look strangely
151 #define XEN_IDE0_MAJOR 3
152 #define XEN_IDE1_MAJOR 22
153 #define XEN_SCSI_DISK0_MAJOR 8
154 #define XEN_SCSI_DISK1_MAJOR 65
155 #define XEN_SCSI_DISK2_MAJOR 66
156 #define XEN_SCSI_DISK3_MAJOR 67
157 #define XEN_SCSI_DISK4_MAJOR 68
158 #define XEN_SCSI_DISK5_MAJOR 69
159 #define XEN_SCSI_DISK6_MAJOR 70
160 #define XEN_SCSI_DISK7_MAJOR 71
161 #define XEN_SCSI_DISK8_MAJOR 128
162 #define XEN_SCSI_DISK9_MAJOR 129
163 #define XEN_SCSI_DISK10_MAJOR 130
164 #define XEN_SCSI_DISK11_MAJOR 131
165 #define XEN_SCSI_DISK12_MAJOR 132
166 #define XEN_SCSI_DISK13_MAJOR 133
167 #define XEN_SCSI_DISK14_MAJOR 134
168 #define XEN_SCSI_DISK15_MAJOR 135
170 #endif /* __XEN_PUBLIC_IO_BLKIF_H__ */