\input texinfo   @c -*-texinfo-*-@c %**start of header@setfilename libscsi.info@settitle libscsi@setchapternewpage off@c %**end of header@c @synindex tp vr@include version.texi@ifinfo@formatSTART-INFO-DIR-ENTRY* libscsi: (libscsi).             A library for direct scsi device access.END-INFO-DIR-ENTRY@end format@end ifinfo@ifinfoThis file documents libscsi @value{VERSION}Copyright 1996 Dieter Baron and Armin ObersteinerPermission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.@ignorePermission is granted to process this file through TeX and print theresults, provided the printed document carries copying permissionnotice identical to this one except for the removal of this paragraph@end ignorePermission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that theentire resulting derived work is distributed under the terms of apermission notice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translationapproved by the Free Software Foundation.@end ifinfo@titlepage@title libscsi@subtitle A Library for Direct @sc{scsi} Device Access@subtitle For version @value{VERSION}, @value{UPDATED}@author Dieter Baron@author Armin Obersteiner@c copyright page@page@vskip 0pt plus 1filllCopyright @copyright{} 1996 Dieter Baron and Armin Obersteiner@sp 2This is a draft edition of the libscsi documentation,@*and is consistent with libscsi @value{VERSION}.@*@sp 2@ignorePublished by the Free Software Foundation @*59 Template Place - Suite 330, @*Boston, MA 02111-1307 USA @*@end ignorePermission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.Permission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entireresulting derived work is distributed under the terms of a permissionnotice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translationapproved by the Free Software Foundation.@end titlepage@ifinfo@c ================================================================@node Top, Introduction, (dir), (dir)@comment  node-name,  next,  previous,  up@top libscsiThis file documents libscsi, a library for direct SCSI device access.This edition documents version @value{VERSION}.It is an early draft version; large parts are still missing -- we didn'twant to delay the release, however.@menu* Introduction::	Design Philosophy of libscsi* Low Level::           Low Level Functions* Extending::           Extending libscsi* Porting::             Porting libscsi to other platforms* Interfaces::          Notes on the Interfaces* Index::* Index of Functions::* Index of Variables and Types::@end menu@end ifinfo@c ================================================================@node Introduction@chapter Introduction@cindex introductionSome applications (such as cd players and cd writers) need direct accessto @sc{scsi} devices.  Although most operating system provide suchservices, each does so in a different way; writing portable software ispainfull.One goal of libscsi is to encapsulate these system dependencies and toprovide a uniform interface to the application.  @xref{Low Level, LowLevel Functions}.The other is to provide convenience functions for @sc{scsi} commands, toavoid programming errors and to render programs more readable.  Theseare grouped according to the sections of X3.131 (the @sc{ansi} standardfor @sc{scsi ii}) or devices for vendor specific commands.@c ================================================================@node Low Level@chapter Low Level Functions@deftypefun {SCSI *} sc_open (char *@var{device})@end deftypefun@deftypefun int sc_close (SCSI *@var{sdev})@code{sc_close} closes device @var{sdev}, deallocating all resourcesassociated with it.  @var{sdev} must not be passed to any libscsifunction afterwards.@end deftypefun@deftypefun int sc_send (SCSI *@var{sdev}, int @var{direction}, int @var{cmdlen}, char *@var{cmd}, int @var{datalen}, char *@var{data})The @code{sc_send} function sends a command to device @var{sdev}.@var{cmd} is the command descriptor block (CDB) of the command,@var{cmdlen} its length (in bytes).Set @var{direction} to @code{SC_READ} if data will be transferred fromthe device to the host in the data in phase; to @code{SC_WRITE} if datawill be transferred to the device during data out phase; or to 0 if nodata (besides the CDB) will be transferred.If this is a write command (@code{SC_WRITE}), @var{data} points to@var{datalen} bytes to be transferred.  If it is a read command(@code{SC_READ}), up to @var{datalen} bytes will be placed in@var{data}.On success, @code{sc_send} return 0 for write and transferless commandsand the number of bytes read on read commands.  On error, -1 is returendand the error indicator and sense data in @var{sdev} are set.@end deftypefun@deftypefun int sc_set_timeout (SCSI *@var{sdev}, u_long @var{timeout})On systems that timeout commands, @code{sc_set_timeout} is used tospecify a timeout of @var{timeout} milliseconds for command completionon device @var{sdev}.If the timeout cannot be set as specified, -1 is returned.  However, ifthe system does not timeout commands, this function is a noop, and 0 isreturned.If the underlying system supports only one global timeout value for alldevices, it is expected of the interface functions to set itappropriatly for each device before sending a command.@end deftypefun@c ================================================================@node Extending@chapter Extending libscsi@cindex extending@exampleYou have to create the files 'lib/xx_????.c' and 'scsi/xx.h' (or justadd prototypes to it).  xx   - command type OR device type OR product  ???? - command nameIf you've included more commands or support for other devices pleasecontact us for inclusion in our distribution.@end example@c ================================================================@node Porting@chapter Porting libscsi to other platforms@cindex portingTo port libscsi to a new platform, you have to provide definitions forthe @code{SCSI} structure and the low level functions @code{sc_open},@code{sc_close}, @code{sc_send}, and @code{sc_set_timeout}.  They shouldbehave as documented in @xref{Low Level, Low Level Functions}.  Look atthe provided interfaces (@code{scsi/os_@{netbsd,amiga@}.h} and@code{lib/os_@{netbsd,amiga@}.c}) for examples.Remove the symbolic links @code{scsi/os.h} and @code{lib/os.c}, andplace your header and soruce files there.If you want to make your interface part of the distribution, pick a nameand place it in the files @code{scsi/os_@var{name}.h} and@code{lib/os_@var{name}.c}.  Also, edit @code{configure.in} to recognizesystems supporting your interface.Also, send us your new interface, so we can include it in futurereleases.@c ================================================================@node Interfaces@chapter Notes on the Interfaces@cindex interfacesThis section contains interface specific notes, such as the syntax andsemantics of device names or constraints.@menu* AmigaDOS::* NetBSD::@end menu@c ================================================================@node AmigaDOS@section AmigaDOS@cindex AmigaDOS@itemize -@item compiling and developing@*You simply need the @code{gcc} or @sc{ADE} environment installed.@item device names@*@sc{scsi} devices are used in following notation@example@var{device}:@var{unit}@end exampleFor example, @code{gvpscsi.device:2}, or simplified, @code{gvpscsi:2}.Also, @code{gvpscsi} is equivalent to @code{gvpscsi.device:0} and @code{gvpscsi:0}.@item platform information@*Any Amiga with Kickstart 2.04+ and SCSI controller will do.(With a few changes Kickstart 1.3 would work too.)Developed and tested with: A2000 (total 7MB), A2630 (2MB), GVP Series II,some SCSI devices: hd, cd, zip.@end itemize@c ================================================================@node NetBSD@section NetBSD@cindex NetBSD@itemize -@item operating system release@*The ioctl @code{SCIOCCOMMAND} is unimplemented in versions 1.0 andearlier, and will always fail.  Thus, libscsi only works with newerversion, starting with 1.0A.@item device names@*Under NetBSD, @sc{scsi} device names are file names for characterspecial devices, usually partition @codevrzueog.  (So, for @code{sd0}, thezeroth @sc{scsi} hard disk, the name would be @code{/dev/rsd0d}.)  As ashorthand, one can specify the device (e.g. @code{sd0}), rather than thefile name.@item opening a device@*Since a character special device file is opened (from which reads arepossible), NetBSD ensures that a medium is present and the device isready.  For a direct @sc{scsi} interface, however, this may provedisadvantageous.@end itemize@c ================================================================@iftex@page@end iftex@node Index@unnumbered Index@printindex cp@node Index of Functions@unnumbered Index of Functions@printindex fn@node Index of Variables and Types@unnumbered Index of Variables and Types@printindex vr@contents@bye