drivers/message/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@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. 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 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