linux/Documentation/i2o/ioctl
<<
>>
Prefs
   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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.