xref: /freebsd/sys/cam/scsi/scsi_ch.h (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1 /* $FreeBSD$ */
2 /*	$NetBSD: scsi_changer.h,v 1.11 1998/02/13 08:28:32 enami Exp $	*/
3 
4 /*-
5  * Copyright (c) 1996 Jason R. Thorpe <thorpej@and.com>
6  * All rights reserved.
7  *
8  * Partially based on an autochanger driver written by Stefan Grefen
9  * and on an autochanger driver written by the Systems Programming Group
10  * at the University of Utah Computer Science Department.
11  *
12  * Redistribution and use in source and binary forms, with or without
13  * modification, are permitted provided that the following conditions
14  * are met:
15  * 1. Redistributions of source code must retain the above copyright
16  *    notice, this list of conditions and the following disclaimer.
17  * 2. Redistributions in binary form must reproduce the above copyright
18  *    notice, this list of conditions and the following disclaimer in the
19  *    documentation and/or other materials provided with the distribution.
20  * 3. All advertising materials mentioning features or use of this software
21  *    must display the following acknowledgements:
22  *	This product includes software developed by Jason R. Thorpe
23  *	for And Communications, http://www.and.com/
24  * 4. The name of the author may not be used to endorse or promote products
25  *    derived from this software without specific prior written permission.
26  *
27  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
32  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
33  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
34  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
35  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
36  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37  * SUCH DAMAGE.
38  */
39 
40 /*
41  * SCSI changer interface description
42  */
43 
44 /*-
45  * Partially derived from software written by Stefan Grefen
46  * (grefen@goofy.zdv.uni-mainz.de soon grefen@convex.com)
47  * based on the SCSI System by written Julian Elischer (julian@tfs.com)
48  * for TRW Financial Systems.
49  *
50  * TRW Financial Systems, in accordance with their agreement with Carnegie
51  * Mellon University, makes this software available to CMU to distribute
52  * or use in any manner that they see fit as long as this message is kept with
53  * the software. For this reason TFS also grants any other persons or
54  * organisations permission to use or modify this software.
55  *
56  * TFS supplies this software to be publicly redistributed
57  * on the understanding that TFS is not responsible for the correct
58  * functioning of this software in any circumstances.
59  *
60  * Ported to run under 386BSD by Julian Elischer (julian@tfs.com) Sept 1992
61  */
62 
63 #ifndef _SCSI_SCSI_CH_H
64 #define _SCSI_SCSI_CH_H 1
65 
66 #include <sys/cdefs.h>
67 
68 /*
69  * SCSI command format
70  */
71 
72 /*
73  * Exchange the medium in the source element with the medium
74  * located at the destination element.
75  */
76 struct scsi_exchange_medium {
77 	u_int8_t	opcode;
78 #define EXCHANGE_MEDIUM		0xa6
79 	u_int8_t	byte2;
80 	u_int8_t	tea[2];	/* transport element address */
81 	u_int8_t	src[2];	/* source address */
82 	u_int8_t	fdst[2]; /* first destination address */
83 	u_int8_t	sdst[2]; /* second destination address */
84 	u_int8_t	invert;
85 #define EXCHANGE_MEDIUM_INV1	0x01
86 #define EXCHANGE_MEDIUM_INV2	0x02
87 	u_int8_t	control;
88 };
89 
90 /*
91  * Cause the medium changer to check all elements for medium and any
92  * other status relevant to the element.
93  */
94 struct scsi_initialize_element_status {
95 	u_int8_t	opcode;
96 #define INITIALIZE_ELEMENT_STATUS	0x07
97 	u_int8_t	byte2;
98 	u_int8_t	reserved[3];
99 	u_int8_t	control;
100 };
101 
102 /*
103  * Request the changer to move a unit of media from the source element
104  * to the destination element.
105  */
106 struct scsi_move_medium {
107 	u_int8_t	opcode;
108 #define MOVE_MEDIUM	0xa5
109 	u_int8_t	byte2;
110 	u_int8_t	tea[2];	/* transport element address */
111 	u_int8_t	src[2];	/* source element address */
112 	u_int8_t	dst[2];	/* destination element address */
113 	u_int8_t	reserved[2];
114 	u_int8_t	invert;
115 #define MOVE_MEDIUM_INVERT	0x01
116 	u_int8_t	control;
117 };
118 
119 /*
120  * Position the specified transport element (picker) in front of
121  * the destination element specified.
122  */
123 struct scsi_position_to_element {
124 	u_int8_t	opcode;
125 #define POSITION_TO_ELEMENT	0x2b
126 	u_int8_t	byte2;
127 	u_int8_t	tea[2];	/* transport element address */
128 	u_int8_t	dst[2];	/* destination element address */
129 	u_int8_t	reserved[2];
130 	u_int8_t	invert;
131 #define POSITION_TO_ELEMENT_INVERT	0x01
132 	u_int8_t	control;
133 };
134 
135 /*
136  * Request that the changer report the status of its internal elements.
137  */
138 struct scsi_read_element_status {
139 	u_int8_t	opcode;
140 #define READ_ELEMENT_STATUS	0xb8
141 	u_int8_t	byte2;
142 #define READ_ELEMENT_STATUS_VOLTAG	0x10	/* report volume tag info */
143 	/* ...next 4 bits are an element type code... */
144 	u_int8_t	sea[2];	/* starting element address */
145 	u_int8_t	count[2]; /* number of elements */
146 	u_int8_t	reserved0;
147 	u_int8_t	len[3];	/* length of data buffer */
148 	u_int8_t	reserved1;
149 	u_int8_t	control;
150 };
151 
152 struct scsi_request_volume_element_address {
153 	u_int8_t	opcode;
154 #define REQUEST_VOLUME_ELEMENT_ADDRESS	0xb5
155 	u_int8_t	byte2;
156 #define REQUEST_VOLUME_ELEMENT_ADDRESS_VOLTAG	0x10
157 	/* ...next 4 bits are an element type code... */
158 	u_int8_t	eaddr[2];	/* element address */
159 	u_int8_t	count[2];	/* number of elements */
160 	u_int8_t	reserved0;
161 	u_int8_t	len[3];		/* length of data buffer */
162 	u_int8_t	reserved1;
163 	u_int8_t	control;
164 };
165 
166 /* XXX scsi_release */
167 
168 /*
169  * Changer-specific mode page numbers.
170  */
171 #define	CH_ELEMENT_ADDR_ASSIGN_PAGE	0x1D
172 #define	CH_TRANS_GEOM_PARAMS_PAGE	0x1E
173 #define	CH_DEVICE_CAP_PAGE		0x1F
174 
175 /*
176  * Data returned by READ ELEMENT STATUS consists of an 8-byte header
177  * followed by one or more read_element_status_pages.
178  */
179 struct read_element_status_header {
180 	u_int8_t	fear[2];  /* first element address reported */
181 	u_int8_t	count[2]; /* number of elements available */
182 	u_int8_t	reserved;
183 	u_int8_t	nbytes[3]; /* byte count of all pages */
184 };
185 
186 struct read_element_status_page_header {
187 	u_int8_t	type;	/* element type code; see type codes below */
188 	u_int8_t	flags;
189 #define READ_ELEMENT_STATUS_AVOLTAG	0x40
190 #define READ_ELEMENT_STATUS_PVOLTAG	0x80
191 	u_int8_t	edl[2];	/* element descriptor length */
192 	u_int8_t	reserved;
193 	u_int8_t	nbytes[3]; /* byte count of all descriptors */
194 };
195 
196 /*
197  * Format of a volume tag
198  */
199 
200 struct volume_tag {
201 	u_int8_t	vif[32];	/* volume identification field */
202 	u_int8_t	reserved[2];
203 	u_int8_t	vsn[2];		/* volume sequence number */
204 };
205 
206 struct read_element_status_descriptor {
207 	u_int8_t	eaddr[2];	/* element address */
208 	u_int8_t	flags1;
209 
210 #define READ_ELEMENT_STATUS_FULL	0x01
211 #define READ_ELEMENT_STATUS_IMPEXP	0x02
212 #define READ_ELEMENT_STATUS_EXCEPT	0x04
213 #define READ_ELEMENT_STATUS_ACCESS	0x08
214 #define READ_ELEMENT_STATUS_EXENAB	0x10
215 #define READ_ELEMENT_STATUS_INENAB	0x20
216 
217 #define READ_ELEMENT_STATUS_MT_MASK1	0x05
218 #define READ_ELEMENT_STATUS_ST_MASK1	0x0c
219 #define READ_ELEMENT_STATUS_IE_MASK1	0x3f
220 #define READ_ELEMENT_STATUS_DT_MASK1	0x0c
221 
222 	u_int8_t	reserved0;
223 	u_int8_t	sense_code;
224 	u_int8_t	sense_qual;
225 
226 	/*
227 	 * dt_scsi_flags and dt_scsi_addr are valid only on data transport
228 	 * elements.  These bytes are undefined for all other element types.
229 	 */
230 	u_int8_t	dt_scsi_flags;
231 
232 #define READ_ELEMENT_STATUS_DT_LUNMASK	0x07
233 #define READ_ELEMENT_STATUS_DT_LUVALID	0x10
234 #define READ_ELEMENT_STATUS_DT_IDVALID	0x20
235 #define READ_ELEMENT_STATUS_DT_NOTBUS	0x80
236 
237 	u_int8_t	dt_scsi_addr;
238 
239 	u_int8_t	reserved1;
240 
241 	u_int8_t	flags2;
242 #define READ_ELEMENT_STATUS_INVERT	0x40
243 #define READ_ELEMENT_STATUS_SVALID	0x80
244 	u_int8_t	ssea[2];	/* source storage element address */
245 
246 	struct volume_tag pvoltag;	/* omitted if PVOLTAG == 0 */
247 	struct volume_tag avoltag;	/* omitted if AVOLTAG == 0 */
248 
249 	/* Other data may follow */
250 };
251 
252 /* XXX add data returned by REQUEST VOLUME ELEMENT ADDRESS */
253 
254 /* Element type codes */
255 #define ELEMENT_TYPE_MASK	0x0f	/* Note: these aren't bits */
256 #define ELEMENT_TYPE_ALL	0x00
257 #define ELEMENT_TYPE_MT		0x01
258 #define ELEMENT_TYPE_ST		0x02
259 #define ELEMENT_TYPE_IE		0x03
260 #define ELEMENT_TYPE_DT		0x04
261 
262 /*
263  * XXX The following definitions should be common to all SCSI device types.
264  */
265 #define PGCODE_MASK	0x3f	/* valid page number bits in pg_code */
266 #define PGCODE_PS	0x80	/* indicates page is savable */
267 
268 /*
269  * Send volume tag information to the changer
270  */
271 
272 struct scsi_send_volume_tag {
273 	u_int8_t	opcode;
274 #define SEND_VOLUME_TAG	0xb6
275 	u_int8_t	byte2;
276 	u_int8_t	ea[2];		/* element address */
277 	u_int8_t	reserved2;
278   	u_int8_t	sac;		/* send action code */
279 
280 #define SEND_VOLUME_TAG_ASSERT_PRIMARY		0x08
281 #define SEND_VOLUME_TAG_ASSERT_ALTERNATE	0x09
282 #define SEND_VOLUME_TAG_REPLACE_PRIMARY		0x0a
283 #define SEND_VOLUME_TAG_REPLACE_ALTERNATE	0x0b
284 #define SEND_VOLUME_TAG_UNDEFINED_PRIMARY	0x0c
285 #define SEND_VOLUME_TAG_UNDEFINED_ALTERNATE	0x0d
286 
287 	u_int8_t	reserved4[2];
288 	u_int8_t	pll[2];		/* parameter list length */
289 	u_int8_t	reserved5;
290 	u_int8_t	control;
291 };
292 
293 /*
294  * Parameter format for SEND VOLUME TAG
295  */
296 
297 struct scsi_send_volume_tag_parameters {
298 	u_int8_t	vitf[32];	/* volume tag identification template */
299 	u_int8_t	reserved1[2];
300 	u_int8_t	minvsn[2];	/* minimum volume sequence number */
301 	u_int8_t	reserved2[2];
302 	u_int8_t	maxvsn[2];	/* maximum volume sequence number */
303 };
304 
305 /*
306  * Device capabilities page.
307  *
308  * This page defines characteristics of the elemenet types in the
309  * medium changer device.
310  *
311  * Note in the definitions below, the following abbreviations are
312  * used:
313  *		MT	Medium transport element (picker)
314  *		ST	Storage transport element (slot)
315  *		IE	Import/export element (portal)
316  *		DT	Data tranfer element (tape/disk drive)
317  */
318 struct page_device_capabilities {
319 	u_int8_t	pg_code;	/* page code (0x1f) */
320 	u_int8_t	pg_length;	/* page length (0x12) */
321 
322 	/*
323 	 * The STOR_xx bits indicate that an element of a given
324 	 * type may provide independent storage for a unit of
325 	 * media.  The top four bits of this value are reserved.
326 	 */
327 	u_int8_t	stor;
328 #define STOR_MT		0x01
329 #define STOR_ST		0x02
330 #define STOR_IE		0x04
331 #define STOR_DT		0x08
332 
333 	u_int8_t	reserved0;
334 
335 	/*
336 	 * The MOVE_TO_yy bits indicate the changer supports
337 	 * moving a unit of medium from an element of a given type to an
338 	 * element of type yy.  This is used to determine if a given
339 	 * MOVE MEDIUM command is legal.  The top four bits of each
340 	 * of these values are reserved.
341 	 */
342 	u_int8_t	move_from[CHET_MAX + 1];
343 #define MOVE_TO_MT	0x01
344 #define MOVE_TO_ST	0x02
345 #define MOVE_TO_IE	0x04
346 #define MOVE_TO_DT	0x08
347 
348 	u_int8_t	reserved1[4];
349 
350 	/*
351 	 * Similar to above, but for EXCHANGE MEDIUM.
352 	 */
353 	u_int8_t	exchange_with[CHET_MAX + 1];
354 #define EXCHANGE_WITH_MT	0x01
355 #define EXCHANGE_WITH_ST	0x02
356 #define EXCHANGE_WITH_IE	0x04
357 #define EXCHANGE_WITH_DT	0x08
358 };
359 
360 /*
361  * Medium changer elemement address assignment page.
362  *
363  * Some of these fields can be a little confusing, so an explanation
364  * is in order.
365  *
366  * Each component within a a medium changer apparatus is called an
367  * "element".
368  *
369  * The "medium transport element address" is the address of the first
370  * picker (robotic arm).  "Number of medium transport elements" tells
371  * us how many pickers exist in the changer.
372  *
373  * The "first storage element address" is the address of the first
374  * slot in the tape or disk magazine.  "Number of storage elements" tells
375  * us how many slots exist in the changer.
376  *
377  * The "first import/export element address" is the address of the first
378  * medium portal accessible both by the medium changer and an outside
379  * human operator.  This is where the changer might deposit tapes destined
380  * for some vault.  The "number of import/export elements" tells us
381  * not many of these portals exist in the changer.  NOTE: this number may
382  * be 0.
383  *
384  * The "first data transfer element address" is the address of the first
385  * tape or disk drive in the changer.  "Number of data transfer elements"
386  * tells us how many drives exist in the changer.
387  */
388 struct page_element_address_assignment {
389 	u_int8_t	pg_code;	/* page code (0x1d) */
390 	u_int8_t	pg_length;	/* page length (0x12) */
391 
392 	/* Medium transport element address */
393 	u_int8_t	mtea[2];
394 
395 	/* Number of medium transport elements */
396 	u_int8_t	nmte[2];
397 
398 	/* First storage element address */
399 	u_int8_t	fsea[2];
400 
401 	/* Number of storage elements */
402 	u_int8_t	nse[2];
403 
404 	/* First import/export element address */
405 	u_int8_t	fieea[2];
406 
407 	/* Number of import/export elements */
408 	u_int8_t	niee[2];
409 
410 	/* First data transfer element address */
411 	u_int8_t	fdtea[2];
412 
413 	/* Number of data trafer elements */
414 	u_int8_t	ndte[2];
415 
416 	u_int8_t	reserved[2];
417 };
418 
419 /*
420  * Transport geometry parameters page.
421  *
422  * Defines whether each medium transport element is a member of a set of
423  * elements that share a common robotics subsystem and whether the element
424  * is capable of media rotation.  One transport geometry descriptor is
425  * transferred for each medium transport element, beginning with the first
426  * medium transport element (other than the default transport element address
427  * of 0).
428  */
429 struct page_transport_geometry_parameters {
430 	u_int8_t	pg_code;	/* page code (0x1e) */
431 	u_int8_t	pg_length;	/* page length; variable */
432 
433 	/* Transport geometry descriptor(s) are here. */
434 
435 	u_int8_t	misc;
436 #define CAN_ROTATE	0x01
437 
438 	/* Member number in transport element set. */
439 	u_int8_t	member;
440 };
441 
442 __BEGIN_DECLS
443 void scsi_move_medium(struct ccb_scsiio *csio, u_int32_t retries,
444 		      void (*cbfcnp)(struct cam_periph *, union ccb *),
445 		      u_int8_t tag_action, u_int32_t tea, u_int32_t src,
446 		      u_int32_t dst, int invert, u_int8_t sense_len,
447 		      u_int32_t timeout);
448 
449 void scsi_exchange_medium(struct ccb_scsiio *csio, u_int32_t retries,
450 			  void (*cbfcnp)(struct cam_periph *, union ccb *),
451 			  u_int8_t tag_action, u_int32_t tea, u_int32_t src,
452 			  u_int32_t dst1, u_int32_t dst2, int invert1,
453 			  int invert2, u_int8_t sense_len, u_int32_t timeout);
454 
455 void scsi_position_to_element(struct ccb_scsiio *csio, u_int32_t retries,
456 			      void (*cbfcnp)(struct cam_periph *, union ccb *),
457 			      u_int8_t tag_action, u_int32_t tea, u_int32_t dst,
458 			      int invert, u_int8_t sense_len,
459 			      u_int32_t timeout);
460 
461 void scsi_read_element_status(struct ccb_scsiio *csio, u_int32_t retries,
462 			      void (*cbfcnp)(struct cam_periph *, union ccb *),
463 			      u_int8_t tag_action, int voltag, u_int32_t sea,
464 			      u_int32_t count, u_int8_t *data_ptr,
465 			      u_int32_t dxfer_len, u_int8_t sense_len,
466 			      u_int32_t timeout);
467 
468 void scsi_initialize_element_status(struct ccb_scsiio *csio, u_int32_t retries,
469 			       void (*cbfcnp)(struct cam_periph *, union ccb *),
470 			       u_int8_t tag_action, u_int8_t sense_len,
471 			       u_int32_t timeout);
472 void scsi_send_volume_tag(struct ccb_scsiio *csio, u_int32_t retries,
473 			  void (*cbfcnp)(struct cam_periph *, union ccb *),
474 			  u_int8_t tag_action,
475 			  u_int16_t element_address,
476 			  u_int8_t send_action_code,
477 			  struct scsi_send_volume_tag_parameters *parameters,
478 			  u_int8_t sense_len, u_int32_t timeout);
479 __END_DECLS
480 
481 #endif /* _SCSI_SCSI_CH_H */
482