Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
blkif.h
Go to the documentation of this file.
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>
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 
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 
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) */
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). */
126 } __attribute__((__packed__));
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 */
139 } __attribute__((__packed__));
142  uint8_t operation; /* BLKIF_OP_??? */
143  union {
146  } u;
147 } __attribute__((__packed__));
150  uint64_t id; /* copied from request */
151  uint8_t operation; /* copied from request */
152  int16_t status; /* BLKIF_RSP_??? */
153 };
154 
155 /*
156  * STATUS RETURN CODES.
157  */
158  /* Operation not supported (only happens on barrier writes). */
159 #define BLKIF_RSP_EOPNOTSUPP -2
160  /* Operation failed for some unspecified reason (-EIO). */
161 #define BLKIF_RSP_ERROR -1
162  /* Operation completed successfully. */
163 #define BLKIF_RSP_OKAY 0
164 
165 /*
166  * Generate blkif ring structures and types.
167  */
168 
169 DEFINE_RING_TYPES(blkif, struct blkif_request, struct blkif_response);
170 
171 #define VDISK_CDROM 0x1
172 #define VDISK_REMOVABLE 0x2
173 #define VDISK_READONLY 0x4
174 
175 /* Xen-defined major numbers for virtual disks, they look strangely
176  * familiar */
177 #define XEN_IDE0_MAJOR 3
178 #define XEN_IDE1_MAJOR 22
179 #define XEN_SCSI_DISK0_MAJOR 8
180 #define XEN_SCSI_DISK1_MAJOR 65
181 #define XEN_SCSI_DISK2_MAJOR 66
182 #define XEN_SCSI_DISK3_MAJOR 67
183 #define XEN_SCSI_DISK4_MAJOR 68
184 #define XEN_SCSI_DISK5_MAJOR 69
185 #define XEN_SCSI_DISK6_MAJOR 70
186 #define XEN_SCSI_DISK7_MAJOR 71
187 #define XEN_SCSI_DISK8_MAJOR 128
188 #define XEN_SCSI_DISK9_MAJOR 129
189 #define XEN_SCSI_DISK10_MAJOR 130
190 #define XEN_SCSI_DISK11_MAJOR 131
191 #define XEN_SCSI_DISK12_MAJOR 132
192 #define XEN_SCSI_DISK13_MAJOR 133
193 #define XEN_SCSI_DISK14_MAJOR 134
194 #define XEN_SCSI_DISK15_MAJOR 135
195 
196 #endif /* __XEN_PUBLIC_IO_BLKIF_H__ */