adapter_driver(3K) DG/UX R4.11MU05 adapter_driver(3K)
NAME
adapter_driver: dev_xxx_adapter_open, dev_xxx_adapter_close,
dev_xxx_register_requester, dev_xxx_deregister_requester,
dev_xxx_set_adapter_options, dev_xxx_set_unit_options,
dev_xxx_issue_command, dev_xxx_issue_async_command,
dev_xxx_issue_command_physical_mode, dev_xxx_adapter_ioctl,
dev_xxx_get_device_info - implement an adapter driver
SYNOPSIS
#include "/usr/src/uts/aviion/dev/dev_scsi_adapter_def.h"
status_type dev_xxx_adapter_open (
io_device_handle_type adapter_handle, READ_ONLY
io_channel_flags_type channel_flags READ_ONLY )
status_type dev_xxx_adapter_close (
io_device_handle_type adapter_handle, READ_WRITE
io_channel_flags_type channel_flags READ_WRITE )
status_type dev_xxx_register_requester (
dev_scsi_adapter_unit_registration_blk_ptr_type rb_ptr READ_WRITE )
void dev_xxx_deregister_requester (
io_device_handle_type adapter_handle READ_ONLY )
status_type dev_xxx_set_adapter_options (
io_device_handle_type adapter_handle, READ_ONLY
dev_scsi_adapter_options_block_ptr_type adap_opt_blk_ptr READ_WRITE)
status_type dev_xxx_set_unit_options (
io_device_handle_type adapter_handle, READ_ONLY
dev_scsi_adapter_unit_options_block_ptr_type u_opt_blk_ptr READ_WRITE)
status_type dev_xxx_issue_command (
dev_adapter_request_block_ptr_type arb_ptr READ_WRITE )
status_type dev_xxx_issue_async_command (
dev_adapter_request_block_ptr_type arb_ptr READ_WRITE )
status_type dev_xxx_issue_command_physical_mode (
dev_adapter_physical_request_blk_ptr_type request_blk_ptr READ_WRITE)
status_type dev_xxx_adapter_ioctl (
io_device_handle_type adapter_handle, READ_ONLY
bit32e_type command, READ_ONLY
bit32e_type parameter, READ_WRITE
int32e_ptr_type return_val_ptr WRITE_ONLY )
status_type dev_xxx_get_device_info (
io_device_number_type adapter_device_number, READ_ONLY
dev_scsi_adapter_unit_spec_type unit_spec, READ_ONLY
bit8_type device_type, READ_ONLY
bit32e_ptr_type driver_handle_ptr WRITE_ONLY )
where:
adap_opt_blk_ptr Pointer to an adapter options block that specifies
the options to be selected for the unit.
adapter_device_number
The major and minor device number of the SCSI
adapter used to access the target unit.
adapter_handle 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.
arb_ptr A pointer to an adapter request block that holds
all information that describes the request.
channel_flags 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.
device_type Device type of device expected to be registered for
unit number and SCSI ID.
driver_handle_ptr 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.
rb_ptr A pointer to a SCSI adapter registration block.
request_blk_ptr 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.
return_value_ptr A pointer to the value to be returned to the user.
If the command fails, minus one (-1) is returned.
u_opt_blk_ptr Pointer to a unit options block that specifies the
options to be selected for the unit.
unit_spec 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:
dev_xxx_adapter_open Prepare device or adapter driver for I/O
dev_xxx_adapter_close Prepare adapter to be removed from use
dev_xxx_register_requester Associate device with a SCSI adapter
dev_xxx_deregister_requester Terminate the link between the SCSI
adapter manager and a device
dev_xxx_set_adapter_options Set registered device's adapter options
dev_xxx_set_unit_options Set unit options of a registered device
dev_xxx_issue_command Issue a SCSI command synchronously
dev_xxx_issue_async_command Issue a SCSI command asynchronously
dev_xxx_issue_command_physical_mode
Issue a physical I/O request to device
dev_xxx_adapter_ioctl Perform control operation on adapter
dev_xxx_get_device_info Get driver handle registered with device
The adapter_manager(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 server_messages(3K) man page describes how to define an error
status and how to log an error to the error server. The sc_panic(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.
dev_scsi_adapter_routines_vector_type
typedef struct
{
io_driver_routines_vector_type driver_routines;
dev_scsi_interface_routines_vector_type scsi_routines;
} dev_scsi_adapter_routines_vector_type ;
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.
dev_scsi_interface_routines_vector_type
typedef struct
{
uint16_type version;
bit16_type flags;
status_type (*register_requester)();
status_type (*set_unit_options)();
void (*deregister_requester)();
status_type (*issue_command)();
status_type (*issue_async_command)();
status_type (*get_device_info)();
status_type (*issue_command_physical_mode)();
status_type (*set_adapter_options)();
status_type (*adapter_open)();
status_type (*adapter_close)();
status_type (*adapter_ioctl)();
} dev_scsi_interface_routines_vector_type ;
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 DEV_SCSI_INTERFACE_VERSION_2. The flags field is currently
unused.
dev_scsi_adapter_unit_spec_type
typedef struct
{
uint8_type scsi_id;
uint8_type unit;
} dev_scsi_adapter_unit_spec_type ;
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:
scsi_id Pass the target device's SCSI ID on the SCSI bus.
unit Pass the logical unit number of the target device.
dev_adapter_request_block_type
typedef struct
{
misc_queue_links_type links;
uint16_type type;
bit16e_type request_flags;
uint32_type reserved;
io_device_handle_type adapter_handle;
dev_scsi_cmd_blk_type scsi_cmd_blk;
dev_scsi_adapter_unit_spec_type unit_spec;
io_buffer_vector_type buffer_vector;
dev_scsi_request_sense_buffer_type sense_buffer;
boolean_type sync_io;
io_operation_record_ptr_type op_record_ptr;
io_completion_routine_ptr_type complete_io_routine;
misc_clock_value_type request_start_time;
misc_clock_value_type total_request_busy_time
status_type async_start_status;
uint32_type scsi_command_size;
uint32_type scsi_status;
} dev_adapter_request_block_type ;
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.
request_flags
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.
adapter_handle
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.
scsi_cmd_blk
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.
unit_spec
Pass the target device's SCSI ID and logical unit
number.
buffer_vector
Pass the buffer vector describing the main memory area
that is to be involved in the I/O operation.
sync_io
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.
op_record_ptr
When the operation is to be performed asynchronously,
pass a pointer to the original operation record that
specified the request.
complete_io_routine
When operation is to be performed asynchronously, pass
the address of the caller's I/O completion routine.
request_start_time
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.
total_request_busy_time
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.
async_start_status
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.
scsi_command_size
Specify the size of the SCSI command descriptor block.
This field is used determine the size of a vendor
unique SCSI command descriptor block.
scsi_status
Return the status of the SCSI command which was issued
to the device.
Request Flag Literals
#define DEV_SCSI_REQUEST_FLAGS_NONE
#define DEV_SCSI_REQUEST_FLAGS_KERNEL_BUFFER
#define DEV_SCSI_REQUEST_FLAGS_PHYSICAL_BUFFER
#define DEV_SCSI_REQUEST_FLAGS_SB_DONE
#define DEV_SCSI_REQUEST_FLAGS_SB
#define DEV_SCSI_REQUEST_FLAGS_SB_READ
#define DEV_SCSI_REQUEST_FLAGS_DATA_XFER_IN
The following constants define bit positions of the request flags
used in the request_flags field of dev_adapter_request_block_type.
The options are as follows:
DEV_SCSI_REQUEST_FLAGS_NONE
SCSI device drivers use this literal to indicate that
no special flags are set.
DEV_SCSI_REQUEST_FLAGS_KERNEL_BUFFER
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.
DEV_SCSI_REQUEST_FLAGS_PHYSICAL_BUFFER
SCSI device drivers use this literal to indicate that
the data buffer address specified in the request block
is a physical address.
DEV_SCSI_REQUEST_FLAGS_SB_DONE
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.
DEV_SCSI_REQUEST_FLAGS_SB
This literal is used by the DG/UX sector-buffering
mechanism. When set, it indicates that sector
buffering is enabled for device access.
DEV_SCSI_REQUEST_FLAGS_SB_READ
This literal is used by the DG/UX sector-buffering
mechanism. When set, it indicates that a sector
buffered read is taking place.
DEV_SCSI_REQUEST_FLAGS_DATA_XFER_IN
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.
dev_scsi_adapter_unit_registration_blk_type
typedef struct
{
io_device_number_type adapter_device_number;
dev_scsi_adapter_unit_spec_type unit_spec;
io_device_handle_type adapter_handle;
io_device_handle_type driver_handle;
uint16_type max_concurrent_requests;
bit16_type interface_flags;
uint32_type max_request_size;
bit8_type device_type;
} dev_scsi_adapter_unit_registration_blk_type ;
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:
adapter_device_number
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.
unit_spec
SCSI device drivers use this field to pass the SCSI ID
and logical unit number of the device being registered.
adapter_handle
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.
driver_handle
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
dev_xxx_get_device_info routine. The adapter manager
does not interpret this field.
max_concurrent_requests
SCSI device drivers use this field to pass the maximum
number of concurrently executing requests on the unit
that the driver will allow.
interface_flags
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.
max_request_size
The adapter driver uses this field to return the
maximum number of bytes transferable between the host
and device in a single operation.
device_type
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 device_type is
recorded for the device. The values used in this field
are given under Device Type Literals below.
Interface Flag Literals
#define DEV_SCSI_REGISTRATION_BLK_FLAGS_NONE
#define DEV_SCSI_REGISTRATION_BLK_FLAGS_SCSI2_SUPPORTED
#define DEV_SCSI_REGISTRATION_BLK_FLAGS_32LUN_SUPPORTED
The following constants define values of the flags used in the
interface_flags field of an adapter request block described by
dev_scsi_adapter_unit_registration_blk_type. The options are as
follows:
DEV_SCSI_REGISTRATION_BLK_FLAGS_NONE
SCSI device drivers use this literal if no options
other than the defaults are supported.
DEV_SCSI_REGISTRATION_BLK_FLAGS_SCSI2_SUPPORTED
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).
DEV_SCSI_REGISTRATION_BLK_FLAGS_32LUN_SUPPORTED
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 DEV_SCSI_ENCODED_DEVICE_DIRECT_ACCESS
#define DEV_SCSI_ENCODED_DEVICE_SEQUENTIAL_ACCESS
#define DEV_SCSI_ENCODED_DEVICE_PRINTER
#define DEV_SCSI_ENCODED_DEVICE_PROCESSOR
#define DEV_SCSI_ENCODED_DEVICE_WRITE_ONCE_READ_MULTIPLE
#define DEV_SCSI_ENCODED_DEVICE_DIRECT_ACCESS_READ_ONLY
#define DEV_SCSI_ENCODED_DEVICE_GENERAL_DIRECT_ACCESS
The following constants define values of the types used in the
device_type field of an adapter request block described by
dev_scsi_adapter_unit_registration_blk_type. The options are as
follows:
DEV_SCSI_ENCODED_DEVICE_DIRECT_ACCESS
Indicate that the device is a direct access device, for
example, disk.
DEV_SCSI_ENCODED_DEVICE_SEQUENTIAL_ACCESS
Indicate that the device is a sequential access device,
for example, tape.
DEV_SCSI_ENCODED_DEVICE_PRINTER
Indicate that the device is a printer.
DEV_SCSI_ENCODED_DEVICE_PROCESSOR
Indicate that the device is a processor, for example, a
CPU.
DEV_SCSI_ENCODED_DEVICE_WRITE_ONCE_READ_MULTIPLE
Indicate that the device is a WORM access device.
DEV_SCSI_ENCODED_DEVICE_DIRECT_ACCESS_READ_ONLY
Indicate that the device is a read-only device, for
example, a CDROM.
DEV_SCSI_ENCODED_DEVICE_GENERAL_DIRECT_ACCESS
Indicate that the device is any direct access device.
This define may be used for disks, WORM devices, or
CDROM devices.
dev_adapter_physical_request_blk_type
typedef struct
{
uint16_type type;
uint16_type request_flags;
uint32_type reserved;
dev_scsi_cmd_blk_type scsi_cmd_blk;
io_buffer_vector_type buffer_vector;
dev_scsi_request_sense_buffer_type sense_buffer;
dev_scsi_mode_buffer_type mode_select_buffer;
uint16_type volume;
dev_scsi_adapter_unit_spec_type unit_spec;
io_device_number_type adapter_device_number;
boolean_type is_open;
boolean_type first_block_on_medium;
} dev_adapter_physical_request_blk_type ;
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.
request_flags
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.
scsi_cmd_blk
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.
buffer_vector
Pass the buffer vector describing the main memory area
that is to be involved in the I/O operation.
sense_buffer
Pass the buffer in which SCSI Request Sense information
is to be returned if a request results in a Check
Condition status.
mode_select_buffer
Pass the buffer to which the device's current operating
mode information is saved.
volume Specify the current volume number.
unit_spec
Specify the device's SCSI ID and logical unit number.
adapter_device_number
Specify the major and minor device number of the target
adapter.
is_open
Pass a flag that, when set, indicates that the device
has been successfully opened as a system dump target.
first_block_on_medium
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.
dev_scsi_adapter_options_block_type
typedef struct
{
uint16_type driver_interface_version;
uint16_type adapter_interface_version;
} dev_scsi_adapter_options_block_type ;
SCSI device drivers use this structure to specify various options to
the dev_xxx_set_adapter_options 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:
driver_interface_version
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.
adapter_interface_version
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.
dev_scsi_adapter_unit_options_block_type
typedef struct
{
misc_clock_value_ptr_type disconnect_timeout_ptr;
misc_clock_value_ptr_type bus_request_timeout_ptr;
uint8_type max_disconn_reconn_per_command;
uint8_type adapter_retries;
uint8_type sense_bytes;
boolean_type synchronous_data_transfers;
boolean_type perform_request_sorting;
boolean_type enable_scsi_2;
boolean_type fast_scsi;
boolean_type wide_scsi;
boolean_type tagged_commands;
boolean_type auto_sense;
} dev_scsi_adapter_unit_options_block_type ;
SCSI device drivers use this structure to specify various unit
options to the dev_xxx_set_unit_options 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:
disconnect_timeout_ptr
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
disconnect_timeout_ptr of
DEV_SCSI_ADAPTER_NULL_TIMEOUT_PTR disables disconnect
timeouts for the device.
bus_request_timeout_ptr
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
bus_request_timeout_ptr of
DEV_SCSI_ADAPTER_NULL_TIMEOUT_PTR disables bus request
timeouts for the device.
max_disconn_reconn_per_command
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.
adapter_retries
Specify the number of times the SCSI adapter driver
will reissue a request if the request results in a hard
I/O error.
sense_bytes
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.
synchronous_data_transfers
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.
perform_request_sorting
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.
enable_scsi_2
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.
fast_scsi
Attempt to use SCSI-2 fast synchronous data transfers
when data is tranferred to/from the device.
wide_scsi
Attempt to use SCSI-2 wide synchronous data transfers
when data is transferred to/from the device
tagged_commands
Attempt to use simple tagged commands with this device.
auto_sense
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 DEV_SCSI_ADAPTER_NULL_TIMEOUT_PTR
#define DEV_SCSI_ADAPTER_MIN_TIMEOUT_VALUE
#define DEV_SCSI_ADAPTER_MAX_TIMEOUT_VALUE
#define DEV_SCSI_ADAPTER_MIN_ADAPTER_RETRIES
#define DEV_SCSI_ADAPTER_MAX_ADAPTER_RETRIES
#define DEV_SCSI_ADAPTER_MIN_SENSE_BYTES
#define DEV_SCSI_ADAPTER_MAX_SENSE_BYTES
#define DEV_SCSI_ADAPTER_MIN_DISCON_RECON
#define DEV_SCSI_ADAPTER_MAX_DISCON_RECON
SCSI device drivers use the following literals with the
dev_scsi_adapter_unit_options_block_type structure. See
/usr/src/uts/aviion/dev/i_dev_scsi_adapter_def.h for the latest list
of literals.
DEV_SCSI_ADAPTER_NULL_TIMEOUT_PTR
Disable timeouts to a unit.
DEV_SCSI_ADAPTER_MIN_TIMEOUT_VALUE
Indicate the minimum timeout value supported by a SCSI
adapter driver. This value is in units of
milliseconds.
DEV_SCSI_ADAPTER_MAX_TIMEOUT_VALUE
Indicate the maximum timeout value supported by a SCSI
adapter driver. This value is in units of
milliseconds.
DEV_SCSI_ADAPTER_MIN_ADAPTER_RETRIES
Indicate the minimum number of adapter retries that can
be specified in a Set Unit Options block.
DEV_SCSI_ADAPTER_MAX_ADAPTER_RETRIES
Indicate the maximum number of adapter retries that can
be specified in a Set Unit Options block.
DEV_SCSI_ADAPTER_MIN_SENSE_BYTES
Indicate the minimum number of sense bytes that can be
specified in a Set Unit Options block.
DEV_SCSI_ADAPTER_MAX_SENSE_BYTES
Indicate the maximum number of sense bytes that may be
specified in a Set Unit Options block.
DEV_SCSI_ADAPTER_MIN_DISCON_RECON
Indicate the minimum number disconnect/reconnects per
command that can be specified in a Set Unit Options
block.
DEV_SCSI_ADAPTER_MAX_DISCON_RECON
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
dev_scsi_interface_routines_vector_type. You supply the entry points
to your adapter routines in this routines vector which you define in
dev_xxx_global_data.c. SCSI device drivers obtain the vector to
their adapter driver's routines during device configuration.
dev_xxx_adapter_open
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.
dev_xxx_adapter_close
This routine performs any necessary exit operations to prepare the
specified adapter to be removed from use.
dev_xxx_register_requester
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 IO_ENXIO_DEVICE_IS_ALREADY_CONFIGURED and
IO_ENXIO_DEVICE_DOES_NOT_EXIST.
dev_xxx_deregister_requester
This routine terminates the link between the SCSI adapter manager and
the device referenced by adapter_handle.
dev_xxx_set_adapter_options
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 dev_scsi_adapter_options_block in this man page.
dev_xxx_set_unit_options
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
dev_scsi_adapter_unit_options_block in this man page.
dev_xxx_issue_command
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.
dev_xxx_issue_async_command
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.
dev_xxx_issue_command_physical_mode
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.
dev_xxx_adapter_ioctl
This routine performs the specified control operation on the
specified adapter.
dev_xxx_get_device_info
This routine retrieves the driver handle that was registered with the
device.
DIAGNOSTICS
Return Value
For dev_xxx_adapter_open:
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 dev_xxx_adapter_close:
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 dev_xxx_register_requester:
OK The specified device was successfully registered with
the adapter.
IO_ENXIO_DEVICE_IS_ALREADY_CONFIGURED
A device is already registered at the location
specified by rb_ptr.
For dev_xxx_deregister_requester: None.
For dev_xxx_set_adapter_options:
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 dev_xxx_set_unit_options:
OK The requested options were selected successfully.
DEV_STATUS_SCSI_ILLEGAL_UNIT_OPTIONS_VALUE
An illegal option value was detected in the callers Set
Unit Options block.
IO_EIO_PHYSICAL_UNIT_FAILURE
Some serious error occurred in attempting to set the
requested options in the adapter controller.
For dev_xxx_issue_command:
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 dev_xxx_issue_async_command:
OK The request was successfully started. This status does
not indicate that the request has completed
successfully.
For dev_xxx_issue_command_physical_mode:
OK A synchronous request completed successfully.
DEV_STATUS_SCSI_CMD_COMPLETE_CHECK_CONDITION
The command completed with a Check Condition status,
and sense information is available in the caller's
sense buffer.
IO_EIO_HARD_IO_ERROR
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 dev_xxx_adapter_ioctl:
OK The command was successfully executed.
IO_EINVAL_COMMAND_NOT_SUPPORTED_BY_DEVICE
This driver does not implement the indicated command.
For dev_xxx_get_device_info:
OK The driver handle was successfully retrieved and
returned.
IO_ENXIO_DEVICE_IS_NOT_CONFIGURED
A device of the specified type is not registered at the
SCSI ID and unit number slot.
SEE ALSO
adapter_manager(3K), device_driver(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)