adapter_driver(3K) DG/UX R4.11MU05 adapter_driver(3K)
NAME
adapterdriver: devxxxadapteropen, devxxxadapterclose,
devxxxregisterrequester, devxxxderegisterrequester,
devxxxsetadapteroptions, devxxxsetunitoptions,
devxxxissuecommand, devxxxissueasynccommand,
devxxxissuecommandphysicalmode, devxxxadapterioctl,
devxxxgetdeviceinfo - implement an adapter driver
SYNOPSIS
#include "/usr/src/uts/aviion/dev/devscsiadapterdef.h"
statustype devxxxadapteropen (
iodevicehandletype adapterhandle, READONLY
iochannelflagstype channelflags READONLY )
statustype devxxxadapterclose (
iodevicehandletype adapterhandle, READWRITE
iochannelflagstype channelflags READWRITE )
statustype devxxxregisterrequester (
devscsiadapterunitregistrationblkptrtype rbptr READWRITE )
void devxxxderegisterrequester (
iodevicehandletype adapterhandle READONLY )
statustype devxxxsetadapteroptions (
iodevicehandletype adapterhandle, READONLY
devscsiadapteroptionsblockptrtype adapoptblkptr READWRITE)
statustype devxxxsetunitoptions (
iodevicehandletype adapterhandle, READONLY
devscsiadapterunitoptionsblockptrtype uoptblkptr READWRITE)
statustype devxxxissuecommand (
devadapterrequestblockptrtype arbptr READWRITE )
statustype devxxxissueasynccommand (
devadapterrequestblockptrtype arbptr READWRITE )
statustype devxxxissuecommandphysicalmode (
devadapterphysicalrequestblkptrtype requestblkptr READWRITE)
statustype devxxxadapterioctl (
iodevicehandletype adapterhandle, READONLY
bit32etype command, READONLY
bit32etype parameter, READWRITE
int32eptrtype returnvalptr WRITEONLY )
statustype devxxxgetdeviceinfo (
iodevicenumbertype adapterdevicenumber, READONLY
devscsiadapterunitspectype unitspec, READONLY
bit8type devicetype, READONLY
bit32eptrtype driverhandleptr WRITEONLY )
where:
adapoptblkptr Pointer to an adapter options block that specifies
the options to be selected for the unit.
adapterdevicenumber
The major and minor device number of the SCSI
adapter used to access the target unit.
adapterhandle The device handle of the physical adapter that is
to be opened, closed, deregistered, or set. This
handle must be the device handle that was returned
by the adapter driver's register-requester routine.
arbptr A pointer to an adapter request block that holds
all information that describes the request.
channelflags The set of channel flags specifying the type of
access requested on the device.
command A command to the device. The interpretation of the
command is specific to the driver.
devicetype Device type of device expected to be registered for
unit number and SCSI ID.
driverhandleptr Pointer to where driver handle is to be returned.
parameter An argument to the command. The interpretation of
the parameter is specific to the driver and the
command. The parameter can be used to transfer
information in either direction between the caller
and the device. For example, it can be a pointer
to a buffer supplied by the caller.
rbptr A pointer to a SCSI adapter registration block.
requestblkptr Pointer to a request block that holds information
specifying a request. This is a special version of
the adapter request block, not the same request
block used during normal system operation.
returnvalueptr A pointer to the value to be returned to the user.
If the command fails, minus one (-1) is returned.
uoptblkptr Pointer to a unit options block that specifies the
options to be selected for the unit.
unitspec The SCSI ID and unit number of the target device.
DESCRIPTION
This man page describes the interfaces for routines you must write to
build a SCSI adapter driver. Those routines are as follows:
devxxxadapteropen Prepare device or adapter driver for I/O
devxxxadapterclose Prepare adapter to be removed from use
devxxxregisterrequester Associate device with a SCSI adapter
devxxxderegisterrequester Terminate the link between the SCSI
adapter manager and a device
devxxxsetadapteroptions Set registered device's adapter options
devxxxsetunitoptions Set unit options of a registered device
devxxxissuecommand Issue a SCSI command synchronously
devxxxissueasynccommand Issue a SCSI command asynchronously
devxxxissuecommandphysicalmode
Issue a physical I/O request to device
devxxxadapterioctl Perform control operation on adapter
devxxxgetdeviceinfo Get driver handle registered with device
The adaptermanager(3K) man page describes the SCSI adapter routines
that come with the DG/UX system. You only need to write adapter
routines if your application requires changes to Data General-
supplied adapter routines or if you are going to add a different type
of adapter board to your system. As with user-supplied device driver
routines, replace xxx with the mnemonic for your SCSI adapter.
Each routine has specific return values (see Return Value below) that
the kernel can process when the routine returns. When no return
value is specified, the routine must not fail (the kernel will not
process any returns or exceptions). If the driver routine
experiences an exception other than those specified under Return
Value, it can proceed in one of the following three ways:
1. It can return an exception by returning a value other than one
of the specified values. The kernel will filter this value back
to the user as a standard errno. You can either define your own
values for this errno or use values already defined by the
system. Check /usr/include/sys/errno.h for a listing of the
existing errnos and their definitions.
2. It can use the error server to log an error.
3. It can halt the system. Some driver routines are not allowed to
halt. We indicate whether or not a routine can halt under
Return Value below.
The servermessages(3K) man page describes how to define an error
status and how to log an error to the error server. The scpanic(3K)
man page describes how to use the routine that halts the system.
Constants and Data Structures
This subsection describes constants and data structures defined in
the include file cited in the SYNOPSIS section and used by SCSI
device and adapter drivers.
Try to avoid dependencies on the specifics of these structures, such
as size or location of fields, because these specifics may change in
later releases of the software. You can verify exact variable
definitions in the appropriate include file. The best way to avoid
such dependencies is to use kernel-supplied routines to manipulate
these structures.
devscsiadapterroutinesvectortype
typedef struct
{
iodriverroutinesvectortype driverroutines;
devscsiinterfaceroutinesvectortype scsiroutines;
} devscsiadapterroutinesvectortype ;
This structure describes the adapter driver routines vector. Note
that it contains both the standard device driver routines vector and
the additional adapter-driver-specific routines vector.
devscsiinterfaceroutinesvectortype
typedef struct
{
uint16type version;
bit16type flags;
statustype (*registerrequester)();
statustype (*setunitoptions)();
void (*deregisterrequester)();
statustype (*issuecommand)();
statustype (*issueasynccommand)();
statustype (*getdeviceinfo)();
statustype (*issuecommandphysicalmode)();
statustype (*setadapteroptions)();
statustype (*adapteropen)();
statustype (*adapterclose)();
statustype (*adapterioctl)();
} devscsiinterfaceroutinesvectortype ;
This type describes the adapter-driver-specific routines vector.
This vector contains a pointer to each adapter driver routine that
the adapter manager can call. The version field is present to allow
changes to this structure while retaining compatibility with older
user-written device drivers. The structure as currently defined is
version DEVSCSIINTERFACEVERSION2. The flags field is currently
unused.
devscsiadapterunitspectype
typedef struct
{
uint8type scsiid;
uint8type unit;
} devscsiadapterunitspectype ;
The SCSI device driver uses this structure to specify a particular
instance of a SCSI device on a SCSI adapter.
The fields in this structure are as follows:
scsiid Pass the target device's SCSI ID on the SCSI bus.
unit Pass the logical unit number of the target device.
devadapterrequestblocktype
typedef struct
{
miscqueuelinkstype links;
uint16type type;
bit16etype requestflags;
uint32type reserved;
iodevicehandletype adapterhandle;
devscsicmdblktype scsicmdblk;
devscsiadapterunitspectype unitspec;
iobuffervectortype buffervector;
devscsirequestsensebuffertype sensebuffer;
booleantype syncio;
iooperationrecordptrtype oprecordptr;
iocompletionroutineptrtype completeioroutine;
miscclockvaluetype requeststarttime;
miscclockvaluetype totalrequestbusytime
statustype asyncstartstatus;
uint32type scsicommandsize;
uint32type scsistatus;
} devadapterrequestblocktype ;
The SCSI device driver uses this structure as a generic parameter
block to specify a request to the supporting adapter driver.
The fields in this structure are as follows:
links The adapter driver maintains this field using queue
manager calls in order to enqueue/dequeue the adapter
request block onto various lists during request
processing.
type Define the type of the adapter request block and hence
provides for multiple adapter request blocks. This
provision has been made to allow for new types of
adapter request blocks that may be needed as new types
of adapters are added. For the current SCSI adapter
definition, this field should be set to
DEV_SCSI_ARB_TYPE_SCSI_I.
requestflags
Pass flags that qualify the request. The values used
in this field are given under Request Flag Literals
below.
reserved
Do nothing. This field is reserved for future use by
Data General. It must always be set to zero.
adapterhandle
Pass the field opaquely. The adapter driver uses this
handle to map each instance of a device to the data
structures used to control it. This handle is used
only by the adapter driver.
scsicmdblk
Pass the command block which specifies the request to
be made to the device. The SCSI command block is not
interpreted by the adapter manager.
unitspec
Pass the target device's SCSI ID and logical unit
number.
buffervector
Pass the buffer vector describing the main memory area
that is to be involved in the I/O operation.
syncio
Indicate whether the request is to be performed
synchronously (the caller pends in the driver for the
I/O operation to complete) or asynchronously. If it is
clear (FALSE), the operation is performed
asynchronously. When set, the operation is performed
synchronously.
oprecordptr
When the operation is to be performed asynchronously,
pass a pointer to the original operation record that
specified the request.
completeioroutine
When operation is to be performed asynchronously, pass
the address of the caller's I/O completion routine.
requeststarttime
Store the starting time of a request for device usage
accounting. Upon request completion, the start time is
subtracted from the current time to get the total time
required to process the request. This field is not
used by the SCSI interface manager; it used is only by
the SCSI device drivers.
totalrequestbusytime
Specify the total amount of time that the target
physical device spent processing the request. Since
the SCSI device drivers have no precise knowledge of
when the target device actually starts or completes a
request, this information must be obtained from the
supporting SCSI interface manager.
asyncstartstatus
Specify a status for asynchronous requests that may be
used within a device or adapter driver. A value other
than OK indicates that the request could not be started
on the device. The field is undefined for synchronous
requests. This field should not be used to communicate
statuses between device and adapter drivers as such
statuses should be returned through the adapter/device
interface.
scsicommandsize
Specify the size of the SCSI command descriptor block.
This field is used determine the size of a vendor
unique SCSI command descriptor block.
scsistatus
Return the status of the SCSI command which was issued
to the device.
Request Flag Literals
#define DEVSCSIREQUESTFLAGSNONE
#define DEVSCSIREQUESTFLAGSKERNELBUFFER
#define DEVSCSIREQUESTFLAGSPHYSICALBUFFER
#define DEVSCSIREQUESTFLAGSSBDONE
#define DEVSCSIREQUESTFLAGSSB
#define DEVSCSIREQUESTFLAGSSBREAD
#define DEVSCSIREQUESTFLAGSDATAXFERIN
The following constants define bit positions of the request flags
used in the requestflags field of devadapterrequestblocktype.
The options are as follows:
DEVSCSIREQUESTFLAGSNONE
SCSI device drivers use this literal to indicate that
no special flags are set.
DEVSCSIREQUESTFLAGSKERNELBUFFER
SCSI device drivers use this literal to indicate that
the data buffer address specified in the request block
is a kernel address. If this flag is not set, a user
buffer is assumed.
DEVSCSIREQUESTFLAGSPHYSICALBUFFER
SCSI device drivers use this literal to indicate that
the data buffer address specified in the request block
is a physical address.
DEVSCSIREQUESTFLAGSSBDONE
This literal is used by the DG/UX sector-buffering
mechanism. When set, it indicates that the current
request is done. Sector buffering is performed by the
DG/UX SCSI disk driver to allow access to a disk that
does not have standard 512-byte sectors.
DEVSCSIREQUESTFLAGSSB
This literal is used by the DG/UX sector-buffering
mechanism. When set, it indicates that sector
buffering is enabled for device access.
DEVSCSIREQUESTFLAGSSBREAD
This literal is used by the DG/UX sector-buffering
mechanism. When set, it indicates that a sector
buffered read is taking place.
DEVSCSIREQUESTFLAGSDATAXFERIN
SCSI device drivers use this literal to indicate data
direction. If set, this literal indicates that the
data transfer direction is from the adapter to the host
(that is, a read). If clear, the data transfer
direction is from the host to the adapter (that is, a
write). This flag is valid only if the number of bytes
being transferred is greater than zero.
devscsiadapterunitregistrationblktype
typedef struct
{
iodevicenumbertype adapterdevicenumber;
devscsiadapterunitspectype unitspec;
iodevicehandletype adapterhandle;
iodevicehandletype driverhandle;
uint16type maxconcurrentrequests;
bit16type interfaceflags;
uint32type maxrequestsize;
bit8type devicetype;
} devscsiadapterunitregistrationblktype ;
The SCSI device driver uses this structure to register a physical
unit with the SCSI adapter manager. Registration establishes a
direct link between the device driver and the adapter manager service
routines. Registering a unit consists of the device driver and the
adapter driver exchanging information. This structure contains
several variables needed for the registration process.
The fields in this structure are as follows:
adapterdevicenumber
SCSI device drivers use this field to pass the major
and minor device numbers of the SCSI adapter with which
the unit is being registered.
unitspec
SCSI device drivers use this field to pass the SCSI ID
and logical unit number of the device being registered.
adapterhandle
SCSI device drivers use this field to pass the handle
that the SCSI adapter manager returns to the device
driver requesting the registration. It is passed as an
argument to the adapter driver routines to identify the
adapter that is the target of a request. The driver
does not interpret this field.
driverhandle
SCSI device drivers use this field to pass a unit
handle that points to a driver-defined block of
information specific to the unit being addressed. The
device driver may pass this handle to the adapter
manager when it registers the unit. The adapter
manager saves this handle and returns it to the driver
when the driver calls the adapter's
devxxxgetdeviceinfo routine. The adapter manager
does not interpret this field.
maxconcurrentrequests
SCSI device drivers use this field to pass the maximum
number of concurrently executing requests on the unit
that the driver will allow.
interfaceflags
SCSI device drivers use this field to indicate which
type of interface this SCSI driver supports. The
values used in this field are given in the Interface
Flags Literals listed below.
maxrequestsize
The adapter driver uses this field to return the
maximum number of bytes transferable between the host
and device in a single operation.
devicetype
If a device is already registered with the specified
SCSI ID and unit number, the device type of the
registered device is returned in this field.
Otherwise, the device type specified by devicetype is
recorded for the device. The values used in this field
are given under Device Type Literals below.
Interface Flag Literals
#define DEVSCSIREGISTRATIONBLKFLAGSNONE
#define DEVSCSIREGISTRATIONBLKFLAGSSCSI2SUPPORTED
#define DEVSCSIREGISTRATIONBLKFLAGS32LUNSUPPORTED
The following constants define values of the flags used in the
interfaceflags field of an adapter request block described by
devscsiadapterunitregistrationblktype. The options are as
follows:
DEVSCSIREGISTRATIONBLKFLAGSNONE
SCSI device drivers use this literal if no options
other than the defaults are supported.
DEVSCSIREGISTRATIONBLKFLAGSSCSI2SUPPORTED
SCSI device drivers use this literal to indicate
interface type. If set, this flag indicates that the
SCSI interface supports SCSI-2 features (command
tagging).
DEVSCSIREGISTRATIONBLKFLAGS32LUNSUPPORTED
SCSI device drivers use this literal to indicate they
support 32 Logical Unit Numbers, as specified in the
SCSI-3 draft. If set, this flag indicates that the
SCSI interface supports this feature.
Device Type Literals
#define DEVSCSIENCODEDDEVICEDIRECTACCESS
#define DEVSCSIENCODEDDEVICESEQUENTIALACCESS
#define DEVSCSIENCODEDDEVICEPRINTER
#define DEVSCSIENCODEDDEVICEPROCESSOR
#define DEVSCSIENCODEDDEVICEWRITEONCEREADMULTIPLE
#define DEVSCSIENCODEDDEVICEDIRECTACCESSREADONLY
#define DEVSCSIENCODEDDEVICEGENERALDIRECTACCESS
The following constants define values of the types used in the
devicetype field of an adapter request block described by
devscsiadapterunitregistrationblktype. The options are as
follows:
DEVSCSIENCODEDDEVICEDIRECTACCESS
Indicate that the device is a direct access device, for
example, disk.
DEVSCSIENCODEDDEVICESEQUENTIALACCESS
Indicate that the device is a sequential access device,
for example, tape.
DEVSCSIENCODEDDEVICEPRINTER
Indicate that the device is a printer.
DEVSCSIENCODEDDEVICEPROCESSOR
Indicate that the device is a processor, for example, a
CPU.
DEVSCSIENCODEDDEVICEWRITEONCEREADMULTIPLE
Indicate that the device is a WORM access device.
DEVSCSIENCODEDDEVICEDIRECTACCESSREADONLY
Indicate that the device is a read-only device, for
example, a CDROM.
DEVSCSIENCODEDDEVICEGENERALDIRECTACCESS
Indicate that the device is any direct access device.
This define may be used for disks, WORM devices, or
CDROM devices.
devadapterphysicalrequestblktype
typedef struct
{
uint16type type;
uint16type requestflags;
uint32type reserved;
devscsicmdblktype scsicmdblk;
iobuffervectortype buffervector;
devscsirequestsensebuffertype sensebuffer;
devscsimodebuffertype modeselectbuffer;
uint16type volume;
devscsiadapterunitspectype unitspec;
iodevicenumbertype adapterdevicenumber;
booleantype isopen;
booleantype firstblockonmedium;
} devadapterphysicalrequestblktype ;
SCSI device drivers use this structure as an information block to
specify a SCSI bus request when the system is in shutdown mode and a
system dump is in progress.
The fields in this structure are as follows:
type Define the type of the adapter request block and hence
provide for multiple adapter request blocks. This
provision has been made to allow for new types of
adapter request blocks that may be needed as new types
of adapters are added. This field must be defined.
requestflags
Pass flags used to qualify the type of request. See
the Request Flag Literals sub-subsection above.
reserved
Do nothing. This field is reserved for future use by
Data General and must always be set to zero.
scsicmdblk
Pass the SCSI command block, which specifies the
request to be made to the device. The SCSI command
block is not interpreted by the adapter manager.
buffervector
Pass the buffer vector describing the main memory area
that is to be involved in the I/O operation.
sensebuffer
Pass the buffer in which SCSI Request Sense information
is to be returned if a request results in a Check
Condition status.
modeselectbuffer
Pass the buffer to which the device's current operating
mode information is saved.
volume Specify the current volume number.
unitspec
Specify the device's SCSI ID and logical unit number.
adapterdevicenumber
Specify the major and minor device number of the target
adapter.
isopen
Pass a flag that, when set, indicates that the device
has been successfully opened as a system dump target.
firstblockonmedium
Pass a flag used to determine whether to prompt for a
new volume or to notify the shutdown manager to restart
from the last checkpoint if an error occurs.
devscsiadapteroptionsblocktype
typedef struct
{
uint16type driverinterfaceversion;
uint16type adapterinterfaceversion;
} devscsiadapteroptionsblocktype ;
SCSI device drivers use this structure to specify various options to
the devxxxsetadapteroptions routine of the supporting SCSI
adapter driver. Adapter interface version 2 adds this routine to the
interface.
The options specified in this structure affect the adapter though on
a per-unit basis. For example, an option might cause the adapter to
alter its interface definition to a given unit.
The fields in this structure are as follows:
driverinterfaceversion
Specify the SCSI driver/adapter interlace version
supported by the driver. The driver uses this to let
the adapter know which interface version it supports.
adapterinterfaceversion
Specify the SCSI driver/adapter interface version
supported by the adapter manager. The adapter manager
returns this value to the caller, so that the caller
will know what interface version, and therefore what
features are supported by the adapter.
devscsiadapterunitoptionsblocktype
typedef struct
{
miscclockvalueptrtype disconnecttimeoutptr;
miscclockvalueptrtype busrequesttimeoutptr;
uint8type maxdisconnreconnpercommand;
uint8type adapterretries;
uint8type sensebytes;
booleantype synchronousdatatransfers;
booleantype performrequestsorting;
booleantype enablescsi2;
booleantype fastscsi;
booleantype widescsi;
booleantype taggedcommands;
booleantype autosense;
} devscsiadapterunitoptionsblocktype ;
SCSI device drivers use this structure to specify various unit
options to the devxxxsetunitoptions interface of the supporting
SCSI adapter driver.
The options specified in this structure affect the behavior of the
unit connected to an adapter. For example, an option might cause a
given unit to enter a different mode of operation. These options are
different from the unit options, which alter the behavior of the unit
itself.
The fields in this structure are as follows:
disconnecttimeoutptr
Pass a pointer to a driver which will wait after a
disconnect has occurred before assuming that an error
has taken place and that the reselect will not be
occurring. If the timeout interval expires, a timeout
error will be reported back to the caller. A
disconnecttimeoutptr of
DEV_SCSI_ADAPTER_NULL_TIMEOUT_PTR disables disconnect
timeouts for the device.
busrequesttimeoutptr
Pass a pointer to a driver that will wait after a bus
request has been made before assuming an error has
taken place and the request is aborted. A
busrequesttimeoutptr of
DEV_SCSI_ADAPTER_NULL_TIMEOUT_PTR disables bus request
timeouts for the device.
maxdisconnreconnpercommand
Specify the maximum number of times that the SCSI
target device can be expected to disconnect and
reconnect during the execution of a single command.
This value is used by some SCSI adapter drivers to
calculate the maximum amount of time that a single
request to the SCSI adapter should take. The time
value is used as a backup timeout mechanism for SCSI
adapters that manage disconnect timeouts and bus
request timeouts internally. A value of zero for this
field inhibits the device from disconnecting while a
command is executing.
adapterretries
Specify the number of times the SCSI adapter driver
will reissue a request if the request results in a hard
I/O error.
sensebytes
Specify the number of sense bytes that will be returned
from the device if a command to the device results in a
Check Condition status.
synchronousdatatransfers
Pass a flag which, when non-zero, indicates that data
transfer to/from the device should be done in SCSI
synchronous mode. If this option is selected on a
device that does not support synchronous transfers,
data will be transferred in asynchronous mode with no
error reported to the driver.
performrequestsorting
Pass a flag which, when non-zero, indicates that the
adapter driver should perform request sorting and
ordering to provide more efficient access to the
specified device.
enablescsi2
Pass a flag which, when set, indicates that the SCSI
interface should execute commands in SCSI-2 mode using
command tagging. It is up to the individual device
driver to determine whether their devices support
command tagging.
fastscsi
Attempt to use SCSI-2 fast synchronous data transfers
when data is tranferred to/from the device.
widescsi
Attempt to use SCSI-2 wide synchronous data transfers
when data is transferred to/from the device
taggedcommands
Attempt to use simple tagged commands with this device.
autosense
Whenever a check condition occurs, the adapter driver
should automatically issue a request sense command to
return the sense data from the device.
SCSI Adapter Unit Options Block Literals
#define DEVSCSIADAPTERNULLTIMEOUTPTR
#define DEVSCSIADAPTERMINTIMEOUTVALUE
#define DEVSCSIADAPTERMAXTIMEOUTVALUE
#define DEVSCSIADAPTERMINADAPTERRETRIES
#define DEVSCSIADAPTERMAXADAPTERRETRIES
#define DEVSCSIADAPTERMINSENSEBYTES
#define DEVSCSIADAPTERMAXSENSEBYTES
#define DEVSCSIADAPTERMINDISCONRECON
#define DEVSCSIADAPTERMAXDISCONRECON
SCSI device drivers use the following literals with the
devscsiadapterunitoptionsblocktype structure. See
/usr/src/uts/aviion/dev/idevscsiadapterdef.h for the latest list
of literals.
DEVSCSIADAPTERNULLTIMEOUTPTR
Disable timeouts to a unit.
DEVSCSIADAPTERMINTIMEOUTVALUE
Indicate the minimum timeout value supported by a SCSI
adapter driver. This value is in units of
milliseconds.
DEVSCSIADAPTERMAXTIMEOUTVALUE
Indicate the maximum timeout value supported by a SCSI
adapter driver. This value is in units of
milliseconds.
DEVSCSIADAPTERMINADAPTERRETRIES
Indicate the minimum number of adapter retries that can
be specified in a Set Unit Options block.
DEVSCSIADAPTERMAXADAPTERRETRIES
Indicate the maximum number of adapter retries that can
be specified in a Set Unit Options block.
DEVSCSIADAPTERMINSENSEBYTES
Indicate the minimum number of sense bytes that can be
specified in a Set Unit Options block.
DEVSCSIADAPTERMAXSENSEBYTES
Indicate the maximum number of sense bytes that may be
specified in a Set Unit Options block.
DEVSCSIADAPTERMINDISCONRECON
Indicate the minimum number disconnect/reconnects per
command that can be specified in a Set Unit Options
block.
DEVSCSIADAPTERMAXDISCONRECON
Indicate the maximum number disconnect/reconnects per
command that can be specified in a Set Unit Options
block.
Interfaces for Adapter Driver Routines
SCSI device driver routines use SCSI adapter drivers to interface to
the SCSI bus. To write an adapter driver you supply the same
routines as for a device driver plus the routines listed below.
These routines must conform to the interfaces described in the rest
of this man page. As with device driver routines, substitute your
own device mnemonic for the xxx shown in the routine names in this
man page.
The routines listed below are the ones listed in
devscsiinterfaceroutinesvectortype. You supply the entry points
to your adapter routines in this routines vector which you define in
devxxxglobaldata.c. SCSI device drivers obtain the vector to
their adapter driver's routines during device configuration.
devxxxadapteropen
This routine performs device-specific operations needed to prepare
either a device and/or the adapter driver itself to do I/O on a
particular unit.
devxxxadapterclose
This routine performs any necessary exit operations to prepare the
specified adapter to be removed from use.
devxxxregisterrequester
This routine associates the specified device with a SCSI adapter,
thereby establishing a link between the device driver and the adapter
service routines.
This routine adds an entry to the SCSI adapter unit table at the
specified SCSI ID and logical unit number. The unit table entry
consists of a device type specifier and a unit handle, which is
meaningful only to the device driver. The unit table entry provides
a bridge between the device driver and the adapter driver routines.
If the unit table entry specified by the SCSI ID and logical unit
number is already occupied, an error is returned. Also, the device
type of the device occupying the entry is returned so that the caller
can distinguish between IOENXIODEVICEISALREADYCONFIGURED and
IOENXIODEVICEDOESNOTEXIST.
devxxxderegisterrequester
This routine terminates the link between the SCSI adapter manager and
the device referenced by adapterhandle.
devxxxsetadapteroptions
This routine sets the adapter options of a registered device.
This routine is called to set the various options that describe how
the SCSI adapter driver manages a request that has been issued over
the SCSI bus. For a description of the options supported, see the
definition of the devscsiadapteroptionsblock in this man page.
devxxxsetunitoptions
This routine sets the unit options of a registered device. These
options describe how the SCSI adapter driver manages a request that
has been issued over the SCSI bus to a unit. For a description of
the unit options supported, see the definition of the
devscsiadapterunitoptionsblock in this man page.
devxxxissuecommand
This routine issues a SCSI command synchronously through the adapter
to a target device.
The routine performs all of the actions necessary to issue a SCSI
command to the target device. This includes selecting the target
device, issuing the command to the device, managing any data
transfer operations, and returning any device status.
If the request completes with a Check Condition status, sense
information from the device is automatically returned in the adapter
request block.
devxxxissueasynccommand
This routine issues a SCSI command through the adapter to a target
device asynchronously.
The routine performs all of the actions necessary to issue a SCSI
command to the target device asynchronously. This includes selecting
the target device and issuing the command to the device. Unlike the
dev_xxx_issue_command routine, it returns control to the caller
before the I/O request completes. It enqueues the request on the
request queue within the adapter driver then, if possible, starts the
request in the device. If the command list request lock cannot be
obtained, the request is left on the request queue and the function
returns immediately. The enqueued request is started when the
currently executing request and all requests ahead in the queue have
been executed.
The Driver or the I/O Driver Server handles request completion and
starts the next request in the queue if there is one.
devxxxissuecommandphysicalmode
This routine issues a I/O request through the SCSI adapter to a
target device as part of the kernel's system dump operation. The
system calls this routine to issue a synchronous I/O request over the
SCSI bus without the use of the normal operating system facilities.
This routine should perform synchronization without the use of event
counters or interrupts. It should assume all buffer addresses are
physical. It can also assume that system is running a single thread
of control, so no lock management is required.
devxxxadapterioctl
This routine performs the specified control operation on the
specified adapter.
devxxxgetdeviceinfo
This routine retrieves the driver handle that was registered with the
device.
DIAGNOSTICS
Return Value
For devxxxadapteropen:
OK The specified device was successfully opened.
Other return values that you deem necessary
The receiving device driver should be prepared to
handle these return values.
For devxxxadapterclose:
OK The specified device was successfully closed.
Other return values that you deem necessary
The receiving device driver should be prepared to
handle these return values.
For devxxxregisterrequester:
OK The specified device was successfully registered with
the adapter.
IOENXIODEVICEISALREADYCONFIGURED
A device is already registered at the location
specified by rbptr.
For devxxxderegisterrequester: None.
For devxxxsetadapteroptions:
OK The requested options were selected successfully.
Other return values that you deem necessary
The receiving device driver should be prepared to
handle these return values.
For devxxxsetunitoptions:
OK The requested options were selected successfully.
DEVSTATUSSCSIILLEGALUNITOPTIONSVALUE
An illegal option value was detected in the callers Set
Unit Options block.
IOEIOPHYSICALUNITFAILURE
Some serious error occurred in attempting to set the
requested options in the adapter controller.
For devxxxissuecommand:
OK A synchronous request completed successfully.
Other return values that you deem necessary
You may define additional return values for your
adapter if the receiving device drivers are prepared to
handle them.
For devxxxissueasynccommand:
OK The request was successfully started. This status does
not indicate that the request has completed
successfully.
For devxxxissuecommandphysicalmode:
OK A synchronous request completed successfully.
DEVSTATUSSCSICMDCOMPLETECHECKCONDITION
The command completed with a Check Condition status,
and sense information is available in the caller's
sense buffer.
IOEIOHARDIOERROR
The command completed with a check condition status,
and the subsequent request sense command failed.
Other return values that you deem necessary
You may define additional return values for your
adapter if the receiving device drivers are prepared to
handle them.
For devxxxadapterioctl:
OK The command was successfully executed.
IOEINVALCOMMANDNOTSUPPORTEDBYDEVICE
This driver does not implement the indicated command.
For devxxxgetdeviceinfo:
OK The driver handle was successfully retrieved and
returned.
IOENXIODEVICEISNOTCONFIGURED
A device of the specified type is not registered at the
SCSI ID and unit number slot.
SEE ALSO
adaptermanager(3K), devicedriver(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)