i386/linux/linux-2.3.21/drivers/i2o/README.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@plexity.net
  24
  25 II. IOP Access
  26
  27 Access to the I2O subsystem is provided through the device file named
  28 /dev/i2octl.  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/i2octl 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 retreived.  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 the software pointed by sw->buf to the
 212    iop identified by sw->iop. The DownloadFlags, SwID, SwType and SwSize
 213    fields of the ExecSwDownload message are filled in with the values of
 214    sw->flags, sw->sw_id, sw->sw_type and *(sw->swlen).
 215
 216    Once the ioctl() is called and software transfer begins, the
 217    user can read the value *(sw->maxfrag) and *(sw->curfrag) to
 218    determine the status of the software transfer. As the IOP
 219    is very slow when it comes to SW transfers, this can be
 220    used by a separate thread to report status to the user. The
 221    user _should not_ write to this memory location until the ioctl()
 222    has returned.
 223
 224    RETURNS
 225
 226    This function returns 0 no errors occur. If an error occurs, -1
 227    is returned and errno is set appropriatly:
 228
 229       EFAULT      Invalid user space pointer was passed
 230       ENXIO       Invalid IOP number
 231       ETIMEDOUT   Timeout waiting for reply message
 232       ENOMEM      Kernel memory allocation error
 233
 234 IX. Uploading Software
 235
 236    SYNOPSIS
 237
 238    ioctl(fd, I2OSWUL, struct i2o_sw_xfer *sw);
 239
 240       struct i2o_sw_xfer
 241       {
 242          u32   iop;      /* IOP unit number */
 243          u8    flags;    /* UploadFlags */
 244          u8    sw_type;  /* Software type */
 245          u32   sw_id;    /* Software ID */
 246          void  *buf;     /* Pointer to software buffer */
 247          u32   *swlen;   /* Length of software buffer */
 248          u32   *maxfrag; /* Number of fragments */
 249          u32   *curfrag; /* Current fragment number */
 250       };
 251
 252    DESCRIPTION
 253
 254    This function uploads software from the IOP identified by sw->iop
 255    and places it in the buffer pointed to by sw->buf. The length of the
 256    buffer is given in *(sw->swlen). The UploadFlags, SwID and SwType
 257    fields of the ExecSwUpload message are filled in
 258    with the values of sw->flags, sw->sw_id and sw->sw_type.
 259
 260    Once the ioctl() is called and software transfer begins, the
 261    user can read the value *(sw->maxfrag) and *(sw->curfrag) to
 262    determine the status of the software transfer.  As the IOP
 263    is very slow when it comes to SW transfers, this can be
 264    used by a separate thread to report status to the user. The
 265    user _should not_ write to this memory location until the ioctl()
 266    has returned.
 267
 268    RETURNS
 269
 270    This function returns 0 if no errors occur.  If an error occurs, -1
 271    is returned and errno is set appropriatly:
 272
 273       EFAULT      Invalid user space pointer was passed
 274       ENXIO       Invalid IOP number
 275       ETIMEDOUT   Timeout waiting for reply message
 276       ENOMEM      Kernel memory allocation error
 277
 278 X. Removing Software
 279
 280    SYNOPSIS
 281
 282    ioctl(fd, I2OSWDEL, struct i2o_sw_xfer *sw);
 283
 284       struct i2o_sw_xfer
 285       {
 286          u32   iop;      /* IOP unit number */
 287          u8    flags;    /* RemoveFlags */
 288          u8    sw_type;  /* Software type */
 289          u32   sw_id;    /* Software ID */
 290          void  *buf;     /* Unused */
 291          u32   *swlen;   /* Length of the software data */
 292          u32   *maxfrag; /* Unused */
 293          u32   *curfrag; /* Unused */
 294       };
 295
 296    DESCRIPTION
 297
 298    This function removes software from the IOP identified by sw->iop.
 299    The RemoveFlags, SwID, SwType and SwSize fields of the ExecSwRemove message
 300    are filled in with the values of sw->flags, sw->sw_id, sw->sw_type and
 301    *(sw->swlen). Give zero in *(sw->len) if the value is unknown. IOP uses
 302    *(sw->swlen) value to verify correct identication of the module to remove.
 303    The actual size of the module is written into *(sw->swlen).
 304
 305    RETURNS
 306
 307    This function returns 0 if no errors occur.  If an error occurs, -1
 308    is returned and errno is set appropriatly:
 309
 310       EFAULT      Invalid user space pointer was passed
 311       ENXIO       Invalid IOP number
 312       ETIMEDOUT   Timeout waiting for reply message
 313       ENOMEM      Kernel memory allocation error
 314
 315 X. Validating Configuration
 316
 317    SYNOPSIS
 318
 319    ioctl(fd, I2OVALIDATE, int *iop);
 320         u32 iop;
 321
 322    DESCRIPTION
 323
 324    This function posts an ExecConfigValidate message to the controller
 325    identified by iop. This message indicates that the the current
 326    configuration is accepted. The iop changes the status of suspect drivers
 327    to valid and may delete old drivers from its store.
 328
 329    RETURNS
 330
 331    This function returns 0 if no erro occur.  If an error occurs, -1 is
 332    returned and errno is set appropriatly:
 333
 334       ETIMEDOUT   Timeout waiting for reply message
 335       ENXIO       Invalid IOP number
 336
 337 XI. Configuration Dialog
 338
 339    SYNOPSIS
 340
 341    ioctl(fd, I2OHTML, struct i2o_html *htquery);
 342       struct i2o_html
 343       {
 344          u32   iop;      /* IOP unit number */
 345          u32   tid;      /* Target device ID */
 346          u32   page;     /* HTML page */
 347          void  *resbuf;  /* Buffer for reply HTML page */
 348          u32   *reslen;  /* Length in bytes of reply buffer */
 349          void  *qbuf;    /* Pointer to HTTP query string */
 350          u32   qlen;     /* Length in bytes of query string buffer */
 351       };
 352
 353    DESCRIPTION
 354
 355    This function posts an UtilConfigDialog message to the device identified
 356    by htquery->iop and htquery->tid.  The requested HTML page number is
 357    provided by the htquery->page field, and the resultant data is stored
 358    in the buffer pointed to by htquery->resbuf.  If there is an HTTP query
 359    string that is to be sent to the device, it should be sent in the buffer
 360    pointed to by htquery->qbuf.  If there is no query string, this field
 361    should be set to NULL. The actual size of the reply received is written
 362    into *(htquery->reslen).
 363
 364    RETURNS
 365
 366    This function returns 0 if no error occur. If an error occurs, -1
 367    is returned and errno is set appropriatly:
 368
 369       EFAULT      Invalid user space pointer was passed
 370       ENXIO       Invalid IOP number
 371       ENOBUFS     Buffer not large enough.  If this occurs, the required
 372                   buffer length is written into *(ops->reslen)
 373       ETIMEDOUT   Timeout waiting for reply message
 374       ENOMEM      Kernel memory allocation error
 375
 376 XII. Events
 377
 378     In the process of determining this.  Current idea is to have use
 379     the select() interface to allow user apps to periodically poll
 380     the /dev/i2octl device for events.  When select() notifies the user
 381     that an event is available, the user would call read() to retrieve
 382     a list of all the events that are pending for the specific device.
 383
 384 =============================================================================
 385 Revision History
 386 =============================================================================
 387
 388 Rev 0.1 - 04/01/99
 389 - Initial revision
 390
 391 Rev 0.2 - 04/06/99
 392 - Changed return values to match UNIX ioctl() standard.  Only return values
 393   are 0 and -1.  All errors are reported through errno.
 394 - Added summary of proposed possible event interfaces
 395
 396 Rev 0.3 - 04/20/99
 397 - Changed all ioctls() to use pointers to user data instead of actual data
 398 - Updated error values to match the code