HARDWARE DEPENDENT LIBRARY SYNOPSIS

The config_admin library is a generic interface that is used for dynamic
configuration, (DR). Each piece of hardware that supports DR must supply a
hardware-specific plugin library that contains the entry points listed in this subsection. The
generic library will locate and link to the appropriate library to effect
DR operations. The interfaces specified in this subsection are really “hidden” from
users of the generic libraries. It is, however, necessary that writers of
the hardware-specific plug in libraries know what these interfaces are.

Description

The config_*() functions provide a hardware independent interface to hardware-specific system configuration
administration functions. The cfga_*() functions are provided by hardware-specific libraries that
are dynamically loaded to handle configuration administration functions in a hardware-specific manner.

The libcfgadm library is used to provide the services of the cfgadm(1M)
command. The hardware-specific libraries are located in /usr/platform/${machine}/lib/cfgadm, /usr/platform/${arch}/lib/cfgadm, and /usr/lib/cfgadm. The
hardware-specific library names are derived from the driver name or from class
names in device tree nodes that identify attachment points.

The config_change_state() function performs operations that change the state of the system
configuration. The state_change_cmd argument can be one of the following: CFGA_CMD_INSERT, CFGA_CMD_REMOVE,
CFGA_CMD_DISCONNECT, CFGA_CMD_CONNECT, CFGA_CMD_CONFIGURE, or CFGA_CMD_UNCONFIGURE. The state_change_cmdCFGA_CMD_INSERT is used to prepare
for manual insertion or to activate automatic hardware insertion of an occupant. The
state_change_cmdCFGA_CMD_REMOVE is used to prepare for manual removal or activate automatic
hardware removal of an occupant. The state_change_cmdCFGA_CMD_DISCONNECT is used to disable
normal communication to or from an occupant in a receptacle. The state_change_cmdCFGA_CMD_CONNECT
is used to enable communication to or from an occupant in a
receptacle. The state_change_cmdCFGA_CMD_CONFIGURE is used to bring the hardware resources contained on,
or attached to, an occupant into the realm of Solaris, allowing use
of the occupant's hardware resources by the system. The state_change_cmdCFGA_CMD_UNCONFIGURE is
used to remove the hardware resources contained on, or attached to, an occupant
from the realm of Solaris, disallowing further use of the occupant's hardware
resources by the system.

The flags argument may contain one or both of the defined flags,
CFGA_FLAG_FORCE and CFGA_FLAG_VERBOSE. If the CFGA_FLAG_FORCE flag is asserted certain safety checks
will be overridden. For example, this may not allow an occupant in the
failed condition to be configured, but might allow an occupant in the
failing condition to be configured. Acceptance of a force is hardware
dependent. If the CFGA_FLAG_VERBOSE flag is asserted hardware-specific details relating to the
operation are output utilizing the cfga_msg mechanism.

The config_test() function is used to initiate testing of the specified attachment
point.

The num_ap_ids argument specifies the number of ap_ids in the ap_ids array.
The ap_ids argument points to an array of ap_ids.

The ap_id argument points to a single ap_id.

The function and options strings conform to the getsubopt(3C) syntax convention and
are used to supply hardware-specific function or option information. No generic hardware-independent functions
or options are defined.

The cfga_confirm structure referenced by confp provides a call-back interface to get
permission to proceed should the requested operation require, for example, a noticeable
service interruption. The cfga_confirm structure includes the following members:

The confirm() function is called with two arguments: the generic pointer appdata_ptr
and the message detailing what requires confirmation. The generic pointer appdata_ptr is
set to the value passed in in the cfga_confirm structure member appdata_ptr and
can be used in a graphical user interface to relate the confirm
function call to the config_*() call. The confirm() function should return
1 to allow the operation to proceed and 0 otherwise.

The cfga_msg structure referenced by msgp provides a call-back interface to output
messages from a hardware-specific library. In the presence of the CFGA_FLAG_VERBOSE flag,
these messages can be informational; otherwise they are restricted to error messages. The
cfga_msg structure includes the following members:

The message_routine() function is called with two arguments: the generic pointer appdata_ptr
and the message. The generic pointer appdata_ptr is set to the value
passed in in the cfga_confirm structure member appdata_ptr and can be used
in a graphical user interface to relate the message_routine() function call to
the config_*() call. The messages must be in the native language specified
by the LC_MESSAGES locale category; see setlocale(3C).

For some generic errors a hardware-specific error message can be returned. The
storage for the error message string, including the terminating null character, is
allocated by the config_* functions using malloc(3C) and a pointer to this
storage returned through errstring. If errstring is NULL no error message will
be generated or returned. If errstring is not NULL and no error
message is generated, the pointer referenced by errstring will be set to
NULL. It is the responsibility of the function calling config_*() to deallocate the
returned storage using free(3C). The error messages must be in the native
language specified by the LC_MESSAGES locale category; see setlocale(3C).

The config_list_ext() function provides the listing interface. When supplied with a list
of ap_ids through the first two arguments, it returns an array of
cfga_list_data_t structures for each attachment point specified. If the first two arguments are
0 and NULL respectively, then all attachment points in the device tree
will be listed. Additionally, dynamic expansion of an attachment point to list
dynamic attachment points may also be requested by passing the CFGA_FLAG_LIST_ALL flag through
the flags argument. Storage for the returned array of stat structures is
allocated by the config_list_ext() function using malloc(3C). This storage must be freed
by the caller of config_list_ext() by using free(3C).

The listopts argument to config_list_ext() conforms to the getsubopt(3C) syntax and
is used to pass listing sub-options. Currently, only the sub-option class=class_name is supported.
This list option restricts the listing to attachment points of class
class_name.

The listopts argument to cfga_list_ext() is reserved for future use. Hardware-specific
libraries should ignore this argument if it is NULL. If listopts is
not NULL and is not supported by the hardware-specific library, an appropriate error
code should be returned.

The ap_log_id and the ap_phys_id members give the hardware-specific logical and physical
names of the attachment point. The ap_busy memberd indicates activity is present
that may result in changes to state or condition. The ap_status_time
member provides the time at which either the ap_r_state, ap_o_state, or ap_cond
field of the attachment point last changed. The ap_info member is available
for the hardware-specific code to provide additional information about the attachment point. The
ap_class member contains the attachment point class (if any) for an attachment
point. The ap_class member is filled in by the generic library.
If the ap_log_id and ap_phys_id members are not filled in by the hardware-specific
library, the generic library will fill in these members using a generic
format. The remaining members are the responsibility of the corresponding hardware-tospecific library.

All string members in the cfga_list_data structure are null-terminated.

The config_stat(), config_list(), cfga_stat(), and cfga_list() functions and the cfga_stat_data data structure
are deprecated interfaces and are provided solely for backward compatibility. Use of
these interfaces is strongly discouraged.

The config_ap_id_cmp function performs a hardware dependent comparison on two ap_ids,
returning an equal to, less than or greater than indication in the
manner of strcmp(3C). Each argument is either a cfga_ap_id_t or can be
a null-terminated string. This function can be used when sorting lists of
ap_ids, for example with qsort(3C), or when selecting entries from the result
of a config_list function call.

The config_strerror function can be used to map an error return value
to an error message string. See RETURN VALUES. The returned string should not
be overwritten. config_strerror returns NULL if cfgerrnum is out-of-range.

The cfga_help function can be used request that a hardware-specific library output
it's localized help message.

Return Values

The config_*() and cfga_*() functions return the following values. Additional error information
may be returned through errstring if the return code is not CFGA_OK.
See DESCRIPTION for details.

CFGA_BUSY

The command was not completed due to an element of the system configuration administration system being busy.

CFGA_ATTR_INVAL

No attachment points with the specified attributes exists

CFGA_ERROR

An error occurred during the processing of the requested operation. This error code includes validation of the command arguments by the hardware-specific code.

CFGA_INSUFFICIENT_CONDITION

Operation failed due to attachment point condition.

CFGA_INVAL

The system configuration administration operation requested is not supported on the specified attachment point.

CFGA_LIB_ERROR

A procedural error occurred in the library, including failure to obtain process resources such as memory and file descriptors.

CFGA_NACK

The command was not completed due to a negative acknowledgement from the confp->confirm function.

CFGA_NO_LIB

A hardware-specific library could not be located using the supplied ap_id.

CFGA_NOTSUPP

System configuration administration is not supported on the specified attachment point.

CFGA_OK

The command completed as requested.

CFGA_OPNOTSUPP

System configuration administration operation is not supported on this attachment point.

CFGA_PRIV

The caller does not have the required process privileges. For example, if configuration administration is performed through a device driver, the permissions on the device node would be used to control access.

CFGA_SYSTEM_BUSY

The command required a service interruption and was not completed due to a part of the system that could not be quiesced.

Errors

Many of the errors returned by the system configuration administration functions are
hardware-specific. The strings returned in errstring may include the following:

attachment pointap_idnot known

The attachment point detailed in the error message does not exist.

unknown hardware optionoptionforoperation

An unknown option was encountered in the options string.

hardware optionoptionrequires a value

An option in the options string should have been of the form option=value.

listing optionlist_optionrequires a value

An option in the listopts string should have been of the form option=value.

hardware optionoptiondoes not require a value

An option in the options string should have been a simple option.

attachment pointap_idis not configured

A config_change_state command to CFGA_CMD_UNCONFIGURE an occupant was made to an attachment point whose occupant was not in the CFGA_STAT_CONFIGURED state.

attachment pointap_idis not unconfigured

A config_change_state command requiring an unconfigured occupant was made to an attachment point whose occupant was not in the CFGA_STAT_UNCONFIGURED state.

attachment pointap_idcondition not satisfactory

A config_change_state command was made to an attachment point whose condition prevented the operation.

attachment pointap_idin conditionconditioncannot be used

A config_change_state operation with force indicated was directed to an attachment point whose condition fails the hardware dependent test.

See Also

Notes

Applications using this library should be aware that the underlying implementation may
use system services which alter the contents of the external variable errno
and may use file descriptor resources.

The following code shows the intended error processing when config_*() returns a
value other than CFGA_OK: