pio_assist Kernel Service

Purpose

Provides a standardized programmed I/O exception handling mechanism for all routines performing programmed I/O.

Syntax

#include <sys/types.h>
#include <sys/errno.h>

Parameters

Description

The pio_assist kernel service assists in handling exceptions caused by programmed I/O. Use of the pio_assist service standardizes the programmed I/O exception handling for all routines performing programmed I/O. The pio_assist service is built upon other kernel services that routines access to provide their own exception handling if the pio_assist service should not be used.

Using the pio_assist Kernel Service

To use the pio_assist service, the device handler writer must provide a callable routine that performs the I/O operation. The device handler writer can also optionally provide a routine that can recover and log I/O errors. The mainline device handler code would then call the pio_assist service with the following parameters:

• A pointer to the parameters needed by the I/O routine
• The function pointer for the routine performing I/O
• A pointer for the I/O recovery routine (or a null pointer, if there is no I/O recovery routine)

If the pointer for the I/O recovery routine is a null character, the iofunc routine is recalled to recover from I/O exceptions. The I/O routine for error retry should only be re-used if the I/O routine can handle being recalled when an error occurs, and if the sequence of I/O instructions can be reissued to recover from typical bus errors.

The ioparms parameter points to the parameters needed by the I/O routine. It is passed to the I/O routine when the pio_assist service calls the I/O routine. It is also passed to the I/O recovery routine when the I/O recovery routine is invoked by the pio_assist service. If any of the parameters found in the structure pointed to by the ioparms parameter are modified by the iofunc routine and needed by the iorecov or recalled iofunc routine, they must be declared as volatile.

Requirements for Coding the Caller-Provided I/O Routine

The iofunc parameter is a function pointer to the routine performing the actual I/O. It is called by the pio_assist service with the following parameters:

int iofunc (ioparms)
caddr_t ioparms;             /* pointer to parameters */

The ioparms parameter points to the parameters used by the I/O routine that was provided on the call to the pio_assist kernel service.

If the pio_assist kernel service is used with a null pointer to the iorecov I/O recovery routine, the iofunc I/O routine is called to retry all programmed I/O exceptions. This is useful for devices that have I/O operations that can be re-sent without concern for hardware state synchronization problems.

Upon return from the I/O, the return code should be 0 if no error was encountered by the I/O routine itself. If a nonzero return code is presented, it is used as the return code from the pio_assist kernel service.

Requirements for Coding the Caller-Provided I/O Recovery Routine

The iorecov parameter is a function pointer to the device handler's I/O recovery routine. This iorecov routine is responsible for logging error information, if required, and performing the necessary recovery operations to complete the I/O, if possible. This may in fact include calling the original I/O routine. The iorecov routine is called with the following parameters when an exception is detected during execution of the I/O routine:

int iorecov (parms, action, infop)
caddr_t parms;/* pointer to parameters passed to iofunc*/
int action;            /* action indicator */
struct pio_except *infop;        /* pointer to exception info */

The parms parameter points to the parameters used by the I/O routine that were provided on the call to the pio_assist service.

The action parameter is an operation code set by the pio_assist kernel service to one of the following:

The pio_except structure containing the exception information is platform-specific and defined in the /usr/include/sys/except.h file. The fields in this structure define the type of error that occurred, the bus address on which the error occurred, and additional platform-specific information to assist in the handling of the exception.

The iorecov routine should return with a return code of 0 if the exception is a type that the routine can handle. A EXCEPT_NOT_HANDLED return code signals that the exception is a type not handled by the iorecov routine. This return code causes the pio_assist kernel service to invoke the next exception handler on the stack of exception handlers. Any other nonzero return code signals that the iorecov routine handled the exception but could not successfully recover the I/O. This error code is returned as the return code from the pio_assist kernel service.

Return Codes by the pio_assist Kernel Service

The pio_assist kernel service returns a return code of 0 if the iofunc I/O routine does not indicate any errors, or if programmed I/O exceptions did occur but were successfully handled by the iorecov I/O recovery routine. If an I/O exception occurs during execution of the iofunc or iorecov routines and the exception count has not exceeded the maximum value, the iorecov routine is called with an op value of PIO_RETRY.

If the number of exceptions that occurred during this operation exceeds the maximum number of retries set by the platform-specific value of PIO_RETRY_COUNT, the pio_assist kernel service calls the iorecov routine with an op value of PIO_NO_RETRY. This indicates that the I/O operation should not be retried. In this case, the pio_assist service returns a return code value of EIO indicating failure of the I/O operation.

If the exception is not an I/O-related exception or if the iorecov routine returns with the return code of EXCEPT_NOT_HANDLED (indicating that it could not handle the exception), the pio_assist kernel service does not return to the caller. Instead, it invokes the next exception handler on the stack of exception handlers for the current process or interrupt handler. If no other exception handlers are on the stack, the default exception handler is invoked. The normal action of the default exception handler is to cause a system crash.

Execution Environment

The pio_assist kernel service can be called from either the process or interrupt environment.

Return Values