SSA Adapter Device Driver

Purpose

Supports the SSA adapter.

Syntax

#include </usr/include/sys/ssa.h> #include </usr/include/sys/devinfo.h>

Description

The /dev/ssan special files provide an interface that allows client application programs to access SSA adapters and the SSA devices that are connected to those adapters. Multiple-head device drivers and application programs can all access a particular SSA adapter and its connected devices at the same time.

Configuring Devices

All the SSA adapters that are connected to the using system are normally configured automatically during the system boot sequence.

SSA Adapter ODM Attributes

Note: A Micro Channel Machine can only run AIX® 5.1 or earlier.

The SSA Micro Channel adapter has a number of object data manager (ODM) attributes that you can display by using the lsattr command:

Item Description
ucode Holds the file name of the microcode package file that supplies the adapter microcode that is present in an SSA adapter.
bus_intr_level Holds the value of the bus interrupt level that the SSA adapter device driver for this adapter will use.
dma_lvl Holds the value of the DMA arbitration level that the SSA adapter device driver for this adapter will use.
bus_io_addr Holds the value of the bus I/O base address of the adapter registers that the SSA adapter device driver for this adapter will use.
dma_bus_mem Holds the value of the bus I/O base address of the adapter's DMA address that the SSA adapter device driver for this adapter will use.
dbmw Holds the size of the DMA area that the SSA adapter device driver for this adapter will use. You can use the chdev command to change the value of this attribute. The default value provides a DMA area that is large enough to allow the adapter to perform efficiently, yet allows other adapters to be configured.
  The default value is practical for normal use. If, however, a particular SSA device that is attached to the using system needs large quantities of outstanding I/O to get best performance, a larger DMA area might improve the performance of the adapter.
bus_mem_start Holds the value of the bus-memory start address that the SSA adapter device driver for this adapter will use.
intr_priority Holds the value of the interrupt priority that the SSA adapter device driver for this adapter will use.
daemon Specifies whether to start the SSA adapter daemon. If the attribute is set to TRUE, the daemon is started when the adapter is configured.
  The daemon holds the adapter device driver open although the operating system might not be using that adapter device driver at the time. This action allows the adapter device driver to reset the adapter card if the software that is running on it finds an unrecoverable problem. It also allows the adapter device driver to log errors against the adapter.
  The ability of the device driver to log errors against the adapter is especially useful if the adapter is in an SSA loop that is used by another adapter, because failure of this adapter can affect the availability of the SSA loop to the other adapter.
  You can use the chdev command to change the value of this attribute.
host_address This attribute may be used to specify the TCPIP address used by the SSA network agent on remote hosts to contact this host. If set, the value is passed to remote hosts via the SSA network. If this attribute is not set then the value returned by the "hostname" command is passed to remote hosts.

This may be useful on systems which have more than one tcpip address and where the specific TPCIP address used by the SSA network agent is important.

This attribute is only functional for the PCI SSA Multi-Initiator/RAID EL Adapter and the Micro Channel SSA Multi-Initiator/RAID EL Adapter.

PCI SSA Adapter ODM Attributes

The PCI SSA adapter has a number of object data manager (ODM) attributes that you can display by using the lsattr command:

Item Description
ucode Holds the file name of the microcode package file that supplies the adapter microcode that is present in an SSA adapter.
bus_intr_level Holds the value of the bus interrupt level that the SSA adapter device driver for this adapter will use.
bus_io_addr Holds the value of the bus I/O base address of the adapter registers that the SSA adapter device driver for this adapter will use.
bus_mem_start Holds the value of the bus-memory start address that the SSA adapter device driver for this adapter will use.
bus_mem_start2 Holds the value of the bus-memory start address that the SSA adapter device driver for this adapter will use.
intr_priority Holds the value of the interrupt priority that the SSA adapter device driver for this adapter will use.
daemon Specifies whether to start the SSA adapter daemon. If the attribute is set to TRUE, the daemon is started when the adapter is configured.
  The daemon holds the adapter device driver open although the operating system might not be using that adapter device driver at the time. This action allows the adapter device driver to reset the adapter card if the software that is running on it finds an unrecoverable problem. It also allows the adapter device driver to log errors against the adapter.
  The ability of the device driver to log errors against the adapter is especially useful if the adapter is in an SSA loop that is used by another adapter, because failure of this adapter can affect the availability of the SSA loop to the other adapter.
  You can use the chdev command to change the value of this attribute.

Device-Dependent Subroutines

The SSA adapter device driver provides support only for the open, close, and ioctl subroutines. It does not provide support for the read and write subroutines.

open and close Subroutines

The open and openx subroutines must be called by any application program that wants to send ioctl calls to the device driver.

You can use the open or the openx subroutine call to open the SSA adapter device driver. If you use the openx subroutine call, set the ext parameter to 0, because the call does not use it.

Summary of SSA Error Conditions

If an open or ioctl subroutine that has been issued to an SSA adapter fails, the subroutine returns -1, and the global variable errno is set to a value from the file /usr/include/sys/errno.h.

Possible errno values for the SSA adapter device driver are:

Item Description
EINVAL An unknown ioctl was attempted or the parameters supplied were not valid.
EIO An I/O error occurred.
ENOMEM The command could not be completed because not enough real memory or paging space was available.
ENXIO The requested device does not exist.

Managing Dumps

The SSA adapter device driver is a target for the system dump facility.

The DUMPQUERY option returns a minimum transfer size of 0 bytes and a maximum transfer size that is appropriate for the SSA adapter.

To be processed, calls to the SSA adapter device driver DUMPWRITE option should use the arg parameter as a pointer to the SSA_Ioreq_t structure, which is defined in /usr/include/sys/ssa.h. Using this interface, commands for which the adapter provides support can be run on a previously started (opened) target device. The SSA adapter device driver ignores the uiop parameter.

Note: Only the SsaMCB.MCB_Result field of the SSA_Ioreq_t structure is set at completion of the DUMPWRITE. During the dump, no support is provided for error logging.

If the dddump entry point completes successfully, it returns a 0. If the entry point does not complete successfully, it returns one of the following:

Item Description
EINVAL A request that is not valid was sent to the adapter device driver; for example, a request for the DUMPSTART option was sent before a DUMPINIT option had been run successfully
EIO The adapter device driver was unable to complete the command because the required resources were not available, or because an I/O error had occurred.
ETIMEDOUT The adapter did not respond with status before the passed command time-out value expired.

Files

Item Description
/dev/ssa0, /dev/ssa1,..., /dev/ssan Provide an interface to allow SSA head device drivers to access SSA devices or adapters.