home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / CDRom / di_cdt.lha / cdtools / docs / libscsi.info next >
Encoding:
GNU Info File  |  1996-09-20  |  8.5 KB  |  267 lines
  1. This is Info file libscsi.info, produced by Makeinfo-1.55 from the
  2. input file libscsi.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * libscsi: (libscsi).             A library for direct scsi device access.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file documents libscsi 0.2
  9.  
  10.    Copyright 1996 Dieter Baron and Armin Obersteiner
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that the
  18. entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Free Software Foundation.
  25.  
  26. 
  27. File: libscsi.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  28.  
  29. libscsi
  30. *******
  31.  
  32.    This file documents libscsi, a library for direct SCSI device access.
  33. This edition documents version 0.2.
  34.  
  35.    It is an early draft version; large parts are still missing - we
  36. didn't want to delay the release, however.
  37.  
  38. * Menu:
  39.  
  40. * Introduction::    Design Philosophy of libscsi
  41. * Low Level::           Low Level Functions
  42. * Extending::           Extending libscsi
  43. * Porting::             Porting libscsi to other platforms
  44. * Interfaces::          Notes on the Interfaces
  45.  
  46. * Index::
  47. * Index of Functions::
  48. * Index of Variables and Types::
  49.  
  50. 
  51. File: libscsi.info,  Node: Introduction,  Next: Low Level,  Prev: Top,  Up: Top
  52.  
  53. Introduction
  54. ************
  55.  
  56.    Some applications (such as cd players and cd writers) need direct
  57. access to SCSI devices.  Although most operating system provide such
  58. services, each does so in a different way; writing portable software is
  59. painfull.
  60.  
  61.    One goal of libscsi is to encapsulate these system dependencies and
  62. to provide a uniform interface to the application.  *Note Low Level
  63. Functions: Low Level.
  64.  
  65.    The other is to provide convenience functions for SCSI commands, to
  66. avoid programming errors and to render programs more readable.  These
  67. are grouped according to the sections of X3.131 (the ANSI standard for
  68. SCSI II) or devices for vendor specific commands.
  69.  
  70. 
  71. File: libscsi.info,  Node: Low Level,  Next: Extending,  Prev: Introduction,  Up: Top
  72.  
  73. Low Level Functions
  74. *******************
  75.  
  76.  - Function: SCSI * sc_open (char *DEVICE)
  77.  
  78.  - Function: int sc_close (SCSI *SDEV)
  79.      `sc_close' closes device SDEV, deallocating all resources
  80.      associated with it.  SDEV must not be passed to any libscsi
  81.      function afterwards.
  82.  
  83.  - Function: int sc_send (SCSI *SDEV, int DIRECTION, int CMDLEN, char
  84.           *CMD, int DATALEN, char *DATA)
  85.      The `sc_send' function sends a command to device SDEV.
  86.  
  87.      CMD is the command descriptor block (CDB) of the command, CMDLEN
  88.      its length (in bytes).
  89.  
  90.      Set DIRECTION to `SC_READ' if data will be transferred from the
  91.      device to the host in the data in phase; to `SC_WRITE' if data
  92.      will be transferred to the device during data out phase; or to 0
  93.      if no data (besides the CDB) will be transferred.
  94.  
  95.      If this is a write command (`SC_WRITE'), DATA points to DATALEN
  96.      bytes to be transferred.  If it is a read command (`SC_READ'), up
  97.      to DATALEN bytes will be placed in DATA.
  98.  
  99.      On success, `sc_send' return 0 for write and transferless commands
  100.      and the number of bytes read on read commands.  On error, -1 is
  101.      returend and the error indicator and sense data in SDEV are set.
  102.  
  103.  - Function: int sc_set_timeout (SCSI *SDEV, u_long TIMEOUT)
  104.      On systems that timeout commands, `sc_set_timeout' is used to
  105.      specify a timeout of TIMEOUT milliseconds for command completion
  106.      on device SDEV.
  107.  
  108.      If the timeout cannot be set as specified, -1 is returned.
  109.      However, if the system does not timeout commands, this function is
  110.      a noop, and 0 is returned.
  111.  
  112.      If the underlying system supports only one global timeout value
  113.      for all devices, it is expected of the interface functions to set
  114.      it appropriatly for each device before sending a command.
  115.  
  116. 
  117. File: libscsi.info,  Node: Extending,  Next: Porting,  Prev: Low Level,  Up: Top
  118.  
  119. Extending libscsi
  120. *****************
  121.  
  122.      You have to create the files 'lib/xx_????.c' and 'scsi/xx.h' (or just
  123.      add prototypes to it).
  124.      
  125.        xx   - command type OR device type OR product
  126.        ???? - command name
  127.      
  128.      If you've included more commands or support for other devices please
  129.      contact us for inclusion in our distribution.
  130.  
  131. 
  132. File: libscsi.info,  Node: Porting,  Next: Interfaces,  Prev: Extending,  Up: Top
  133.  
  134. Porting libscsi to other platforms
  135. **********************************
  136.  
  137.    To port libscsi to a new platform, you have to provide definitions
  138. for the `SCSI' structure and the low level functions `sc_open',
  139. `sc_close', `sc_send', and `sc_set_timeout'.  They should behave as
  140. documented in *Note Low Level Functions: Low Level.  Look at the
  141. provided interfaces (`scsi/os_{netbsd,amiga}.h' and
  142. `lib/os_{netbsd,amiga}.c') for examples.
  143.  
  144.    Remove the symbolic links `scsi/os.h' and `lib/os.c', and place your
  145. header and soruce files there.
  146.  
  147.    If you want to make your interface part of the distribution, pick a
  148. name and place it in the files `scsi/os_NAME.h' and `lib/os_NAME.c'.
  149. Also, edit `configure.in' to recognize systems supporting your
  150. interface.
  151.  
  152.    Also, send us your new interface, so we can include it in future
  153. releases.
  154.  
  155. 
  156. File: libscsi.info,  Node: Interfaces,  Next: Index,  Prev: Porting,  Up: Top
  157.  
  158. Notes on the Interfaces
  159. ***********************
  160.  
  161.    This section contains interface specific notes, such as the syntax
  162. and semantics of device names or constraints.
  163.  
  164. * Menu:
  165.  
  166. * AmigaDOS::
  167. * NetBSD::
  168.  
  169. 
  170. File: libscsi.info,  Node: AmigaDOS,  Next: NetBSD,  Up: Interfaces
  171.  
  172. AmigaDOS
  173. ========
  174.  
  175.    - compiling and developing
  176.      You simply need the `gcc' or ADE environment installed.
  177.  
  178.    - device names
  179.      SCSI devices are used in following notation
  180.           DEVICE:UNIT
  181.      For example, `gvpscsi.device:2', or simplified, `gvpscsi:2'.
  182.      Also, `gvpscsi' is equivalent to `gvpscsi.device:0' and
  183.      `gvpscsi:0'.
  184.  
  185.    - platform information
  186.      Any Amiga with Kickstart 2.04+ and SCSI controller will do.  (With
  187.      a few changes Kickstart 1.3 would work too.)
  188.  
  189.      Developed and tested with: A2000 (total 7MB), A2630 (2MB), GVP
  190.      Series II, some SCSI devices: hd, cd, zip.
  191.  
  192. 
  193. File: libscsi.info,  Node: NetBSD,  Prev: AmigaDOS,  Up: Interfaces
  194.  
  195. NetBSD
  196. ======
  197.  
  198.    - operating system release
  199.      The ioctl `SCIOCCOMMAND' is unimplemented in versions 1.0 and
  200.      earlier, and will always fail.  Thus, libscsi only works with newer
  201.      version, starting with 1.0A.
  202.  
  203.    - device names
  204.      Under NetBSD, SCSI device names are file names for character
  205.      special devices, usually partition `d'.  (So, for `sd0', the
  206.      zeroth SCSI hard disk, the name would be `/dev/rsd0d'.)  As a
  207.      shorthand, one can specify the device (e.g. `sd0'), rather than the
  208.      file name.
  209.  
  210.    - opening a device
  211.      Since a character special device file is opened (from which reads
  212.      are possible), NetBSD ensures that a medium is present and the
  213.      device is ready.  For a direct SCSI interface, however, this may
  214.      prove disadvantageous.
  215.  
  216. 
  217. File: libscsi.info,  Node: Index,  Next: Index of Functions,  Prev: Interfaces,  Up: Top
  218.  
  219. Index
  220. *****
  221.  
  222. * Menu:
  223.  
  224. * AmigaDOS:                             AmigaDOS.
  225. * extending:                            Extending.
  226. * interfaces:                           Interfaces.
  227. * introduction:                         Introduction.
  228. * NetBSD:                               NetBSD.
  229. * porting:                              Porting.
  230.  
  231. 
  232. File: libscsi.info,  Node: Index of Functions,  Next: Index of Variables and Types,  Prev: Index,  Up: Top
  233.  
  234. Index of Functions
  235. ******************
  236.  
  237. * Menu:
  238.  
  239. * sc_close:                             Low Level.
  240. * sc_open:                              Low Level.
  241. * sc_send:                              Low Level.
  242. * sc_set_timeout:                       Low Level.
  243.  
  244. 
  245. File: libscsi.info,  Node: Index of Variables and Types,  Prev: Index of Functions,  Up: Top
  246.  
  247. Index of Variables and Types
  248. ****************************
  249.  
  250. * Menu:
  251.  
  252. 
  253. Tag Table:
  254. Node: Top973
  255. Node: Introduction1609
  256. Node: Low Level2365
  257. Node: Extending4259
  258. Node: Porting4701
  259. Node: Interfaces5616
  260. Node: AmigaDOS5897
  261. Node: NetBSD6580
  262. Node: Index7438
  263. Node: Index of Functions7857
  264. Node: Index of Variables and Types8220
  265. 
  266. End Tag Table
  267.