ras_register and ras_unregister Exported Kernel Services

Edit online

Purpose

Registers and unregisters a RAS component.

Syntax

#include <sys/ras.h>
kerrno_t ras_register (
ras_block_t * rasbp,
char * name,
ras_block_t parent,
ras_type_t typesubtype,
char * desc,
long flags,
ras_callback_t ras_callback,
void * private_data);

kerrno_t ras_unregister (ras_block_t ras_blk);

Description

The ras_register kernel service and the ras_unregister kernel service register and unregister RAS handlers which are invoked by the kernel when the system needs to communicate various RAS commands to each component.

The ras_register kernel service registers a component with the given name under the parent provided. If the parent is NULL, the ras_register kernel service registers name as a base component, but the typesubtype parameter must be provided. The name parameter specifies the name for the subcomponent or base component (it is not a full component path). The flags field is used to specify what aspects of RAS the component understands. The ras_callback is the mechanism by which the RAS subsystem communicates various commands to the component, depending on what aspects of RAS the component understands. The desc parameter provides a short description for the component as a service aid.

The ras_register kernel service allocates a ras_block_t member and returns the control block for the component through the rasbp argument. This control block can be used in ras_control calls and further ras_register calls (to allocate children, for instance).

If the registration fails due to the system being out of memory, the value of the rasbp argument is set to RAS_BLOCK_NULL. All RAS functions for this component are disabled. RAS kernel services accept RAS_BLOCK_NULL control blocks but take no action. If the control block is set to RAS_BLOCK_NULLRAS, domain related functions (such as the CT_HOOKx and CT_GEN macros) run correctly but take no action. This action allows the ENOMEM type failures from the ras_register kernel service to be safely ignored. The value of the rasbp argument for all other types of errors is undefined.

The ras_unregister kernel service unregisters a component previously registered with the ras_register kernel service. The ras_blk parameter should have no further children.

Parameters

Item Description
rasbp The newly allocated ras_block_t member.
name The name of the component, not its full pathname. Individual node names are limited to the number of characters specified by the value of the RAS_NAME_MAX parameter (including the terminating NULL character). The full component path (the concatenated names of a child component and all of its ancestors) is limited to the number of characters specified by the value of the RAS_PATH_MAX parameter (including the terminating NULL character). The ras_register kernel service reconstructs the full component path and rejects registrations for components whose full path exceeds the value of the RAS_PATH_MAX parameter. Node names are restricted to the character set “A-Z”,”a-z”,”0-9” and “_”.
parent An optional pointer to the parent component or NULL if none.
typesubtype If parent is NULL, mandatory parameter is used to categorize the component. The top 16-bits of the lower word of this field are the type, and the bottom 16-bits are the subtype. The typesubtype is a ras_type_t member, which is an enum. See the sys/ras_base.h file for a description of the types available. If parent is non-NULL, this parameter is required to be the value of the RAS_TYPE_CHILD parameter.
desc A short description string for the component. The desc string is limited to the number of characters specified by the value of the RAS_DESC_MAX parameter (including the terminating null). The desc string has no character set restriction. Any static elements of the string should be in U.S. English, but dynamic elements have no restriction.
flags Indicates what type of RAS systems this component is aware of. Valid choices are the following:
  • RASF_TRACE_AWARE: Component is Component Trace aware.
  • RASF_ERROR_AWARE: Component is Error Checking aware.
These flags are defined in the sys/ras.h file.
ras_callback A function pointer provided by the registrant and called by the framework each time an external event modifies a property of the component. See the ras_callback interface specification.
private_data An optional pointer to a component private memory area passed to the ras_callback function upon callback.
ras_blk The control block to remove.

Execution Environment

Both the ras_register kernel service and the ras_unregister kernel service must be called from the process environment.

Return Values

The following are the return values of the ras_register kernel service.

Item Description
0 Successful.
non-zero Unsuccessful.

The following are the return values of the ras_unregister kernel service.

Item Description
0 Successful.
non-zero Unsuccessful.