[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Kernel and Subsystems, Volume 2

ssadisk SSA Disk Device Driver

Purpose

Provides support for 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 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:

By default, all disk drives are configured as system disk drives. The array management software deletes hdisks to create arrays.

SSA physical disks have the following properties:

SSA logical disks have the following properties:

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 successfully 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.

Takeover 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 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 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:
    1. Enter lsdev -Ccpdisk -r connwhere.
    2. 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 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:
    1. Enter lsdev -Ccdisk -r connwhere and press Enter.
    2. 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 identifier, as follows:
    1. Type lsdev -Ccdisk -r connwhere and press Enter.
    2. Select the 15-character unique identifier 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

The open, read, write, and close subroutines start typical physical volume operations.

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.
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 5L Version 5.2 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):

Related Information

Special Files Overview in AIX 5L Version 5.2 Files Reference.

Understanding the Execution of Initiator I/O Requests in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

SCSI Error Recovery in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

Understanding the sc_buf Structure in AIX 5L Version 5.2 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.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]