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