ioctl 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394
  1. Linux I2O User Space Interface
  2. rev 0.3 - 04/20/99
  3. =============================================================================
  4. Originally written by Deepak Saxena(deepak@plexity.net)
  5. Currently maintained by Deepak Saxena(deepak@plexity.net)
  6. =============================================================================
  7. I. Introduction
  8. The Linux I2O subsystem provides a set of ioctl() commands that can be
  9. utilized by user space applications to communicate with IOPs and devices
  10. on individual IOPs. This document defines the specific ioctl() commands
  11. that are available to the user and provides examples of their uses.
  12. This document assumes the reader is familiar with or has access to the
  13. I2O specification as no I2O message parameters are outlined. For information
  14. on the specification, see http://www.i2osig.org
  15. This document and the I2O user space interface are currently maintained
  16. by Deepak Saxena. Please send all comments, errata, and bug fixes to
  17. deepak@csociety.purdue.edu
  18. II. IOP Access
  19. Access to the I2O subsystem is provided through the device file named
  20. /dev/i2o/ctl. This file is a character file with major number 10 and minor
  21. number 166. It can be created through the following command:
  22. mknod /dev/i2o/ctl c 10 166
  23. III. Determining the IOP Count
  24. SYNOPSIS
  25. ioctl(fd, I2OGETIOPS, int *count);
  26. u8 count[MAX_I2O_CONTROLLERS];
  27. DESCRIPTION
  28. This function returns the system's active IOP table. count should
  29. point to a buffer containing MAX_I2O_CONTROLLERS entries. Upon
  30. returning, each entry will contain a non-zero value if the given
  31. IOP unit is active, and NULL if it is inactive or non-existent.
  32. RETURN VALUE.
  33. Returns 0 if no errors occur, and -1 otherwise. If an error occurs,
  34. errno is set appropriately:
  35. EFAULT Invalid user space pointer was passed
  36. IV. Getting Hardware Resource Table
  37. SYNOPSIS
  38. ioctl(fd, I2OHRTGET, struct i2o_cmd_hrt *hrt);
  39. struct i2o_cmd_hrtlct
  40. {
  41. u32 iop; /* IOP unit number */
  42. void *resbuf; /* Buffer for result */
  43. u32 *reslen; /* Buffer length in bytes */
  44. };
  45. DESCRIPTION
  46. This function returns the Hardware Resource Table of the IOP specified
  47. by hrt->iop in the buffer pointed to by hrt->resbuf. The actual size of
  48. the data is written into *(hrt->reslen).
  49. RETURNS
  50. This function returns 0 if no errors occur. If an error occurs, -1
  51. is returned and errno is set appropriately:
  52. EFAULT Invalid user space pointer was passed
  53. ENXIO Invalid IOP number
  54. ENOBUFS Buffer not large enough. If this occurs, the required
  55. buffer length is written into *(hrt->reslen)
  56. V. Getting Logical Configuration Table
  57. SYNOPSIS
  58. ioctl(fd, I2OLCTGET, struct i2o_cmd_lct *lct);
  59. struct i2o_cmd_hrtlct
  60. {
  61. u32 iop; /* IOP unit number */
  62. void *resbuf; /* Buffer for result */
  63. u32 *reslen; /* Buffer length in bytes */
  64. };
  65. DESCRIPTION
  66. This function returns the Logical Configuration Table of the IOP specified
  67. by lct->iop in the buffer pointed to by lct->resbuf. The actual size of
  68. the data is written into *(lct->reslen).
  69. RETURNS
  70. This function returns 0 if no errors occur. If an error occurs, -1
  71. is returned and errno is set appropriately:
  72. EFAULT Invalid user space pointer was passed
  73. ENXIO Invalid IOP number
  74. ENOBUFS Buffer not large enough. If this occurs, the required
  75. buffer length is written into *(lct->reslen)
  76. VI. Settting Parameters
  77. SYNOPSIS
  78. ioctl(fd, I2OPARMSET, struct i2o_parm_setget *ops);
  79. struct i2o_cmd_psetget
  80. {
  81. u32 iop; /* IOP unit number */
  82. u32 tid; /* Target device TID */
  83. void *opbuf; /* Operation List buffer */
  84. u32 oplen; /* Operation List buffer length in bytes */
  85. void *resbuf; /* Result List buffer */
  86. u32 *reslen; /* Result List buffer length in bytes */
  87. };
  88. DESCRIPTION
  89. This function posts a UtilParamsSet message to the device identified
  90. by ops->iop and ops->tid. The operation list for the message is
  91. sent through the ops->opbuf buffer, and the result list is written
  92. into the buffer pointed to by ops->resbuf. The number of bytes
  93. written is placed into *(ops->reslen).
  94. RETURNS
  95. The return value is the size in bytes of the data written into
  96. ops->resbuf if no errors occur. If an error occurs, -1 is returned
  97. and errno is set appropriatly:
  98. EFAULT Invalid user space pointer was passed
  99. ENXIO Invalid IOP number
  100. ENOBUFS Buffer not large enough. If this occurs, the required
  101. buffer length is written into *(ops->reslen)
  102. ETIMEDOUT Timeout waiting for reply message
  103. ENOMEM Kernel memory allocation error
  104. A return value of 0 does not mean that the value was actually
  105. changed properly on the IOP. The user should check the result
  106. list to determine the specific status of the transaction.
  107. VII. Getting Parameters
  108. SYNOPSIS
  109. ioctl(fd, I2OPARMGET, struct i2o_parm_setget *ops);
  110. struct i2o_parm_setget
  111. {
  112. u32 iop; /* IOP unit number */
  113. u32 tid; /* Target device TID */
  114. void *opbuf; /* Operation List buffer */
  115. u32 oplen; /* Operation List buffer length in bytes */
  116. void *resbuf; /* Result List buffer */
  117. u32 *reslen; /* Result List buffer length in bytes */
  118. };
  119. DESCRIPTION
  120. This function posts a UtilParamsGet message to the device identified
  121. by ops->iop and ops->tid. The operation list for the message is
  122. sent through the ops->opbuf buffer, and the result list is written
  123. into the buffer pointed to by ops->resbuf. The actual size of data
  124. written is placed into *(ops->reslen).
  125. RETURNS
  126. EFAULT Invalid user space pointer was passed
  127. ENXIO Invalid IOP number
  128. ENOBUFS Buffer not large enough. If this occurs, the required
  129. buffer length is written into *(ops->reslen)
  130. ETIMEDOUT Timeout waiting for reply message
  131. ENOMEM Kernel memory allocation error
  132. A return value of 0 does not mean that the value was actually
  133. properly retrieved. The user should check the result list
  134. to determine the specific status of the transaction.
  135. VIII. Downloading Software
  136. SYNOPSIS
  137. ioctl(fd, I2OSWDL, struct i2o_sw_xfer *sw);
  138. struct i2o_sw_xfer
  139. {
  140. u32 iop; /* IOP unit number */
  141. u8 flags; /* DownloadFlags field */
  142. u8 sw_type; /* Software type */
  143. u32 sw_id; /* Software ID */
  144. void *buf; /* Pointer to software buffer */
  145. u32 *swlen; /* Length of software buffer */
  146. u32 *maxfrag; /* Number of fragments */
  147. u32 *curfrag; /* Current fragment number */
  148. };
  149. DESCRIPTION
  150. This function downloads a software fragment pointed by sw->buf
  151. to the iop identified by sw->iop. The DownloadFlags, SwID, SwType
  152. and SwSize fields of the ExecSwDownload message are filled in with
  153. the values of sw->flags, sw->sw_id, sw->sw_type and *(sw->swlen).
  154. The fragments _must_ be sent in order and be 8K in size. The last
  155. fragment _may_ be shorter, however. The kernel will compute its
  156. size based on information in the sw->swlen field.
  157. Please note that SW transfers can take a long time.
  158. RETURNS
  159. This function returns 0 no errors occur. If an error occurs, -1
  160. is returned and errno is set appropriatly:
  161. EFAULT Invalid user space pointer was passed
  162. ENXIO Invalid IOP number
  163. ETIMEDOUT Timeout waiting for reply message
  164. ENOMEM Kernel memory allocation error
  165. IX. Uploading Software
  166. SYNOPSIS
  167. ioctl(fd, I2OSWUL, struct i2o_sw_xfer *sw);
  168. struct i2o_sw_xfer
  169. {
  170. u32 iop; /* IOP unit number */
  171. u8 flags; /* UploadFlags */
  172. u8 sw_type; /* Software type */
  173. u32 sw_id; /* Software ID */
  174. void *buf; /* Pointer to software buffer */
  175. u32 *swlen; /* Length of software buffer */
  176. u32 *maxfrag; /* Number of fragments */
  177. u32 *curfrag; /* Current fragment number */
  178. };
  179. DESCRIPTION
  180. This function uploads a software fragment from the IOP identified
  181. by sw->iop, sw->sw_type, sw->sw_id and optionally sw->swlen fields.
  182. The UploadFlags, SwID, SwType and SwSize fields of the ExecSwUpload
  183. message are filled in with the values of sw->flags, sw->sw_id,
  184. sw->sw_type and *(sw->swlen).
  185. The fragments _must_ be requested in order and be 8K in size. The
  186. user is responsible for allocating memory pointed by sw->buf. The
  187. last fragment _may_ be shorter.
  188. Please note that SW transfers can take a long time.
  189. RETURNS
  190. This function returns 0 if no errors occur. If an error occurs, -1
  191. is returned and errno is set appropriatly:
  192. EFAULT Invalid user space pointer was passed
  193. ENXIO Invalid IOP number
  194. ETIMEDOUT Timeout waiting for reply message
  195. ENOMEM Kernel memory allocation error
  196. X. Removing Software
  197. SYNOPSIS
  198. ioctl(fd, I2OSWDEL, struct i2o_sw_xfer *sw);
  199. struct i2o_sw_xfer
  200. {
  201. u32 iop; /* IOP unit number */
  202. u8 flags; /* RemoveFlags */
  203. u8 sw_type; /* Software type */
  204. u32 sw_id; /* Software ID */
  205. void *buf; /* Unused */
  206. u32 *swlen; /* Length of the software data */
  207. u32 *maxfrag; /* Unused */
  208. u32 *curfrag; /* Unused */
  209. };
  210. DESCRIPTION
  211. This function removes software from the IOP identified by sw->iop.
  212. The RemoveFlags, SwID, SwType and SwSize fields of the ExecSwRemove message
  213. are filled in with the values of sw->flags, sw->sw_id, sw->sw_type and
  214. *(sw->swlen). Give zero in *(sw->len) if the value is unknown. IOP uses
  215. *(sw->swlen) value to verify correct identication of the module to remove.
  216. The actual size of the module is written into *(sw->swlen).
  217. RETURNS
  218. This function returns 0 if no errors occur. If an error occurs, -1
  219. is returned and errno is set appropriatly:
  220. EFAULT Invalid user space pointer was passed
  221. ENXIO Invalid IOP number
  222. ETIMEDOUT Timeout waiting for reply message
  223. ENOMEM Kernel memory allocation error
  224. X. Validating Configuration
  225. SYNOPSIS
  226. ioctl(fd, I2OVALIDATE, int *iop);
  227. u32 iop;
  228. DESCRIPTION
  229. This function posts an ExecConfigValidate message to the controller
  230. identified by iop. This message indicates that the current
  231. configuration is accepted. The iop changes the status of suspect drivers
  232. to valid and may delete old drivers from its store.
  233. RETURNS
  234. This function returns 0 if no erro occur. If an error occurs, -1 is
  235. returned and errno is set appropriatly:
  236. ETIMEDOUT Timeout waiting for reply message
  237. ENXIO Invalid IOP number
  238. XI. Configuration Dialog
  239. SYNOPSIS
  240. ioctl(fd, I2OHTML, struct i2o_html *htquery);
  241. struct i2o_html
  242. {
  243. u32 iop; /* IOP unit number */
  244. u32 tid; /* Target device ID */
  245. u32 page; /* HTML page */
  246. void *resbuf; /* Buffer for reply HTML page */
  247. u32 *reslen; /* Length in bytes of reply buffer */
  248. void *qbuf; /* Pointer to HTTP query string */
  249. u32 qlen; /* Length in bytes of query string buffer */
  250. };
  251. DESCRIPTION
  252. This function posts an UtilConfigDialog message to the device identified
  253. by htquery->iop and htquery->tid. The requested HTML page number is
  254. provided by the htquery->page field, and the resultant data is stored
  255. in the buffer pointed to by htquery->resbuf. If there is an HTTP query
  256. string that is to be sent to the device, it should be sent in the buffer
  257. pointed to by htquery->qbuf. If there is no query string, this field
  258. should be set to NULL. The actual size of the reply received is written
  259. into *(htquery->reslen).
  260. RETURNS
  261. This function returns 0 if no error occur. If an error occurs, -1
  262. is returned and errno is set appropriatly:
  263. EFAULT Invalid user space pointer was passed
  264. ENXIO Invalid IOP number
  265. ENOBUFS Buffer not large enough. If this occurs, the required
  266. buffer length is written into *(ops->reslen)
  267. ETIMEDOUT Timeout waiting for reply message
  268. ENOMEM Kernel memory allocation error
  269. XII. Events
  270. In the process of determining this. Current idea is to have use
  271. the select() interface to allow user apps to periodically poll
  272. the /dev/i2o/ctl device for events. When select() notifies the user
  273. that an event is available, the user would call read() to retrieve
  274. a list of all the events that are pending for the specific device.
  275. =============================================================================
  276. Revision History
  277. =============================================================================
  278. Rev 0.1 - 04/01/99
  279. - Initial revision
  280. Rev 0.2 - 04/06/99
  281. - Changed return values to match UNIX ioctl() standard. Only return values
  282. are 0 and -1. All errors are reported through errno.
  283. - Added summary of proposed possible event interfaces
  284. Rev 0.3 - 04/20/99
  285. - Changed all ioctls() to use pointers to user data instead of actual data
  286. - Updated error values to match the code