[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 2

SCIODNLD (Download) SCSI Adapter Device Driver ioctl Operation

Purpose

Provides the means to download microcode to the adapter.

Description

The SCIODNLD operation provides for downloading microcode to the selected adapter. This operation can be used by system management routines to prepare the adapter for operation. The adapter can be opened in Normal or Diagnostic mode when the SCIODNLD operation is run.

There are two options for executing the SCIODNLD operation. The caller can either download microcode to the adapter or query the version of the currently downloaded microcode.

If the download microcode option is selected, a pointer to a download buffer and its length must be supplied in the caller's memory space. The maximum length of this microcode is adapter-dependent. If the adapter requires transfer of complete blocks, the microcode to be sent must be padded to the next largest block boundary. The block size, if any, is adapter-dependent. Refer to the reference manual for the particular SCSI adapter to find the adapter-specific requirements of the microcode buffer to be downloaded.

The SCSI adapter device driver validates the parameter values for such things as maximum length and block boundaries, as required. The arg parameter for the SCIODNLD operation specifies the address of a sc_download structure. This structure is defined in the /usr/include/sys/scsi.h file.

If the query version option is selected, the pointer and length fields in the passed parameter block are ignored. On successful completion of the SCIODNLD operation, the microcode version is contained in the version_number field.

The SCSI adapter device driver performs normal error-recovery procedures during execution of the SCIODNLD operation.

Return Values

When completed successfully, this operation returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to one of the following values:

EFAULT Indicates that a severe I/O error has occurred, preventing completion of the download. In this case, further operations are not possible on the card, and the caller should discontinue commands to the card. The adapter error-status information is logged in the system error log.
EFAULT Indicates that a bad copy between kernel and user space occurred.
EINVAL Indicates that the adapter device driver was unable to run the command due to incorrect input parameters. Check microcode length and block boundary for errors.
EIO Indicates that the adapter device driver was unable to complete the command due to an unrecoverable I/O error or microcode cyclical redundancy check (CRC) error. If the card has on-board microcode, it may be able to continue running, and further commands may still be possible on this adapter. The adapter error-status information is logged in the system error log.
ENOMEM Indicates insufficient memory is available to complete the command.
ENXIO Indicates that the operation or suboption selected is not supported on this adapter and should not be treated as an error. The caller must check for this return value first (before checking for other errno values) to avoid mistaking this for a failing command.
ETIMEDOUT Indicates that the adapter did not respond with status before the passed command time-out value expired. Since the download operation may not have completed, further operations on the card may not be possible. The caller should discontinue sending commands to the card. This error is also logged in the system error log.

Files

/dev/scsi0, /dev/scsi1,..., /dev/scsin
                          Provide an interface to allow SCSI device drivers to access SCSI devices and adapters.

Related Information

The rmt SCSI device driver, scdisk SCSI device driver, SCSI Adapter device driver.

SCSI Subsystem Overview in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]