]>
Commit | Line | Data |
---|---|---|
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 | ||
12 | #include <xen/interface/io/ring.h> | |
13 | #include <xen/interface/grant_table.h> | |
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 | ||
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 | |
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 | |
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. | |
102 | */ | |
103 | #define BLKIF_OP_DISCARD 5 | |
104 | ||
105 | /* | |
106 | * Maximum scatter/gather segments per request. | |
107 | * This is carefully chosen so that sizeof(struct blkif_ring) <= PAGE_SIZE. | |
108 | * NB. This could be 12 if the ring indexes weren't stored in the same page. | |
109 | */ | |
110 | #define BLKIF_MAX_SEGMENTS_PER_REQUEST 11 | |
111 | ||
112 | struct blkif_request_rw { | |
113 | uint8_t nr_segments; /* number of segments */ | |
114 | blkif_vdev_t handle; /* only for read/write requests */ | |
115 | #ifdef CONFIG_X86_64 | |
116 | uint32_t _pad1; /* offsetof(blkif_request,u.rw.id) == 8 */ | |
117 | #endif | |
118 | uint64_t id; /* private guest value, echoed in resp */ | |
119 | blkif_sector_t sector_number;/* start sector idx on disk (r/w only) */ | |
120 | struct blkif_request_segment { | |
121 | grant_ref_t gref; /* reference to I/O buffer frame */ | |
122 | /* @first_sect: first sector in frame to transfer (inclusive). */ | |
123 | /* @last_sect: last sector in frame to transfer (inclusive). */ | |
124 | uint8_t first_sect, last_sect; | |
125 | } seg[BLKIF_MAX_SEGMENTS_PER_REQUEST]; | |
126 | } __attribute__((__packed__)); | |
127 | ||
128 | struct blkif_request_discard { | |
129 | uint8_t flag; /* BLKIF_DISCARD_SECURE or zero. */ | |
130 | #define BLKIF_DISCARD_SECURE (1<<0) /* ignored if discard-secure=0 */ | |
131 | blkif_vdev_t _pad1; /* only for read/write requests */ | |
132 | #ifdef CONFIG_X86_64 | |
133 | uint32_t _pad2; /* offsetof(blkif_req..,u.discard.id)==8*/ | |
134 | #endif | |
135 | uint64_t id; /* private guest value, echoed in resp */ | |
136 | blkif_sector_t sector_number; | |
137 | uint64_t nr_sectors; | |
138 | uint8_t _pad3; | |
139 | } __attribute__((__packed__)); | |
140 | ||
141 | struct blkif_request_other { | |
142 | uint8_t _pad1; | |
143 | blkif_vdev_t _pad2; /* only for read/write requests */ | |
144 | #ifdef CONFIG_X86_64 | |
145 | uint32_t _pad3; /* offsetof(blkif_req..,u.other.id)==8*/ | |
146 | #endif | |
147 | uint64_t id; /* private guest value, echoed in resp */ | |
148 | } __attribute__((__packed__)); | |
149 | ||
150 | struct blkif_request { | |
151 | uint8_t operation; /* BLKIF_OP_??? */ | |
152 | union { | |
153 | struct blkif_request_rw rw; | |
154 | struct blkif_request_discard discard; | |
155 | struct blkif_request_other other; | |
156 | } u; | |
157 | } __attribute__((__packed__)); | |
158 | ||
159 | struct blkif_response { | |
160 | uint64_t id; /* copied from request */ | |
161 | uint8_t operation; /* copied from request */ | |
162 | int16_t status; /* BLKIF_RSP_??? */ | |
163 | }; | |
164 | ||
165 | /* | |
166 | * STATUS RETURN CODES. | |
167 | */ | |
168 | /* Operation not supported (only happens on barrier writes). */ | |
169 | #define BLKIF_RSP_EOPNOTSUPP -2 | |
170 | /* Operation failed for some unspecified reason (-EIO). */ | |
171 | #define BLKIF_RSP_ERROR -1 | |
172 | /* Operation completed successfully. */ | |
173 | #define BLKIF_RSP_OKAY 0 | |
174 | ||
175 | /* | |
176 | * Generate blkif ring structures and types. | |
177 | */ | |
178 | ||
179 | DEFINE_RING_TYPES(blkif, struct blkif_request, struct blkif_response); | |
180 | ||
181 | #define VDISK_CDROM 0x1 | |
182 | #define VDISK_REMOVABLE 0x2 | |
183 | #define VDISK_READONLY 0x4 | |
184 | ||
185 | /* Xen-defined major numbers for virtual disks, they look strangely | |
186 | * familiar */ | |
187 | #define XEN_IDE0_MAJOR 3 | |
188 | #define XEN_IDE1_MAJOR 22 | |
189 | #define XEN_SCSI_DISK0_MAJOR 8 | |
190 | #define XEN_SCSI_DISK1_MAJOR 65 | |
191 | #define XEN_SCSI_DISK2_MAJOR 66 | |
192 | #define XEN_SCSI_DISK3_MAJOR 67 | |
193 | #define XEN_SCSI_DISK4_MAJOR 68 | |
194 | #define XEN_SCSI_DISK5_MAJOR 69 | |
195 | #define XEN_SCSI_DISK6_MAJOR 70 | |
196 | #define XEN_SCSI_DISK7_MAJOR 71 | |
197 | #define XEN_SCSI_DISK8_MAJOR 128 | |
198 | #define XEN_SCSI_DISK9_MAJOR 129 | |
199 | #define XEN_SCSI_DISK10_MAJOR 130 | |
200 | #define XEN_SCSI_DISK11_MAJOR 131 | |
201 | #define XEN_SCSI_DISK12_MAJOR 132 | |
202 | #define XEN_SCSI_DISK13_MAJOR 133 | |
203 | #define XEN_SCSI_DISK14_MAJOR 134 | |
204 | #define XEN_SCSI_DISK15_MAJOR 135 | |
205 | ||
206 | #endif /* __XEN_PUBLIC_IO_BLKIF_H__ */ |