Provides support for Serial Storage Architecture (SSA) disk drives.
#include <sys/devinfo.h>
#include <sys/ssa.h>
#include <sys/ssadisk.h>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.
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:
| Item | Description |
|---|---|
| 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:
|
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:
| Item | Description |
|---|---|
| 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 logical disk is an array, you can determine the unique identifier in two ways:
|
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.
| Item | Description |
|---|---|
| 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.
| Item | Description |
|---|---|
| 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
| Item | Description |
|---|---|
| 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. |
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:
| Item | Description |
|---|---|
| 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® Version 7.1 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:
| Item | Description |
|---|---|
| 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. |
Possible errno values for ioctl, open, read, and write subroutines when the SSA device driver is used, include:
| Item | Description |
|---|---|
| EBUSY | Indicates one of the following circumstances:
|
| EFAULT | Indicates an illegal user address. |
| EINVAL | Indicates one of the following circumstances:
|
| EIO | Indicates one of the following circumstances:
|
| 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:
|
| 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:
|
| 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. |
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):
| Item | Description |
|---|---|
| /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. |
| Item | Description |
|---|---|
| /dev/pdisk0, /dev/pdisk1, ..., /dev/pdiskn | Provide an interface to allow SSA device drivers character access (control functions only) to physical SSA disks drives. |