1/* $NetBSD: chio.h,v 1.14 2025/07/01 21:07:30 andvar Exp $ */
2
3/*-
4 * Copyright (c) 1996, 1999 The NetBSD Foundation, Inc.
5 * All rights reserved.
6 *
7 * This code is derived from software contributed to The NetBSD Foundation
8 * by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
9 * NASA Ames Research Center.
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
13 * are met:
14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer.
16 * 2. Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in the
18 * documentation and/or other materials provided with the distribution.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
24 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 * POSSIBILITY OF SUCH DAMAGE.
31 */
32
33#ifndef _SYS_CHIO_H_
34#define _SYS_CHIO_H_
35
36#include <sys/ioccom.h>
37
38/*
39 * Element types. Used as "to" and "from" type indicators in move
40 * and exchange operations.
41 *
42 * Note that code in sys/dev/scsipi/ch.c relies on these values (uses
43 * them as offsets in an array, and other evil), so don't muck with them
44 * unless you know what you're doing.
45 */
46#define CHET_MT 0 /* medium transport (picker) */
47#define CHET_ST 1 /* storage transport (slot) */
48#define CHET_IE 2 /* import/export (portal) */
49#define CHET_DT 3 /* data transfer (drive) */
50
51/*
52 * Structure used to execute a MOVE MEDIUM command.
53 */
54struct changer_move_request {
55 int cm_fromtype; /* element type to move from */
56 int cm_fromunit; /* logical unit of from element */
57 int cm_totype; /* element type to move to */
58 int cm_tounit; /* logical unit of to element */
59 int cm_flags; /* misc. flags */
60};
61
62/* cm_flags */
63#define CM_INVERT 0x01 /* invert media */
64
65/*
66 * Structure used to execute an EXCHANGE MEDIUM command. In an
67 * exchange operation, the following steps occur:
68 *
69 * - media from source is moved to first destination.
70 *
71 * - media previously occupying first destination is moved
72 * to the second destination.
73 *
74 * The second destination may or may not be the same as the source.
75 * In the case of a simple exchange, the source and second destination
76 * are the same.
77 */
78struct changer_exchange_request {
79 int ce_srctype; /* element type of source */
80 int ce_srcunit; /* logical unit of source */
81 int ce_fdsttype; /* element type of first destination */
82 int ce_fdstunit; /* logical unit of first destination */
83 int ce_sdsttype; /* element type of second destination */
84 int ce_sdstunit; /* logical unit of second destination */
85 int ce_flags; /* misc. flags */
86};
87
88/* ce_flags */
89#define CE_INVERT1 0x01 /* invert media 1 */
90#define CE_INVERT2 0x02 /* invert media 2 */
91
92/*
93 * Structure used to execute a POSITION TO ELEMENT command. This
94 * moves the current picker in front of the specified element.
95 */
96struct changer_position_request {
97 int cp_type; /* element type */
98 int cp_unit; /* logical unit of element */
99 int cp_flags; /* misc. flags */
100};
101
102/* cp_flags */
103#define CP_INVERT 0x01 /* invert picker */
104
105/*
106 * Data returned by CHIOGPARAMS.
107 */
108struct changer_params {
109 int cp_curpicker; /* current picker */
110 int cp_npickers; /* number of pickers */
111 int cp_nslots; /* number of slots */
112 int cp_nportals; /* number of import/export portals */
113 int cp_ndrives; /* number of drives */
114};
115
116/*
117 * Old-style command used to get element status.
118 */
119struct ochanger_element_status_request {
120 int cesr_type; /* element type */
121 uint8_t *cesr_data; /* pre-allocated data storage */
122};
123
124/*
125 * Structure of a changer volume tag.
126 */
127#define CHANGER_VOLTAG_SIZE 32 /* same as SCSI voltag size */
128struct changer_voltag {
129 char cv_tag[CHANGER_VOLTAG_SIZE + 1]; /* ASCII tag */
130 uint16_t cv_serial; /* serial number */
131};
132
133/*
134 * Data returned by CHIOGSTATUS.
135 */
136struct changer_element_status {
137 int ces_flags; /* CESTATUS_* flags; see below */
138
139 /*
140 * The following is only valid on Data Transport elements (drives).
141 */
142 char ces_xname[16]; /* external name of drive device */
143
144 /*
145 * The following fields indicate the element the medium was
146 * moved from in order to arrive in this element.
147 */
148 int ces_from_type; /* type of element */
149 int ces_from_unit; /* logical unit of element */
150
151 /*
152 * Volume tag information.
153 */
154 struct changer_voltag ces_pvoltag; /* primary volume tag */
155 struct changer_voltag ces_avoltag; /* alternate volume tag */
156
157 size_t ces_vendor_len; /* length of any vendor-specific data */
158
159 /*
160 * These two fields are only valid if CESTATUS_EXCEPT is
161 * set in ces_flags, and are only valid on SCSI changers.
162 */
163 uint8_t ces_asc; /* Additional Sense Code */
164 uint8_t ces_ascq; /* Additional Sense Code Qualifier */
165
166 /*
167 * These two fields may be useful if ces_xname is not valid.
168 * They indicate the target and lun of a drive element. These
169 * are only valid on SCSI changers.
170 */
171 uint8_t ces_target; /* SCSI target of drive */
172 uint8_t ces_lun; /* SCSI LUN of drive */
173};
174
175/*
176 * Flags for changer_element_status. These are flags that are returned
177 * by hardware. Not all flags have meaning for all element types.
178 */
179#define CESTATUS_FULL 0x0001 /* element is full */
180#define CESTATUS_IMPEXP 0x0002 /* media deposited by operator */
181#define CESTATUS_EXCEPT 0x0004 /* element in abnormal state */
182#define CESTATUS_ACCESS 0x0008 /* media accessible by picker */
183#define CESTATUS_EXENAB 0x0010 /* element supports exporting */
184#define CESTATUS_INENAB 0x0020 /* element supports importing */
185
186#define CESTATUS_PICKER_MASK 0x0005 /* flags valid for pickers */
187#define CESTATUS_SLOT_MASK 0x000c /* flags valid for slots */
188#define CESTATUS_PORTAL_MASK 0x003f /* flags valid for portals */
189#define CESTATUS_DRIVE_MASK 0x000c /* flags valid for drives */
190
191#define CESTATUS_INVERTED 0x0040 /* medium inverted from storage */
192#define CESTATUS_NOTBUS 0x0080 /* drive not on same bus as changer */
193
194/*
195 * These changer_element_status flags indicate the validity of fields
196 * in the returned data.
197 */
198#define CESTATUS_STATUS_VALID 0x0100 /* entire structure valid */
199#define CESTATUS_XNAME_VALID 0x0200 /* ces_xname valid */
200#define CESTATUS_FROM_VALID 0x0400 /* ces_from_* valid */
201#define CESTATUS_PVOL_VALID 0x0800 /* ces_pvoltag valid */
202#define CESTATUS_AVOL_VALID 0x1000 /* ces_avoltag valid */
203#define CESTATUS_TARGET_VALID 0x2000 /* ces_target valid */
204#define CESTATUS_LUN_VALID 0x4000 /* ces_lun valid */
205
206#define CESTATUS_BITS \
207 "\20\6INEAB\5EXENAB\4ACCESS\3EXCEPT\2IMPEXP\1FULL"
208
209/*
210 * Command used to get element status.
211 */
212struct changer_element_status_request {
213 int cesr_type; /* element type */
214 int cesr_unit; /* start at this unit */
215 int cesr_count; /* for this many units */
216 int cesr_flags; /* flags; see below */
217 /* pre-allocated data storage */
218 /*
219 * These fields point to the data to be returned to the
220 * user:
221 *
222 * cesr_deta: pointer to array of cesr_count status descriptors
223 *
224 * cesr_vendor_data: pointer to array of void *'s which point
225 * to pre-allocated areas for vendor-specific data. Optional.
226 */
227 struct changer_element_status *cesr_data;
228 void **cesr_vendor_data;
229};
230
231#define CESR_VOLTAGS 0x01 /* request volume tags */
232
233/*
234 * Command used to modify a media element's volume tag.
235 */
236struct changer_set_voltag_request {
237 int csvr_type; /* element type */
238 int csvr_unit; /* unit to modify */
239 int csvr_flags; /* flags; see below */
240 /* the actual volume tag; ignored if clearing
241 the tag */
242 struct changer_voltag csvr_voltag;
243};
244
245#define CSVR_MODE_SET 0x00 /* set volume tag if not set */
246#define CSVR_MODE_REPLACE 0x01 /* unconditionally replace volume tag */
247#define CSVR_MODE_CLEAR 0x02 /* clear volume tag */
248#define CSVR_MODE_MASK 0x0f
249#define CSVR_ALTERNATE 0x10 /* modify alternate volume tag */
250
251/*
252 * Changer events.
253 *
254 * When certain events occur, the kernel can indicate this by setting
255 * a bit in a bitmask.
256 *
257 * When a read is issued to the changer, the kernel returns this event
258 * bitmask. The read never blocks; if no events are pending, the bitmask
259 * will be all-clear.
260 *
261 * A process may select for read to wait for an event to occur.
262 *
263 * The event mask is cleared when the changer is closed.
264 */
265#define CHANGER_EVENT_SIZE sizeof(u_int)
266#define CHEV_ELEMENT_STATUS_CHANGED 0x00000001
267
268/*
269 * ioctls applicable to changers.
270 */
271#define CHIOMOVE _IOW('c', 0x01, struct changer_move_request)
272#define CHIOEXCHANGE _IOW('c', 0x02, struct changer_exchange_request)
273#define CHIOPOSITION _IOW('c', 0x03, struct changer_position_request)
274#define CHIOGPICKER _IOR('c', 0x04, int)
275#define CHIOSPICKER _IOW('c', 0x05, int)
276#define CHIOGPARAMS _IOR('c', 0x06, struct changer_params)
277#define CHIOIELEM _IO('c', 0x07)
278#define OCHIOGSTATUS _IOW('c', 0x08, struct ochanger_element_status_request)
279#define CHIOGSTATUS _IOW('c', 0x09, struct changer_element_status_request)
280#define CHIOSVOLTAG _IOW('c', 0x0a, struct changer_set_voltag_request)
281
282#endif /* _SYS_CHIO_H_ */