Technical Reference: Kernel and Subsystems, Volume 1

eeh_init_multifunc Kernel Service

Purpose

This kernel service registers a multifunction adapter slot on a PCI bus for EEH function.

Syntax

#include <sys/eeh.h>

eeh_handle_t eeh_init_multifunc(pbid, gpbid, slot, flag, delay_seconds, 
                                callback_ptr, dds_ptr)
long pbid;
long gpbid;
long slot;
long flag;
long delay_seconds;
long (*callback_ptr)();
void *dds_ptr;

Parameters

Description

This kernel service is provided for systems that support multifunction adapters. It is also recommended that single function adapters use the multifunction model. The multifunction adapters can reside in one physical slot but have multiple independent instances of device drivers running for each function. Therefore, when recovering a slot from an EEH event, there is a need to coordinate the recovery procedure among them. So this service should only be called by drivers that use the multifunction model. As with eeh_init(), this service also returns an eeh_handle to the calling device driver.

There are two kinds of multifunction adapters: bridged and non-bridged. A bridged adapter has a bridge on the card such as PCI-to-PCI or PCIX-to-PCIX. For bridged-adapters, pbid is the bus ID of the parent bus, and gpbid is the bus ID of the grandparent bus. The parent bus for a bridged adapter is the bus generated by the bridge on the adapter. A bid identifies a bus number and type. The bus type is IO_PCI in the case of PCI and PCI-X bus. The bus number is a unique identifier determined during bus configuration. The BID_VAL macro defined in ioacc.h is used to generate the bid. For non-bridged adapters, pbid and gpbid are the same and are the bus IDs of the parent bus. Thus, when pbid and gpbid have different values, the kernel knows that this is a bridged adapter and has a dependency on the platform firmware with respect to EEH.

The slot argument is the device/function combination ((device* 8) + function) as in the PCI addressing scheme. This is the same as the connwhere ODM value.

The slot is always enabled for EEH when this service is called by the first driver on that slot. All subsequent requests to enable the slot via the EEH_ENABLE flag are ignored. Therefore, the flag argument of EEH_ENABLE is optional, and a flag of EEH_DISABLE is ignored. The flag argument of EEH_CHECK_SLOT verifies whether a given slot is already registered. A value of either EEH_SLOT_ACTIVE or EEH_SLOT_FREE is returned. No registration will occur with the EEH_CHECK_SLOT flag, and it supersedes all other flags. This flag just checks the slot and returns without any other action. If the flag is set to EEH_ENABLE_NO_SUPPORT_RC, eeh_enable_pio() and eeh_enable_dma() returns EEH_NO_SUPPORT under certain conditions. See eeh_enable_pio() and eeh_enable_dma() for more information. It is allowed to logically OR multiple flags together.

The delay_seconds argument allows the device driver to set a time delay between completion of PCI reset and configuration of the bridge on the adapter. The delay is enforced even if the adapter is non-bridged. If a value of 0 is specified for delay_seconds, a default delay time of 1 second is set. When several drivers register on the same pbid, the highest delay time among all registered drivers is used.

The callback_ptr argument is a function pointer to an EEH callback routine. The handler is defined by the device driver and is called by the kernel in order to coordinate recovery among different drivers on the same slot. The driver handles a variety of messages from the kernel in its callback routine. These messages trigger the next step in recovery. The callback routines are called sequentially at INTIODONE interrupt level.

The dds_ptr argument is a cookie that is passed to the driver when the callback routine is invoked. Drivers normally specify a pointer to the device driver's adapter structure.

EEH_SAFE mode: A bridged adapter needs to have its bridge reconfigured at the end of PCI reset. However, if the platform firmware does not support reconfiguration of the bridge, the adapter is marked as EEH_SAFE by the kernel. An EEH_SAFE adapter cannot finish error recovery after an EEH event because of the unsatisfied firmware dependency. See eeh_reset_slot for information on how the error recovery is handled in EEH_SAFE mode.

The macro EEH_INIT_MULTIFUNC(bid, bid2, slot, flag, delay_seconds, callback_ptr, dds_ptr) is provided for the device drivers in order to call this service. This is an exported kernel service.

Execution Environment

This kernel service can only be called from the process environment.

Return Values

Related Information

eeh_broadcast Kernel Service, eeh_clear Kernel Service, eeh_disable_slot Kernel Service, eeh_enable_dma Kernel Service, eeh_enable_pio Kernel Service, eeh_enable_slot Kernel Service, eeh_init Kernel Service, eeh_read_slot_state Kernel Service, eeh_reset_slot Kernel Service, eeh_slot_error Kernel Service