1
2 Linux I2O Support (c) Copyright 1999 Red Hat Software
3 and others.
4
5 This program is free software; you can redistribute it and/or
6 modify it under the terms of the GNU General Public License
7 as published by the Free Software Foundation; either version
8 2 of the License, or (at your option) any later version.
9
10AUTHORS (so far)
11
12Alan Cox, Building Number Three Ltd.
13 Core code, SCSI and Block OSMs
14
15Steve Ralston, LSI Logic Corp.
16 Debugging SCSI and Block OSM
17
18Deepak Saxena, Intel Corp.
19 Various core/block extensions
20 /proc interface, bug fixes
21 Ioctl interfaces for control
22 Debugging LAN OSM
23
24Philip Rumpf
25 Fixed assorted dumb SMP locking bugs
26
27Juha Sievanen, University of Helsinki Finland
28 LAN OSM code
29 /proc interface to LAN class
30 Bug fixes
31 Core code extensions
32
33Auvo Häkkinen, University of Helsinki Finland
34 LAN OSM code
35 /Proc interface to LAN class
36 Bug fixes
37 Core code extensions
38
39Taneli Vähäkangas, University of Helsinki Finland
40 Fixes to i2o_config
41
42CREDITS
43
44 This work was made possible by
45
46Red Hat Software
47 Funding for the Building #3 part of the project
48
49Symbios Logic (Now LSI)
50 Host adapters, hints, known to work platforms when I hit
51 compatibility problems
52
53BoxHill Corporation
54 Loan of initial FibreChannel disk array used for development work.
55
56European Commission
57 Funding the work done by the University of Helsinki
58
59SysKonnect
60 Loan of FDDI and Gigabit Ethernet cards
61
62ASUSTeK
63 Loan of I2O motherboard
64
65STATUS:
66
67o The core setup works within limits.
68o The scsi layer seems to almost work.
69 I'm still chasing down the hang bug.
70o The block OSM is mostly functional
71o LAN OSM works with FDDI and Ethernet cards.
72
73TO DO:
74
75General:
76o Provide hidden address space if asked
77o Long term message flow control
78o PCI IOP's without interrupts are not supported yet
79o Push FAIL handling into the core
80o DDM control interfaces for module load etc
81o Add I2O 2.0 support (Deffered to 2.5 kernel)
82
83Block:
84o Multiple major numbers
85o Read ahead and cache handling stuff. Talk to Ingo and people
86o Power management
87o Finish Media changers
88
89SCSI:
90o Find the right way to associate drives/luns/busses
91
92Lan:
93o Performance tuning
94o Test Fibre Channel code
95
96Tape:
97o Anyone seen anything implementing this ?
98 (D.S: Will attempt to do so if spare cycles permit)
99
1
2Linux I2O User Space Interface
3rev 0.3 - 04/20/99
4
5=============================================================================
6Originally written by Deepak Saxena(deepak@plexity.net)
7Currently maintained by Deepak Saxena(deepak@plexity.net)
8=============================================================================
9
10I. Introduction
11
12The Linux I2O subsystem provides a set of ioctl() commands that can be
13utilized by user space applications to communicate with IOPs and devices
14on individual IOPs. This document defines the specific ioctl() commands
15that are available to the user and provides examples of their uses.
16
17This document assumes the reader is familiar with or has access to the
18I2O specification as no I2O message parameters are outlined. For information
19on the specification, see http://www.i2osig.org
20
21This document and the I2O user space interface are currently maintained
22by Deepak Saxena. Please send all comments, errata, and bug fixes to
23deepak@csociety.purdue.edu
24
25II. IOP Access
26
27Access to the I2O subsystem is provided through the device file named
28/dev/i2o/ctl. This file is a character file with major number 10 and minor
29number 166. It can be created through the following command:
30
31 mknod /dev/i2o/ctl c 10 166
32
33III. Determining the IOP Count
34
35 SYNOPSIS
36
37 ioctl(fd, I2OGETIOPS, int *count);
38
39 u8 count[MAX_I2O_CONTROLLERS];
40
41 DESCRIPTION
42
43 This function returns the system's active IOP table. count should
44 point to a buffer containing MAX_I2O_CONTROLLERS entries. Upon
45 returning, each entry will contain a non-zero value if the given
46 IOP unit is active, and NULL if it is inactive or non-existent.
47
48 RETURN VALUE.
49
50 Returns 0 if no errors occur, and -1 otherwise. If an error occurs,
51 errno is set appropriately:
52
53 EFAULT Invalid user space pointer was passed
54
55IV. Getting Hardware Resource Table
56
57 SYNOPSIS
58
59 ioctl(fd, I2OHRTGET, struct i2o_cmd_hrt *hrt);
60
61 struct i2o_cmd_hrtlct
62 {
63 u32 iop; /* IOP unit number */
64 void *resbuf; /* Buffer for result */
65 u32 *reslen; /* Buffer length in bytes */
66 };
67
68 DESCRIPTION
69
70 This function returns the Hardware Resource Table of the IOP specified
71 by hrt->iop in the buffer pointed to by hrt->resbuf. The actual size of
72 the data is written into *(hrt->reslen).
73
74 RETURNS
75
76 This function returns 0 if no errors occur. If an error occurs, -1
77 is returned and errno is set appropriately:
78
79 EFAULT Invalid user space pointer was passed
80 ENXIO Invalid IOP number
81 ENOBUFS Buffer not large enough. If this occurs, the required
82 buffer length is written into *(hrt->reslen)
83
84V. Getting Logical Configuration Table
85
86 SYNOPSIS
87
88 ioctl(fd, I2OLCTGET, struct i2o_cmd_lct *lct);
89
90 struct i2o_cmd_hrtlct
91 {
92 u32 iop; /* IOP unit number */
93 void *resbuf; /* Buffer for result */
94 u32 *reslen; /* Buffer length in bytes */
95 };
96
97 DESCRIPTION
98
99 This function returns the Logical Configuration Table of the IOP specified
100 by lct->iop in the buffer pointed to by lct->resbuf. The actual size of
101 the data is written into *(lct->reslen).
102
103 RETURNS
104
105 This function returns 0 if no errors occur. If an error occurs, -1
106 is returned and errno is set appropriately:
107
108 EFAULT Invalid user space pointer was passed
109 ENXIO Invalid IOP number
110 ENOBUFS Buffer not large enough. If this occurs, the required
111 buffer length is written into *(lct->reslen)
112
113VI. Setting Parameters
114
115 SYNOPSIS
116
117 ioctl(fd, I2OPARMSET, struct i2o_parm_setget *ops);
118
119 struct i2o_cmd_psetget
120 {
121 u32 iop; /* IOP unit number */
122 u32 tid; /* Target device TID */
123 void *opbuf; /* Operation List buffer */
124 u32 oplen; /* Operation List buffer length in bytes */
125 void *resbuf; /* Result List buffer */
126 u32 *reslen; /* Result List buffer length in bytes */
127 };
128
129 DESCRIPTION
130
131 This function posts a UtilParamsSet message to the device identified
132 by ops->iop and ops->tid. The operation list for the message is
133 sent through the ops->opbuf buffer, and the result list is written
134 into the buffer pointed to by ops->resbuf. The number of bytes
135 written is placed into *(ops->reslen).
136
137 RETURNS
138
139 The return value is the size in bytes of the data written into
140 ops->resbuf if no errors occur. If an error occurs, -1 is returned
141 and errno is set appropriately:
142
143 EFAULT Invalid user space pointer was passed
144 ENXIO Invalid IOP number
145 ENOBUFS Buffer not large enough. If this occurs, the required
146 buffer length is written into *(ops->reslen)
147 ETIMEDOUT Timeout waiting for reply message
148 ENOMEM Kernel memory allocation error
149
150 A return value of 0 does not mean that the value was actually
151 changed properly on the IOP. The user should check the result
152 list to determine the specific status of the transaction.
153
154VII. Getting Parameters
155
156 SYNOPSIS
157
158 ioctl(fd, I2OPARMGET, struct i2o_parm_setget *ops);
159
160 struct i2o_parm_setget
161 {
162 u32 iop; /* IOP unit number */
163 u32 tid; /* Target device TID */
164 void *opbuf; /* Operation List buffer */
165 u32 oplen; /* Operation List buffer length in bytes */
166 void *resbuf; /* Result List buffer */
167 u32 *reslen; /* Result List buffer length in bytes */
168 };
169
170 DESCRIPTION
171
172 This function posts a UtilParamsGet message to the device identified
173 by ops->iop and ops->tid. The operation list for the message is
174 sent through the ops->opbuf buffer, and the result list is written
175 into the buffer pointed to by ops->resbuf. The actual size of data
176 written is placed into *(ops->reslen).
177
178 RETURNS
179
180 EFAULT Invalid user space pointer was passed
181 ENXIO Invalid IOP number
182 ENOBUFS Buffer not large enough. If this occurs, the required
183 buffer length is written into *(ops->reslen)
184 ETIMEDOUT Timeout waiting for reply message
185 ENOMEM Kernel memory allocation error
186
187 A return value of 0 does not mean that the value was actually
188 properly retrieved. The user should check the result list
189 to determine the specific status of the transaction.
190
191VIII. Downloading Software
192
193 SYNOPSIS
194
195 ioctl(fd, I2OSWDL, struct i2o_sw_xfer *sw);
196
197 struct i2o_sw_xfer
198 {
199 u32 iop; /* IOP unit number */
200 u8 flags; /* DownloadFlags field */
201 u8 sw_type; /* Software type */
202 u32 sw_id; /* Software ID */
203 void *buf; /* Pointer to software buffer */
204 u32 *swlen; /* Length of software buffer */
205 u32 *maxfrag; /* Number of fragments */
206 u32 *curfrag; /* Current fragment number */
207 };
208
209 DESCRIPTION
210
211 This function downloads a software fragment pointed by sw->buf
212 to the iop identified by sw->iop. The DownloadFlags, SwID, SwType
213 and SwSize fields of the ExecSwDownload message are filled in with
214 the values of sw->flags, sw->sw_id, sw->sw_type and *(sw->swlen).
215
216 The fragments _must_ be sent in order and be 8K in size. The last
217 fragment _may_ be shorter, however. The kernel will compute its
218 size based on information in the sw->swlen field.
219
220 Please note that SW transfers can take a long time.
221
222 RETURNS
223
224 This function returns 0 no errors occur. If an error occurs, -1
225 is returned and errno is set appropriately:
226
227 EFAULT Invalid user space pointer was passed
228 ENXIO Invalid IOP number
229 ETIMEDOUT Timeout waiting for reply message
230 ENOMEM Kernel memory allocation error
231
232IX. Uploading Software
233
234 SYNOPSIS
235
236 ioctl(fd, I2OSWUL, struct i2o_sw_xfer *sw);
237
238 struct i2o_sw_xfer
239 {
240 u32 iop; /* IOP unit number */
241 u8 flags; /* UploadFlags */
242 u8 sw_type; /* Software type */
243 u32 sw_id; /* Software ID */
244 void *buf; /* Pointer to software buffer */
245 u32 *swlen; /* Length of software buffer */
246 u32 *maxfrag; /* Number of fragments */
247 u32 *curfrag; /* Current fragment number */
248 };
249
250 DESCRIPTION
251
252 This function uploads a software fragment from the IOP identified
253 by sw->iop, sw->sw_type, sw->sw_id and optionally sw->swlen fields.
254 The UploadFlags, SwID, SwType and SwSize fields of the ExecSwUpload
255 message are filled in with the values of sw->flags, sw->sw_id,
256 sw->sw_type and *(sw->swlen).
257
258 The fragments _must_ be requested in order and be 8K in size. The
259 user is responsible for allocating memory pointed by sw->buf. The
260 last fragment _may_ be shorter.
261
262 Please note that SW transfers can take a long time.
263
264 RETURNS
265
266 This function returns 0 if no errors occur. If an error occurs, -1
267 is returned and errno is set appropriately:
268
269 EFAULT Invalid user space pointer was passed
270 ENXIO Invalid IOP number
271 ETIMEDOUT Timeout waiting for reply message
272 ENOMEM Kernel memory allocation error
273
274X. Removing Software
275
276 SYNOPSIS
277
278 ioctl(fd, I2OSWDEL, struct i2o_sw_xfer *sw);
279
280 struct i2o_sw_xfer
281 {
282 u32 iop; /* IOP unit number */
283 u8 flags; /* RemoveFlags */
284 u8 sw_type; /* Software type */
285 u32 sw_id; /* Software ID */
286 void *buf; /* Unused */
287 u32 *swlen; /* Length of the software data */
288 u32 *maxfrag; /* Unused */
289 u32 *curfrag; /* Unused */
290 };
291
292 DESCRIPTION
293
294 This function removes software from the IOP identified by sw->iop.
295 The RemoveFlags, SwID, SwType and SwSize fields of the ExecSwRemove message
296 are filled in with the values of sw->flags, sw->sw_id, sw->sw_type and
297 *(sw->swlen). Give zero in *(sw->len) if the value is unknown. IOP uses
298 *(sw->swlen) value to verify correct identication of the module to remove.
299 The actual size of the module is written into *(sw->swlen).
300
301 RETURNS
302
303 This function returns 0 if no errors occur. If an error occurs, -1
304 is returned and errno is set appropriately:
305
306 EFAULT Invalid user space pointer was passed
307 ENXIO Invalid IOP number
308 ETIMEDOUT Timeout waiting for reply message
309 ENOMEM Kernel memory allocation error
310
311X. Validating Configuration
312
313 SYNOPSIS
314
315 ioctl(fd, I2OVALIDATE, int *iop);
316 u32 iop;
317
318 DESCRIPTION
319
320 This function posts an ExecConfigValidate message to the controller
321 identified by iop. This message indicates that the current
322 configuration is accepted. The iop changes the status of suspect drivers
323 to valid and may delete old drivers from its store.
324
325 RETURNS
326
327 This function returns 0 if no erro occur. If an error occurs, -1 is
328 returned and errno is set appropriately:
329
330 ETIMEDOUT Timeout waiting for reply message
331 ENXIO Invalid IOP number
332
333XI. Configuration Dialog
334
335 SYNOPSIS
336
337 ioctl(fd, I2OHTML, struct i2o_html *htquery);
338 struct i2o_html
339 {
340 u32 iop; /* IOP unit number */
341 u32 tid; /* Target device ID */
342 u32 page; /* HTML page */
343 void *resbuf; /* Buffer for reply HTML page */
344 u32 *reslen; /* Length in bytes of reply buffer */
345 void *qbuf; /* Pointer to HTTP query string */
346 u32 qlen; /* Length in bytes of query string buffer */
347 };
348
349 DESCRIPTION
350
351 This function posts an UtilConfigDialog message to the device identified
352 by htquery->iop and htquery->tid. The requested HTML page number is
353 provided by the htquery->page field, and the resultant data is stored
354 in the buffer pointed to by htquery->resbuf. If there is an HTTP query
355 string that is to be sent to the device, it should be sent in the buffer
356 pointed to by htquery->qbuf. If there is no query string, this field
357 should be set to NULL. The actual size of the reply received is written
358 into *(htquery->reslen).
359
360 RETURNS
361
362 This function returns 0 if no error occur. If an error occurs, -1
363 is returned and errno is set appropriately:
364
365 EFAULT Invalid user space pointer was passed
366 ENXIO Invalid IOP number
367 ENOBUFS Buffer not large enough. If this occurs, the required
368 buffer length is written into *(ops->reslen)
369 ETIMEDOUT Timeout waiting for reply message
370 ENOMEM Kernel memory allocation error
371
372XII. Events
373
374 In the process of determining this. Current idea is to have use
375 the select() interface to allow user apps to periodically poll
376 the /dev/i2o/ctl device for events. When select() notifies the user
377 that an event is available, the user would call read() to retrieve
378 a list of all the events that are pending for the specific device.
379
380=============================================================================
381Revision History
382=============================================================================
383
384Rev 0.1 - 04/01/99
385- Initial revision
386
387Rev 0.2 - 04/06/99
388- Changed return values to match UNIX ioctl() standard. Only return values
389 are 0 and -1. All errors are reported through errno.
390- Added summary of proposed possible event interfaces
391
392Rev 0.3 - 04/20/99
393- Changed all ioctls() to use pointers to user data instead of actual data
394- Updated error values to match the code
395