register_HA_handler Kernel Service

Purpose

Registers a High Availability Event Handler with the Kernel.

Syntax

#include <sys/high_avail.h>

int register_HA_handler (ha_handler) ha_handler_ext_t * ha_handler;

Parameter

Item	Description
ha_handler	Specifies a pointer to a structure of the type ha_handler_ext_t as defined in /usr/include/sys/high_avail.h.

Description

The register_HA_handler kernel registers the High Availability Event Handler (HAEH) function to those kernel extensions that need to be made aware of high availability events such as processor deallocation. This function is called by the kernel, at base level, when a high availability event is initiated, due to some hardware fault.

The ha_handler_ext_t structure has 3 fields:

Field	Description
_fun	Contains a pointer to the high availability event handler function.
_data	Contains a user defined value which will be passed as an argument by the kernel when calling the function.
_name	Component name

When a high availability event is initiated, the kernel calls _fun() at base level (that is, process environment) with 2 parameters:

The first is the data the user passed in the _data field at registration time.
The second is a pointer to a haeh_event_t structure defined in /usr/include/sys/high_avail.h.

The fields of interest in this structure are:

Field	Description
_magic	Identifies the event type. The only possible value is HA_CPU_FAIL.
dealloc_cpu	The logical number of the CPU being deallocated.

The high availability even handler, in addition to user specific functions, must unbind its threads bound to dealloc_cpu and stop the timer request blocks (TRB) started by those bound threads when applicable.

The high availability event handler must return one of the following values:

Value	Description
HA_ACCEPTED	The user processing of the event has succeeded.
HA_REFUSED	The user processing of the event was not successful.

Any return value different from HA_ACCEPTED causes the kernel to abort the processing of the event. In the case of a processor failure, the processor deallocation is aborted. In this case, a CPU_DEALLOC_ABORTED error log entry is created, and the value passed in the _name field appears in the detailed data area of the error log entry.

An extension may register the same HAEH N times (N > 1). Although it is considered as an incorrect behaviour, no error is reported. The given HAEH is invoked N times for each HA event. This handler has to be unregistered as many times as it was registered.

Since the kernel calls the HAEH in turn, it is possible for a HAEH to be called multiple times for the same event. The kernel extensions should be ready to deal with this possibility. For example, two kernel extensions K1 and K2 have registered HA Handlers. A CPU deallocation is initiated. The HAEH for K1 gets invoked, does its job and returns HA_ACCEPTED. K2 gets invoked next and for some reason returns HA_REFUSED. The deallocation is aborted, and an error log entry reports K2 as the reason for failure. Later, the system administer unloads K2 and restarts the deallocation by manually running ha_star. The result is that the HAEH for K1 gets invoked again with the same parameters.

Execution Environment

The register_HA_handler kernel service can be called from the process environment only.

Return Values

Item	Description
0	Indicates a successful operation.

A non zero value indicates an error.