scsi 3.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186
  1. .TH SCSI 2
  2. .SH NAME
  3. openscsi, closescsi, scsiready, scsi, scsicmd, scsierror \- SCSI device operations
  4. .SH SYNOPSIS
  5. .nf
  6. .ft L
  7. #include <u.h>
  8. #include <libc.h>
  9. #include <disk.h>
  10. .ft
  11. .PP
  12. .ft L
  13. typedef struct Scsi {
  14. char *inquire;
  15. int rawfd;
  16. int nchange;
  17. ulong changetime;
  18. };
  19. .ft
  20. .PP
  21. .B
  22. Scsi* openscsi(char *devdir)
  23. .PP
  24. .B
  25. void closescsi(Scsi *s)
  26. .PP
  27. .B
  28. int scsiready(Scsi *s)
  29. .PP
  30. .ft L
  31. int scsi(Scsi *s, uchar *cmd, int ncmd,
  32. .br
  33. void *data, int ndata, int dir)
  34. .PP
  35. .ft L
  36. int scsicmd(Scsi *s, uchar *cmd, int ncmd,
  37. .br
  38. void *data, int ndata, int dir)
  39. .PP
  40. .B
  41. char* scsierror(int asc, int ascq)
  42. .PP
  43. .B
  44. int scsiverbose;
  45. .SH DESCRIPTION
  46. These routines provide an interface
  47. to a SCSI or ATAPI device via
  48. .IR sd (3).
  49. .PP
  50. .I Openscsi
  51. attempts to open the file
  52. .IB devdir /raw
  53. and use it to send raw SCSI commands.
  54. On success, it reads the device's inquiry
  55. string and stores it in
  56. .I inquire
  57. in the returned
  58. .B Scsi
  59. structure.
  60. .I Closescsi
  61. closes the connection and frees the
  62. .B Scsi
  63. structure.
  64. .PP
  65. .I Scsiready
  66. sends the ``unit ready'' command up to three times,
  67. returning zero if the unit responds that it is ready,
  68. or \-1 on error.
  69. .PP
  70. .I Scsierror
  71. returns a textual description of the SCSI status
  72. denoted by the ASC and ASCQ sense codes.
  73. The description is found by consulting
  74. .BR /sys/lib/scsicodes .
  75. The returned string will be overwritten by
  76. the next call to
  77. .IR scsierror .
  78. .PP
  79. .I Scsi
  80. and
  81. .I scsicmd
  82. execute a single SCSI command on the named device.
  83. There should be
  84. .I ncmd
  85. bytes of
  86. command data in
  87. .IR cmd ;
  88. if
  89. .I dir
  90. is
  91. .BR Sread ,
  92. a successful operation
  93. will store up to
  94. .I ndata
  95. bytes into
  96. .IR data ,
  97. returning the number of bytes stored.
  98. If
  99. .I dir
  100. is
  101. .BR Swrite ,
  102. the
  103. .I ndata
  104. bytes beginning at
  105. .I data
  106. are transmitted as the data argument to
  107. the command, and the
  108. number of bytes written is returned.
  109. If
  110. .I dir
  111. is
  112. .BR Snone ,
  113. .I data
  114. and
  115. .I ndata
  116. are ignored.
  117. On error,
  118. .I scsi
  119. and
  120. .I scsicmd
  121. return \-1.
  122. .I Scsicmd
  123. simply issues the command and
  124. returns the result;
  125. .I scsi
  126. works a bit harder and
  127. is the more commonly used routine.
  128. .I Scsi
  129. attempts to send the command;
  130. if it is successful,
  131. .I scsi
  132. returns what
  133. .I scsicmd
  134. returned.
  135. Otherwise,
  136. .I scsi
  137. sends a request sense command to
  138. obtain the reason for the failure,
  139. sends a unit ready command in
  140. an attempt to bring the unit out of any
  141. inconsistent states, and tries again.
  142. If the second try fails,
  143. .I scsi
  144. sends the request
  145. sense and unit ready commands
  146. again
  147. and then uses
  148. .I scsierror
  149. to set
  150. .I errstr
  151. with a reason for failure.
  152. .PP
  153. The
  154. .B nchange
  155. and
  156. .B changetime
  157. fields
  158. in the
  159. .B Scsi
  160. structure
  161. record the number of times a media
  162. change has been detected, and the
  163. time when the current media was
  164. inserted into the drive (really the
  165. first time a SCSI command was issued
  166. after it was inserted).
  167. They are maintained by
  168. .IR scsi .
  169. .PP
  170. If
  171. .I scsiverbose
  172. is set,
  173. these commands will produce a fair
  174. amount of debugging output on file descriptor 2
  175. when SCSI commands fail.
  176. .SH FILES
  177. .TP
  178. .B /sys/lib/scsicodes
  179. List of textual messages corresponding to SCSI error codes;
  180. consulted by
  181. .BR scsierror .
  182. .SH SOURCE
  183. .B /sys/src/libdisk/scsi.c
  184. .SH SEE ALSO
  185. .IR sd (3),
  186. .IR scuzz (8)