Merge master.kernel.org:/pub/scm/linux/kernel/git/gregkh/pci-2.6
[linux-2.6] / Documentation / i2o / ioctl
1
2 Linux I2O User Space Interface
3 rev 0.3 - 04/20/99
4
5 =============================================================================
6 Originally written by Deepak Saxena(deepak@plexity.net)
7 Currently maintained by Deepak Saxena(deepak@plexity.net)
8 =============================================================================
9
10 I. Introduction
11
12 The Linux I2O subsystem provides a set of ioctl() commands that can be
13 utilized by user space applications to communicate with IOPs and devices
14 on individual IOPs. This document defines the specific ioctl() commands
15 that are available to the user and provides examples of their uses.
16
17 This document assumes the reader is familiar with or has access to the
18 I2O specification as no I2O message parameters are outlined.  For information
19 on the specification, see http://www.i2osig.org
20
21 This document and the I2O user space interface are currently maintained
22 by Deepak Saxena.  Please send all comments, errata, and bug fixes to
23 deepak@csociety.purdue.edu
24
25 II. IOP Access
26
27 Access 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
29 number 166.  It can be created through the following command:
30
31    mknod /dev/i2o/ctl c 10 166
32
33 III. 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
55 IV. 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
84 V. 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
113 VI. Settting 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 appropriatly:
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
154 VII. 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
191 VIII. 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 appropriatly:
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
232 IX. 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 appropriatly:
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
274 X. 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 appropriatly:
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
311 X. 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 appropriatly:
329
330       ETIMEDOUT   Timeout waiting for reply message
331       ENXIO       Invalid IOP number
332
333 XI. 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 appropriatly:
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
372 XII. 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 =============================================================================
381 Revision History
382 =============================================================================
383
384 Rev 0.1 - 04/01/99
385 - Initial revision
386
387 Rev 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
392 Rev 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