libscsi.texi

对SCSI设备 直接存取的通用库

\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
@format
START-INFO-DIR-ENTRY
* libscsi: (libscsi).             A library for direct scsi device access.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file documents libscsi @value{VERSION}

Copyright 1996 Dieter Baron and Armin Obersteiner

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph


@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved 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 1filll
Copyright @copyright{} 1996 Dieter Baron and Armin Obersteiner
@sp 2
This is a draft edition of the libscsi documentation,@*
and is consistent with libscsi @value{VERSION}.@*
@sp 2
@ignore
Published by the Free Software Foundation @*
59 Template Place - Suite 330, @*
Boston, MA 02111-1307 USA @*

@end ignore
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end titlepage

@ifinfo
@c ================================================================
@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top libscsi

This 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't
want 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 introduction

Some applications (such as cd players and cd writers) need direct access
to @sc{scsi} devices.  Although most operating system provide such
services, each does so in a different way; writing portable software is
painfull.

One goal of libscsi is to encapsulate these system dependencies and to
provide a uniform interface to the application.  @xref{Low Level, Low
Level Functions}.

The other is to provide convenience functions for @sc{scsi} commands, to
avoid programming errors and to render programs more readable.  These
are grouped according to the sections of X3.131 (the @sc{ansi} standard
for @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 resources
associated with it.  @var{sdev} must not be passed to any libscsi
function 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 from
the device to the host in the data in phase; to @code{SC_WRITE} if data
will be transferred to the device during data out phase; or to 0 if no
data (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 commands
and the number of bytes read on read commands.  On error, -1 is returend
and 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 to
specify a timeout of @var{timeout} milliseconds for command completion
on device @var{sdev}.

If the timeout cannot be set as specified, -1 is returned.  However, if
the system does not timeout commands, this function is a noop, and 0 is
returned.

If the underlying system supports only one global timeout value for all
devices, it is expected of the interface functions to set it
appropriatly for each device before sending a command.
@end deftypefun


@c ================================================================
@node Extending
@chapter Extending libscsi
@cindex extending

@example
You have to create the files 'lib/xx_????.c' and 'scsi/xx.h' (or just
add prototypes to it).

  xx   - command type OR device type OR product
  ???? - command name

If you've included more commands or support for other devices please
contact us for inclusion in our distribution.
@end example


@c ================================================================
@node Porting
@chapter Porting libscsi to other platforms
@cindex porting

To port libscsi to a new platform, you have to provide definitions for
the @code{SCSI} structure and the low level functions @code{sc_open},
@code{sc_close}, @code{sc_send}, and @code{sc_set_timeout}.  They should
behave as documented in @xref{Low Level, Low Level Functions}.  Look at
the 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}, and
place your header and soruce files there.

If you want to make your interface part of the distribution, pick a name
and place it in the files @code{scsi/os_@var{name}.h} and
@code{lib/os_@var{name}.c}.  Also, edit @code{configure.in} to recognize
systems supporting your interface.

Also, send us your new interface, so we can include it in future
releases.


@c ================================================================
@node Interfaces
@chapter Notes on the Interfaces
@cindex interfaces

This section contains interface specific notes, such as the syntax and
semantics 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 example
For 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 and
earlier, and will always fail.  Thus, libscsi only works with newer
version, starting with 1.0A.

@item device names@*
Under NetBSD, @sc{scsi} device names are file names for character
special devices, usually partition @code{d}.  (So, for @code{sd0}, the
zeroth @sc{scsi} hard disk, the name would be @code{/dev/rsd0d}.)  As a
shorthand, one can specify the device (e.g. @code{sd0}), rather than the
file name.

@item opening a device@*
Since a character special device file is opened (from which reads are
possible), NetBSD ensures that a medium is present and the device is
ready.  For a direct @sc{scsi} interface, however, this may prove
disadvantageous.
@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