1 /******************************************************************************
2  * vscsiif.h
3  *
4  * Based on the blkif.h code.
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) FUJITSU Limited 2008.
25  */
26 
27 #ifndef __XEN__PUBLIC_IO_SCSI_H__
28 #define __XEN__PUBLIC_IO_SCSI_H__
29 
30 #include "ring.h"
31 #include "../grant_table.h"
32 
33 /*
34  * Feature and Parameter Negotiation
35  * =================================
36  * The two halves of a Xen pvSCSI driver utilize nodes within the XenStore to
37  * communicate capabilities and to negotiate operating parameters.  This
38  * section enumerates these nodes which reside in the respective front and
39  * backend portions of the XenStore, following the XenBus convention.
40  *
41  * Any specified default value is in effect if the corresponding XenBus node
42  * is not present in the XenStore.
43  *
44  * XenStore nodes in sections marked "PRIVATE" are solely for use by the
45  * driver side whose XenBus tree contains them.
46  *
47  *****************************************************************************
48  *                            Backend XenBus Nodes
49  *****************************************************************************
50  *
51  *------------------ Backend Device Identification (PRIVATE) ------------------
52  *
53  * p-devname
54  *      Values:         string
55  *
56  *      A free string used to identify the physical device (e.g. a disk name).
57  *
58  * p-dev
59  *      Values:         string
60  *
61  *      A string specifying the backend device: either a 4-tuple "h:c:t:l"
62  *      (host, controller, target, lun, all integers), or a WWN (e.g.
63  *      "naa.60014054ac780582").
64  *
65  * v-dev
66  *      Values:         string
67  *
68  *      A string specifying the frontend device in form of a 4-tuple "h:c:t:l"
69  *      (host, controller, target, lun, all integers).
70  *
71  *--------------------------------- Features ---------------------------------
72  *
73  * feature-sg-grant
74  *      Values:         unsigned [VSCSIIF_SG_TABLESIZE...65535]
75  *      Default Value:  0
76  *
77  *      Specifies the maximum number of scatter/gather elements in grant pages
78  *      supported. If not set, the backend supports up to VSCSIIF_SG_TABLESIZE
79  *      SG elements specified directly in the request.
80  *
81  *****************************************************************************
82  *                            Frontend XenBus Nodes
83  *****************************************************************************
84  *
85  *----------------------- Request Transport Parameters -----------------------
86  *
87  * event-channel
88  *      Values:         unsigned
89  *
90  *      The identifier of the Xen event channel used to signal activity
91  *      in the ring buffer.
92  *
93  * ring-ref
94  *      Values:         unsigned
95  *
96  *      The Xen grant reference granting permission for the backend to map
97  *      the sole page in a single page sized ring buffer.
98  *
99  * protocol
100  *      Values:         string (XEN_IO_PROTO_ABI_*)
101  *      Default Value:  XEN_IO_PROTO_ABI_NATIVE
102  *
103  *      The machine ABI rules governing the format of all ring request and
104  *      response structures.
105  */
106 
107 /* Requests from the frontend to the backend */
108 
109 /*
110  * Request a SCSI operation specified via a CDB in vscsiif_request.cmnd.
111  * The target is specified via channel, id and lun.
112  *
113  * The operation to be performed is specified via a CDB in cmnd[], the length
114  * of the CDB is in cmd_len. sc_data_direction specifies the direction of data
115  * (to the device, from the device, or none at all).
116  *
117  * If data is to be transferred to or from the device the buffer(s) in the
118  * guest memory is/are specified via one or multiple scsiif_request_segment
119  * descriptors each specifying a memory page via a grant_ref_t, a offset into
120  * the page and the length of the area in that page. All scsiif_request_segment
121  * areas concatenated form the resulting data buffer used by the operation.
122  * If the number of scsiif_request_segment areas is not too large (less than
123  * or equal VSCSIIF_SG_TABLESIZE) the areas can be specified directly in the
124  * seg[] array and the number of valid scsiif_request_segment elements is to be
125  * set in nr_segments.
126  *
127  * If "feature-sg-grant" in the Xenstore is set it is possible to specify more
128  * than VSCSIIF_SG_TABLESIZE scsiif_request_segment elements via indirection.
129  * The maximum number of allowed scsiif_request_segment elements is the value
130  * of the "feature-sg-grant" entry from Xenstore. When using indirection the
131  * seg[] array doesn't contain specifications of the data buffers, but
132  * references to scsiif_request_segment arrays, which in turn reference the
133  * data buffers. While nr_segments holds the number of populated seg[] entries
134  * (plus the set VSCSIIF_SG_GRANT bit), the number of scsiif_request_segment
135  * elements referencing the target data buffers is calculated from the lengths
136  * of the seg[] elements (the sum of all valid seg[].length divided by the
137  * size of one scsiif_request_segment structure).
138  */
139 #define VSCSIIF_ACT_SCSI_CDB		1
140 
141 /*
142  * Request abort of a running operation for the specified target given by
143  * channel, id, lun and the operation's rqid in ref_rqid.
144  */
145 #define VSCSIIF_ACT_SCSI_ABORT		2
146 
147 /*
148  * Request a device reset of the specified target (channel and id).
149  */
150 #define VSCSIIF_ACT_SCSI_RESET		3
151 
152 /*
153  * Preset scatter/gather elements for a following request. Deprecated.
154  * Keeping the define only to avoid usage of the value "4" for other actions.
155  */
156 #define VSCSIIF_ACT_SCSI_SG_PRESET	4
157 
158 /*
159  * Maximum scatter/gather segments per request.
160  *
161  * Considering balance between allocating at least 16 "vscsiif_request"
162  * structures on one page (4096 bytes) and the number of scatter/gather
163  * elements needed, we decided to use 26 as a magic number.
164  *
165  * If "feature-sg-grant" is set, more scatter/gather elements can be specified
166  * by placing them in one or more (up to VSCSIIF_SG_TABLESIZE) granted pages.
167  * In this case the vscsiif_request seg elements don't contain references to
168  * the user data, but to the SG elements referencing the user data.
169  */
170 #define VSCSIIF_SG_TABLESIZE		26
171 
172 /*
173  * based on Linux kernel 2.6.18, still valid
174  * Changing these values requires support of multiple protocols via the rings
175  * as "old clients" will blindly use these values and the resulting structure
176  * sizes.
177  */
178 #define VSCSIIF_MAX_COMMAND_SIZE	16
179 #define VSCSIIF_SENSE_BUFFERSIZE	96
180 
181 struct scsiif_request_segment {
182 	grant_ref_t gref;
183 	uint16_t offset;
184 	uint16_t length;
185 };
186 
187 #define VSCSIIF_SG_PER_PAGE (PAGE_SIZE / sizeof(struct scsiif_request_segment))
188 
189 /* Size of one request is 252 bytes */
190 struct vscsiif_request {
191 	uint16_t rqid;		/* private guest value, echoed in resp  */
192 	uint8_t act;		/* command between backend and frontend */
193 	uint8_t cmd_len;	/* valid CDB bytes */
194 
195 	uint8_t cmnd[VSCSIIF_MAX_COMMAND_SIZE];	/* the CDB */
196 	uint16_t timeout_per_command;	/* deprecated */
197 	uint16_t channel, id, lun;	/* (virtual) device specification */
198 	uint16_t ref_rqid;		/* command abort reference */
199 	uint8_t sc_data_direction;	/* for DMA_TO_DEVICE(1)
200 					   DMA_FROM_DEVICE(2)
201 					   DMA_NONE(3) requests */
202 	uint8_t nr_segments;		/* Number of pieces of scatter-gather */
203 /*
204  * flag in nr_segments: SG elements via grant page
205  *
206  * If VSCSIIF_SG_GRANT is set, the low 7 bits of nr_segments specify the number
207  * of grant pages containing SG elements. Usable if "feature-sg-grant" set.
208  */
209 #define VSCSIIF_SG_GRANT	0x80
210 
211 	struct scsiif_request_segment seg[VSCSIIF_SG_TABLESIZE];
212 	uint32_t reserved[3];
213 };
214 
215 /* Size of one response is 252 bytes */
216 struct vscsiif_response {
217 	uint16_t rqid;		/* identifies request */
218 	uint8_t padding;
219 	uint8_t sense_len;
220 	uint8_t sense_buffer[VSCSIIF_SENSE_BUFFERSIZE];
221 	int32_t rslt;
222 	uint32_t residual_len;	/* request bufflen -
223 				   return the value from physical device */
224 	uint32_t reserved[36];
225 };
226 
227 DEFINE_RING_TYPES(vscsiif, struct vscsiif_request, struct vscsiif_response);
228 
229 #endif /*__XEN__PUBLIC_IO_SCSI_H__*/
230