[ Previous |
Next |
Contents |
Home |
Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 2
ssadisk SSA Disk Device Driver
Purpose
Supports Serial Storage Architecture (SSA) disk
drives.
Syntax
#include <sys/devinfo.h>
#include <sys/ssa.h>
#include <sys/ssadisk.h>
Configuration Issues
SSA Logical disks, SSA Physical disks, and SSA
RAID Arrays
Serial Storage Architecture (SSA) disk drives are
represented in AIX as SSA logical disks (hdisk0,
hdisk1.....hdiskN) and SSA physical disks
(pdisk0,pdisk1.....pdiskN). SSA RAID arrays are represented
as SSA logical disks (hdisk0, hdisk1.....hdiskN). SSA
logical disks represent the logical properties of the disk drive or array, and can have
volume groups and file systems mounted on them. SSA physical disks represent the
physical properties of the disk drive.
By default:
- One pdisk is always configured for each physical
disk drive.
- One hdisk is configured either for each disk drive
that is connected to the using system, or for each array.
By default, all disk drives are configured as system
(AIX) disk drives. The array management software deletes hdisks to create arrays.
SSA physical disks have the following properties:
- configured as pdisk0,
pdisk1.....pdiskN
- Have errors logged against them in the system error
log.
- Support a character special file (/dev/pdisk0,
/dev/pdisk1..../dev/pdiskN)
- Support the ioctl subroutine for servicing and
diagnostics functions.
- Did not accept read or write subroutine
calls for the character special file.
SSA logical disks have the following properties:
- configured as hdisk0,
hdisk1.....hdiskN
- Support a character special file (/dev/rhdisk0,
/dev/rhdisk1..../dev/rhdiskN)
- Support a block special file (/dev/hdisk0,
/dev/hdisk1..../dev/hdiskN)
- Support the ioctl subroutine call for non
service and diagnostics functions only.
- Accept the read and write subroutine
call to the special files.
- Can be members of volume groups and have filesystems
mounted upon them.
Multiple Adapters
Some SSA subsystems allow a disk drive to be controlled by up to two adapters in a particular
using system. The disk drive has, therefore, two paths to each using system,
and the SSA subsystem can continue to function if an adapter fails. If an
adapter fails or the disk drive becomes inaccessible from the original
adapter, the SSA disk device driver switches to the alternative adapter
without returning an error to any working application.
Once a disk drive has been sucessfully opened, takeover by the alternative
adapter does not occur simply because a drive becomes reserved or fenced out.
However, during an open of a ssa logical disk, the device driver does attempt
to access the disk drive through the alternative adapter if the path through
the original adapter experiences reservation conflict or fenced-out
status.
Takeover does not occur because of a medium error on the disk drive.
Takover occurs only after extensive error-recovery activity within the
adapter and several retries by the device driver. Intermittent errors that
last for only approximately one second usually do not cause adapter
takeover.
Once takeover has successfully occurred and the device driver has accessed
the disk drive through the alternative adapter, the original adapter becomes
the standby adapter. Takeover can, therefore, occur repeatedly from one
adapter to another so long as one takeover event is completed before the next
one starts. Completion of a takeover event is considered to have occurred when
the device driver successfully accesses the disk drive through the alternative
adapter.
Once takeover has occurred, the device driver continues to use the
alternative adapter to access the disk drive until either the system is
rebooted, or takeover occurs back to the original adapter.
Each time the SSA disks are configured, the SSA disk device driver is
informed which path or paths are available to each disk drive, and which
adapter is to be used as the primary path. By default, primary paths to disk
drives are shared equally among the adapters to balance the load. This static
load balancing is performed once, when the devices are configured for the
first time. You can use the chdev command to modify the primary
path.
Because of the dynamic nature of the relationship between SSA adapters and
disk drives, SSA pdisks and hdisks are not children of an adapter but of an
SSA router. This router is called ssar. It does not represent any
actual hardware, but exists only to be the parent device for the SSA logical
disks and SSA physical disks.
Note: |
When the SSA disk device driver switches from using one adapter to using the
other adapter to communicate with a disk, it issues a command that breaks any
SSA-SCSI reserve condition that might exist on that disk. The reservation break is only performed if this host had
successfully reserved the disk drive through the original adapter. This check
is to prevent adapter takeover from breaking reservations held by other using
systems. If multiple using systems are connected to the SSA disks, SSA-SCSI
reserve should not, therefore, be used as the only method for controlling
access to the SSA disks. Fencing is provided as an alternative method for
controlling access to disks that are connected to multiple using systems. |
PCI SSA Multi-Initiator/RAID EL Adapters and Micro Channel Enhanced SSA
Multi-Initiator/RAID EL Adapters are capable of reserving to a node number
rather than reserving to an adapter.
It is highly recommended that you make use of this
ability by setting the SSA router node_number attribute if multiple
adapters are to be configured as described here.
Configuring SSA disk drive devices.
(SSA) disk drives are represented in AIX as SSA
Logical disks (hdisk0, hdisk1.....hdiskN) and SSA physical disks
(pdisk0,pdisk1.....pdiskn). The properties of each are
described in the SSA Subsystem Overview.
Normally, all the disk drives connected to the system
will be configured automatically by the system boot process and the user will need to
take no action to configure them.
Since some SSA devices may be connected to the SSA
network while the system is running without taking the system off line it may be
necessary to configure SSA disks after the boot process has completed. In this case the
devices should be configured by running the configuration manager with the cfgmgr
command.
An exception is to configure a specific device with a
specific name. This may be achieved using the mkdev command.
Using mkdev to Configure a Physical Disk
To use mkdev to configure a SSA physical
disk it will be necessary to specify the following information:
Parent |
ssar |
Class |
pdisk |
Subclass |
ssar |
Type |
You can list the types by typing: lsdev -P -c pdisk -s ssar |
ConnectionLocation |
15-character unique identity of the disk drive. You can determine the unique
identifier in three ways:
- If the disk drive has already been defined the
unique identity may be determined using the lsdev command as follows:
- Enter lsdev -Ccpdisk -r
connwhere.
- Select the 15-character unique identifier for which
characters 5 to 12 match those on the front of the disk drive.
- Otherwise the 15-character unique identifier can be
constructed from the 12-character SSA UID on the label on the side of the disk drive
suffixed by the 3 characters "00D".
- Run the ssacand command, and specify the
adapter to which the physical disk is connected. For example:
ssacand -a ssaO -P
|
Using mkdev to Configure a Logical Disk
In order to use mkdev to configure a SSA
logical disk it will be necessary to specify the following information:
Parent |
ssar |
Class |
disk |
Subclass |
ssar |
Type |
hdisk |
ConnectionLocation |
15-character unique identity of the disk drive.
If the logical disk is a system (AIX) disk, you can
determine the unique identifier in three ways:
- If the disk drive has already been defined the
unique identity may be determined using the lsdev command as follows:
- Enter lsdev -Ccpdisk -r connwhere
and
press Enter.
- Select the 15-character unique identifier for which
characters 5 to 12 match the serial number that is on the front of the disk drive.
- Construct 15-character unique identifier can be
constructed from the 12-character SSA UID on the label on the side of the disk drive
suffixed by the 3 characters "00D".
- Run the ssacand command, and specify the
adapter to which the logical disk is connected. For example:
ssacand -a ssaO -L
If the logical disk is an array, you can determine the
unique identifier in two ways:
- If the logical disk has already been defined, you
can use the lsdev command to determine the unique identy, as follows:
- Type lsdev -Ccdisk -r connwhere
and
press Enter.
- Select the 15-character unique identifer that was
given by the RAID configuration program when the array was created.
- Run the ssacand command, and specify the
adapter to which the logical disk is connected. For example:
ssacand -a ssaO -L
|
Device Attributes
SSA logical disks and SSA physical disks and the
ssar router, have several attributes.You can use the lsattr command to display
these attributes.
Attributes of the SSA Router, ssar.
node_number |
This must be set on systems which are using SSA Fencing or the SSA Disk
Concurrent Mode of Operation Interface.
Both of these features of the SSA disk device driver are used only in configurations
which have more than one host system connected to the same SSA disk drives. In
configurations where only one host system is connected to the SSA disk drives this
attribute has no effect.
For configurations using SSA Fencing or the SSA Disk Concurrent Mode of Operation
Interface this attribute should be set to a different value on each host in the
configuration.
Note: After this attribute has been
modified it is necessary to reboot the system for it to take effect.
|
Attributes which are common to SSA logical and SSA
physical disks.
adapter_a |
Specifies the name of one adapter connected to the device or none if
no adapter is currently connected as adapter_a. |
adapter_b |
Specifies the name of one adapter connected to the device or none if
no adapter is currently connected as adapter_b. |
primary_adapter |
Specifies whether adapter_a or adapter_b is to be the primary adapter for
this device.
This attribute may be modified using the chdev command to one of the values
adapter_a, adapter_b or assign. If the value is set to assign, static load
balancing will be performed when this device is made available and the system will set
the value to either adapter_a or adapter_b. |
connwhere_shad |
Holds a copy of the value of the connwhere parameter for this disk drive. SSA
disks drives cannot be identified by the location field given by lsdev. This is because
they are connected in a loop and do not have hardware-selectable addresses like SCSI
devices. The only means of identification of SSA devices is their serial number and this
is written in the connwhere field of the CuDv entry for the device. Providing this
connwhere_shad attribute, which shadows the connwhere value, means the
user can display the connwhere value for an SSA device for a pdisk or hdisk. |
location |
Describes, in text, the descriptions of the disk drives and their locations
(for example, drawer number 1, slot number 1). The information for this attribute is
entered by the user. |
Attributes for SSA Logical Disks Only
- pvid
- Holds the ODM copy of the PVID for this disk drive for an hdisk.
- queue_depth
- Specifies the maximum number of commands that the SSA disk device driver
dispatches for a single disk drive for an hdisk. You can use the
chdev command to modify this attribute. The default value is
correct for normal operating conditions.
- reserve_lock
- Specifies whether the SSA disk device driver locks the device with a
reservation when it is opened for an hdisk.
- size_in_mb
- Specifies the size of the logical disk in megabytes.
- max_coalesce
- This is the maximum number of bytes which the SSA disk device driver
attempts to transfer to or from an SSA logical disk in a single operation.
The default value is appropriate for most environments. For applications
that perform very long sequential write operations, there are performance
benefits in writing data in blocks of 64KB times the number of disks in the
array minus one (these are known as full-stride writes
times the number of disks in the array minus one, or to some multiple of this
number.
- write_queue_mod
- Alters the way in which write commands are queued to SSA logical disks.
The default value is 0 for all SSA logical disks that do not use the
fast-write cache; with this setting the SSA disk device driver maintains a
single seek-ordered queue of queue_depth operations on the disk. Reads and
writes are queued together in this mode.
If write_queue_mod is set to a non-zero value, the SSA disk device driver
maintains two separate seek-ordered queues, one for reads and one for writes.
In this mode, the device driver issues up to queue_depth read commands and up
to write_queue_mod write commands to the logical disk.
This facility is provided because in some environments it may be
beneficial to hold back write commands in the device driver so that they may
be coalesced into larger operations which may be handled as full-stride writes
by the RAID software within the adapter.
This facility is unlikely to be useful unless a large percentage of the
workload to a RAID-5 device is composed of sequential write operations.
Device-Dependent Subroutines
open, read, write and close Subroutines
The open subroutine is intended primarily
for use by the diagnostic commands and utilities. Appropriate authority is required for
execution. If an attempt is made to run the open subroutine without the proper
authority, the subroutine returns a value of -1 and sets the errno global
variable to a value of EPERM.
The ext parameter passed to the openx
subroutine selects the operation to be used for the target device. The
/usr/include/sys/ssadisk.h file defines possible values for the ext parameter.
The ext parameter can contain any combination of
the following flag values logically ORed together:
SSADISK_PRIMARY |
Opens the device using the primary adapter as the path to the device. As a
result of hardware errors the device driver may automatically switch to the secondary
path if one exists. This can be prevented by additionally specifying the
SSADISK_NOSWITCH flag.
This flag is supported for both SSA logical disks and SSA physical disk drives.This
flag cannot be specified together with SSADISK_SECONDARY. |
SSADISK_SECONDARY |
Opens the device using the secondary adapter as the path to the device. As a
result of hardware errors the device driver may automatically switch to the primary path
if one exists. This can be prevented by additionally specifying the
SSADISK_NOSWITCH flag.
This flag is supported for both SSA logical disks and SSA physical disk drives.This
flag cannot be specified together with SSADISK_PRIMARY. |
SSADISK_NOSWITCH |
If more than one adapter provides a path to the device, the device driver
normally switches from one adapter to the other as part of its error recovery. This flag
prevents this from happening.
This flag is supported for both SSA logical disks and SSA physical disk drives. |
SSADISK_FORCED_OPEN |
Forces the open regardless of whether another initiator has the device
reserved. If another initiator has the device reserved, the reservation is broken. In
other respects, the open operation runs normally.
This flag is supported only for SSA logical disks. This flag cannot be specified
together with SSADISK_FENCEMODE. |
SSADISK_RETAIN_RESERVATION |
Retains the reservation of the device after a close operation by not
issuing the release. This flag prevents other initiators from using the device unless
they break the host machine's reservation.
Note: This does not cause the device to
be explicitly reserved during the close if it was not reserved while it was open.
This flag is supported only for SSA logical disk drives. This flag cannot be
specified together with SSADISK_FENCEMODE. |
SSADISK_NO_RESERVE |
Prevents the reservation of a device during an openx subroutine call
to that device. This operation is provided so a device can be controlled by two
processors that synchronize their activity by their own software means.
This flag overrides the setting of the attribute reserve_lock if the value of the
attribute is yes. This flag is supported only for SSA logical disk drives. This flag
cannot be specified together with SSADISK_FENCEMODE. |
SSADISK_SERVICEMODE |
Opens an SSA physical disk in service mode. This wraps the SSA links either
size of the indicated physical disk allowing it to be removed from the loop for service
without causing errors on the loops.
This flag is supported only for SSA physical disk drives. This flag cannot be
specified together with SSADISK_SCSIMODE. |
SSADISK_SCSIMODE |
Opens an SSA physical disk in SCSI passthrough mode. This allows
SSADISK_IOCTL_SCSI ioctls to be issued to the physical disk.
This flag is supported only for SSA physical disk drives. This flag cannot be
specified together with SSADISK_SERVICEMODE. |
SSADISK_NORETRY |
Opens a device in no-retry mode.
When a device is opened in this mode, commands are not retried if an error occurs.
This flag is supported only for SSA physical disk drives. |
SSADISK_FENCEMODE |
Opens an SSA logical disk drive in fence mode. The open succeeds even if the
host is fenced out from access to the disk drive. Only ioctls can be issued to the
device while it is open in this mode. Any attempt to read from or write to a device
opened in this mode will be rejected with an error.
This flag is supported only for SSA logical disk drives. This flag cannot be
specified together with SSADISK_NO_RESERVE, SSADISK_FORCED_OPEN or
SSADISK_RETAIN_RESERVATION. |
"SSA Options to the openx Subroutine" in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts
gives more specific information on the open operations.
readx and writex Subroutines
The readx and writex subroutines
provide additional parameters affecting the raw data transfer. These subroutines pass
the ext parameter, which specifies request options. The options are constructed
by logically ORing zero or more of the following values:
HWRELOC |
Indicates a request for hardware relocation (safe relocation only). |
UNSAFEREL |
Indicates a request for unsafe hardware relocation. |
WRITEV |
Indicates a request for write verification. |
Error Conditions
Possible errno values for ioctl,
open, read, and write subroutines when the SSA device driver is
used, include:
EBUSY |
Indicates one of the following circumstances:
- An attempt was made to open an SSA physical device
which is already opened by another process.
- The target device is reserved by another
initiator.
|
EFAULT |
Indicates an illegal user address. |
EINVAL |
Indicates one of the following circumstances:
- The read or write subroutine
supplied an nbyte parameter that is not an even multiple of the block size.
- The data buffer length exceeded the maximum defined in
the devinfo structure for an ioctl subroutine operation.
- The openext subroutine supplied an unsupported
combination of extension flags.
- An unsupported ioctl subroutine operation was
attempted.
- An attempt was made to configure a device that is
still open.
- An illegal configuration command has been given.
- The data buffer length exceeded the maximum defined
for a strategy operation.
|
EIO |
Indicates one of the following circumstances:
- The target device cannot be located or is not
responding.
- The target device has indicated an unrecovered
hardware error.
|
ESOFT |
Indicates that the target device has reported a recoverable media error. |
EMEDIA |
Indicates that the target device has encountered an unrecovered media
error. |
ENODEV |
Indicates one of the following circumstances:
- An attempt was made to access an undefined
device.
- An attempt was made to close an undefined device.
|
ENOTREADY |
Indicates that an attempt was made to open a SSA physical device in service
mode whilst a SSA logical device which uses it was in use. |
ENXIO |
Indicates one of the following circumstances:
- The ioctl subroutine supplied an invalid
parameter.
- The openext subroutine supplied extension flags
which selected a non-existent or non-functional adapter path.
- A read or write operation was attempted
beyond the end of the fixed disk drive.
|
EPERM |
Indicates the attempted subroutine requires appropriate authority. |
ENOCONNECT |
Indicates that the host has been fenced out from access to this device. |
ENOMEM |
Indicates that the system has insufficient real memory or insufficient paging
space to complete the operation. |
ENOLCK |
Indicates that an attempt was made to open a device in service mode which is
in an SSA network which is not a loop. |
Special Files
The ssadisk device driver uses raw and
block special files in performing its functions.
Attention: Data corruption, loss of
data, or loss of system integrity (system crash) will occur if devices supporting
paging, logical volumes, or mounted file systems are accessed using block special files.
Block special files are provided for logical volumes and disk devices and are solely for
system use in managing file systems, paging devices, and logical volumes. These files
should not be used for other purposes.
The special files used by the ssadisk device
driver include the following (listed by type of device):
- SSA logical disk drives:
/dev/hdisk0, /dev/hdisk1,..., /dev/hdiskn |
Provide an interface to allow SSA device drivers block I/O access to logical SSA
disk drives. |
/dev/rhdisk0,
/dev/rhdisk1,..., /dev/rhdiskn |
Provide an interface to allow SSA device drivers character access (raw I/O access
and control functions) to logical SSA disk drives. |
- SSA physical disk drives:
/dev/pdisk0, /dev/pdisk1,
..., /dev/pdiskn |
Provide an interface to allow SSA device drivers character access (control
functions only) to physical SSA disks drives. |
Note: The prefix r on a special
file name indicates the drive is accessed as a raw device rather than a block device.
Performing raw I/O with an SSA logical disk requires that all data transfers be in
multiples of the device block size. Also, all lseek subroutines that are made to
the raw device driver must result in a file pointer value that is a multiple of the
device block size.
Related Information
Special Files Overview in
AIX Version 4.3 Files Reference.
Understanding the Execution of
Initiator I/O Requests in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
SCSI Error Recovery in
AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
Understanding the sc_buf
Structure in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
The rmdev command. The mkdev command. The cfgmgr command. The chdev command. The lsdev command. The lsattr command.
The close subroutine, ioctl or ioctlx subroutine,
open, openx, or creat
subroutine, read, readx, readv, or
readvx subroutine,write,
writex, writev, or writevx subroutine.
The SSA
Adapter Device Driver, ssadisk SSA
Disk Device Driver, SSA Subsystem
Overview.
[ Previous |
Next |
Contents |
Home |
Search ]