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. 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 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 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 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 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 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 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 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 appropriatly: 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 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 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