Commit | Line | Data |
---|---|---|
a42089dd JF |
1 | /****************************************************************************** |
2 | * blkif.h | |
3 | * | |
4 | * Unified block-device I/O interface for Xen guest OSes. | |
5 | * | |
6 | * Copyright (c) 2003-2004, Keir Fraser | |
7 | */ | |
8 | ||
9 | #ifndef __XEN_PUBLIC_IO_BLKIF_H__ | |
10 | #define __XEN_PUBLIC_IO_BLKIF_H__ | |
11 | ||
a1ce3928 DH |
12 | #include <xen/interface/io/ring.h> |
13 | #include <xen/interface/grant_table.h> | |
a42089dd JF |
14 | |
15 | /* | |
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()). | |
20 | * | |
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()). | |
25 | */ | |
26 | ||
27 | typedef uint16_t blkif_vdev_t; | |
28 | typedef uint64_t blkif_sector_t; | |
29 | ||
30 | /* | |
31 | * REQUEST CODES. | |
32 | */ | |
33 | #define BLKIF_OP_READ 0 | |
34 | #define BLKIF_OP_WRITE 1 | |
35 | /* | |
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! | |
44 | */ | |
45 | #define BLKIF_OP_WRITE_BARRIER 2 | |
46 | ||
6dcfb751 KRW |
47 | /* |
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! | |
58 | */ | |
59 | #define BLKIF_OP_FLUSH_DISKCACHE 3 | |
32a8d26c LD |
60 | |
61 | /* | |
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! | |
71 | * | |
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 | |
5ea42986 KRW |
87 | * The backend can optionally provide three extra XenBus attributes to |
88 | * further optimize the discard functionality: | |
89 | * 'discard-aligment' - Devices that support discard functionality may | |
90 | * internally allocate space in units that are bigger than the exported | |
91 | * logical block size. The discard-alignment parameter indicates how many bytes | |
92 | * the beginning of the partition is offset from the internal allocation unit's | |
93 | * natural alignment. | |
94 | * 'discard-granularity' - Devices that support discard functionality may | |
95 | * internally allocate space using units that are bigger than the logical block | |
96 | * size. The discard-granularity parameter indicates the size of the internal | |
97 | * allocation unit in bytes if reported by the device. Otherwise the | |
98 | * discard-granularity will be set to match the device's physical block size. | |
99 | * 'discard-secure' - All copies of the discarded sectors (potentially created | |
100 | * by garbage collection) must also be erased. To use this feature, the flag | |
101 | * BLKIF_DISCARD_SECURE must be set in the blkif_request_trim. | |
32a8d26c LD |
102 | */ |
103 | #define BLKIF_OP_DISCARD 5 | |
104 | ||
402b27f9 RPM |
105 | /* |
106 | * Recognized if "feature-max-indirect-segments" in present in the backend | |
107 | * xenbus info. The "feature-max-indirect-segments" node contains the maximum | |
108 | * number of segments allowed by the backend per request. If the node is | |
109 | * present, the frontend might use blkif_request_indirect structs in order to | |
110 | * issue requests with more than BLKIF_MAX_SEGMENTS_PER_REQUEST (11). The | |
111 | * maximum number of indirect segments is fixed by the backend, but the | |
112 | * frontend can issue requests with any number of indirect segments as long as | |
113 | * it's less than the number provided by the backend. The indirect_grefs field | |
114 | * in blkif_request_indirect should be filled by the frontend with the | |
115 | * grant references of the pages that are holding the indirect segments. | |
116 | * This pages are filled with an array of blkif_request_segment_aligned | |
117 | * that hold the information about the segments. The number of indirect | |
118 | * pages to use is determined by the maximum number of segments | |
119 | * a indirect request contains. Every indirect page can contain a maximum | |
120 | * of 512 segments (PAGE_SIZE/sizeof(blkif_request_segment_aligned)), | |
121 | * so to calculate the number of indirect pages to use we have to do | |
122 | * ceil(indirect_segments/512). | |
123 | * | |
124 | * If a backend does not recognize BLKIF_OP_INDIRECT, it should *not* | |
125 | * create the "feature-max-indirect-segments" node! | |
126 | */ | |
127 | #define BLKIF_OP_INDIRECT 6 | |
128 | ||
a42089dd JF |
129 | /* |
130 | * Maximum scatter/gather segments per request. | |
131 | * This is carefully chosen so that sizeof(struct blkif_ring) <= PAGE_SIZE. | |
132 | * NB. This could be 12 if the ring indexes weren't stored in the same page. | |
133 | */ | |
134 | #define BLKIF_MAX_SEGMENTS_PER_REQUEST 11 | |
135 | ||
402b27f9 RPM |
136 | #define BLKIF_MAX_INDIRECT_PAGES_PER_REQUEST 8 |
137 | ||
138 | struct blkif_request_segment_aligned { | |
139 | grant_ref_t gref; /* reference to I/O buffer frame */ | |
140 | /* @first_sect: first sector in frame to transfer (inclusive). */ | |
141 | /* @last_sect: last sector in frame to transfer (inclusive). */ | |
142 | uint8_t first_sect, last_sect; | |
143 | uint16_t _pad; /* padding to make it 8 bytes, so it's cache-aligned */ | |
144 | } __attribute__((__packed__)); | |
145 | ||
51de6952 | 146 | struct blkif_request_rw { |
97e36834 KRW |
147 | uint8_t nr_segments; /* number of segments */ |
148 | blkif_vdev_t handle; /* only for read/write requests */ | |
149 | #ifdef CONFIG_X86_64 | |
150 | uint32_t _pad1; /* offsetof(blkif_request,u.rw.id) == 8 */ | |
151 | #endif | |
152 | uint64_t id; /* private guest value, echoed in resp */ | |
a42089dd JF |
153 | blkif_sector_t sector_number;/* start sector idx on disk (r/w only) */ |
154 | struct blkif_request_segment { | |
155 | grant_ref_t gref; /* reference to I/O buffer frame */ | |
156 | /* @first_sect: first sector in frame to transfer (inclusive). */ | |
157 | /* @last_sect: last sector in frame to transfer (inclusive). */ | |
158 | uint8_t first_sect, last_sect; | |
159 | } seg[BLKIF_MAX_SEGMENTS_PER_REQUEST]; | |
97e36834 | 160 | } __attribute__((__packed__)); |
a42089dd | 161 | |
32a8d26c | 162 | struct blkif_request_discard { |
5ea42986 KRW |
163 | uint8_t flag; /* BLKIF_DISCARD_SECURE or zero. */ |
164 | #define BLKIF_DISCARD_SECURE (1<<0) /* ignored if discard-secure=0 */ | |
97e36834 KRW |
165 | blkif_vdev_t _pad1; /* only for read/write requests */ |
166 | #ifdef CONFIG_X86_64 | |
167 | uint32_t _pad2; /* offsetof(blkif_req..,u.discard.id)==8*/ | |
168 | #endif | |
169 | uint64_t id; /* private guest value, echoed in resp */ | |
32a8d26c | 170 | blkif_sector_t sector_number; |
97e36834 KRW |
171 | uint64_t nr_sectors; |
172 | uint8_t _pad3; | |
173 | } __attribute__((__packed__)); | |
32a8d26c | 174 | |
0e367ae4 DV |
175 | struct blkif_request_other { |
176 | uint8_t _pad1; | |
177 | blkif_vdev_t _pad2; /* only for read/write requests */ | |
178 | #ifdef CONFIG_X86_64 | |
179 | uint32_t _pad3; /* offsetof(blkif_req..,u.other.id)==8*/ | |
180 | #endif | |
181 | uint64_t id; /* private guest value, echoed in resp */ | |
182 | } __attribute__((__packed__)); | |
183 | ||
402b27f9 RPM |
184 | struct blkif_request_indirect { |
185 | uint8_t indirect_op; | |
186 | uint16_t nr_segments; | |
187 | #ifdef CONFIG_X86_64 | |
188 | uint32_t _pad1; /* offsetof(blkif_...,u.indirect.id) == 8 */ | |
189 | #endif | |
190 | uint64_t id; | |
191 | blkif_sector_t sector_number; | |
192 | blkif_vdev_t handle; | |
193 | uint16_t _pad2; | |
194 | grant_ref_t indirect_grefs[BLKIF_MAX_INDIRECT_PAGES_PER_REQUEST]; | |
195 | #ifdef CONFIG_X86_64 | |
196 | uint32_t _pad3; /* make it 64 byte aligned */ | |
197 | #else | |
198 | uint64_t _pad3; /* make it 64 byte aligned */ | |
199 | #endif | |
200 | } __attribute__((__packed__)); | |
201 | ||
51de6952 OS |
202 | struct blkif_request { |
203 | uint8_t operation; /* BLKIF_OP_??? */ | |
51de6952 OS |
204 | union { |
205 | struct blkif_request_rw rw; | |
32a8d26c | 206 | struct blkif_request_discard discard; |
0e367ae4 | 207 | struct blkif_request_other other; |
402b27f9 | 208 | struct blkif_request_indirect indirect; |
51de6952 | 209 | } u; |
97e36834 | 210 | } __attribute__((__packed__)); |
51de6952 | 211 | |
a42089dd JF |
212 | struct blkif_response { |
213 | uint64_t id; /* copied from request */ | |
214 | uint8_t operation; /* copied from request */ | |
215 | int16_t status; /* BLKIF_RSP_??? */ | |
216 | }; | |
217 | ||
218 | /* | |
219 | * STATUS RETURN CODES. | |
220 | */ | |
221 | /* Operation not supported (only happens on barrier writes). */ | |
222 | #define BLKIF_RSP_EOPNOTSUPP -2 | |
223 | /* Operation failed for some unspecified reason (-EIO). */ | |
224 | #define BLKIF_RSP_ERROR -1 | |
225 | /* Operation completed successfully. */ | |
226 | #define BLKIF_RSP_OKAY 0 | |
227 | ||
228 | /* | |
229 | * Generate blkif ring structures and types. | |
230 | */ | |
231 | ||
232 | DEFINE_RING_TYPES(blkif, struct blkif_request, struct blkif_response); | |
233 | ||
234 | #define VDISK_CDROM 0x1 | |
235 | #define VDISK_REMOVABLE 0x2 | |
236 | #define VDISK_READONLY 0x4 | |
237 | ||
c80a4209 SS |
238 | /* Xen-defined major numbers for virtual disks, they look strangely |
239 | * familiar */ | |
240 | #define XEN_IDE0_MAJOR 3 | |
241 | #define XEN_IDE1_MAJOR 22 | |
242 | #define XEN_SCSI_DISK0_MAJOR 8 | |
243 | #define XEN_SCSI_DISK1_MAJOR 65 | |
244 | #define XEN_SCSI_DISK2_MAJOR 66 | |
245 | #define XEN_SCSI_DISK3_MAJOR 67 | |
246 | #define XEN_SCSI_DISK4_MAJOR 68 | |
247 | #define XEN_SCSI_DISK5_MAJOR 69 | |
248 | #define XEN_SCSI_DISK6_MAJOR 70 | |
249 | #define XEN_SCSI_DISK7_MAJOR 71 | |
250 | #define XEN_SCSI_DISK8_MAJOR 128 | |
251 | #define XEN_SCSI_DISK9_MAJOR 129 | |
252 | #define XEN_SCSI_DISK10_MAJOR 130 | |
253 | #define XEN_SCSI_DISK11_MAJOR 131 | |
254 | #define XEN_SCSI_DISK12_MAJOR 132 | |
255 | #define XEN_SCSI_DISK13_MAJOR 133 | |
256 | #define XEN_SCSI_DISK14_MAJOR 134 | |
257 | #define XEN_SCSI_DISK15_MAJOR 135 | |
258 | ||
a42089dd | 259 | #endif /* __XEN_PUBLIC_IO_BLKIF_H__ */ |