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_cmd CFGA_CMD_INSERT is used to prepare for manual insertion or to activate automatic hardware insertion of an occupant. The state_change_cmd CFGA_CMD_REMOVE is used to prepare for manual
removal or activate automatic hardware removal of an occupant. The state_change_cmd CFGA_CMD_DISCONNECT is used to disable normal communication to or from an occupant in a receptacle. The state_change_cmd CFGA_CMD_CONNECT is used to enable communication to or from an occupant in a receptacle. The state_change_cmd CFGA_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_cmd CFGA_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_private_func() function invokes private hardware-specific functions.
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:
|
int (*confirm)(void *appdata_ptr, const char *message);
void *appdata_ptr;
|
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:
|
void (*message_routine)(void *appdata_ptr, const char *message);
void *appdata_ptr;
|
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 cfga_list_data structure includes the following members:
|
cfga_log_ext_t ap_log_id; /* Attachment point logical id */
cfga_phys_ext_t ap_phys_id; /* Attachment point physical id */
cfga_class_t ap_class; /* Attachment point class */
cfga_stat_t ap_r_state; /* Receptacle state */
cfga_stat_t ap_o_state; /* Occupant state */
cfga_cond_t ap_cond; /* Attachment point condition */
cfga_busy_t ap_busy; /* Busy indicator */
time_t ap_status_time; /* Attachment point last change*/
cfga_info_t ap_info; /* Miscellaneous information */
cfga_type_t ap_type; /* Occupant type */
|
The types are defined as follows:
|
typedef char cfga_log_ext_t[CFGA_LOG_EXT_LEN];
typedef char cfga_phys_ext_t[CFGA_PHYS_EXT_LEN];
typedef char cfga_class_t[CFGA_CLASS_LEN];
typedef char cfga_info_t[CFGA_INFO_LEN];
typedef char cfga_type_t[CFGA_TYPE_LEN];
typedef enum cfga_cond_t;
typedef enum cfga_stat_t;
typedef enum cfga_busy_t;
typedef int cfga_flags_t;
|
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.
The ap_log_id, ap_phys_id, ap_info, ap_class, and ap_type members are fixed-length strings. If the actual string is shorter than the size of the member, it will be null-terminated. Because of this, programs
should not rely on there being a terminating null character. When printing these fields, the following format is suggested:
|
printf("%.*s", sizeof(p->ap_log_id), p->ap_log_id);
|
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_unload_libs function unlinks all previously loaded hardware-specific libraries.
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.
|