rcfgadm(1M) provides remote configuration administration operations on dynamically reconfigurable hardware resources. The rcfgadm command allows configuration administration operations on the specified domain from the system controller. These operations include displaying status (-l), initiating testing (-t), invoking configuration state changes (-c), invoking hardware specific functions (-x), and obtaining configuration administration help messages (-h).
rcfgadm performs configuration administration at attachment points, which are places where system software supports dynamic reconfiguration of hardware resources during continued operation of Solaris software.
Configuration administration distinguishes between hardware resources that are physically present in the machine and hardware resources that are configured and visible to the Solaris environment. The nature of configuration administration functions are hardware-specific and rcfgadm performs configuration by calling hardware-specific libraries.
Configuration administration operates on an attachment point. Hardware resources located at attachment points might or might not be physically replaceable during system operation but are dynamically reconfigurable by way of the configuration administration interfaces.
An attachment point defines two unique elements, which are distinct from the hardware resources that exist beyond the attachment point. The two elements of an attachment point are a receptacle and an occupant. Physical insertion or removal of hardware resources occurs at an attachment point and results in a receptacle gaining or losing an occupant. Configuration administration supports the physical insertion and removal operations, as well as other configuration administration functions at an attachment point.
Attachment points have associated state and condition information. The configuration administration interfaces provide control for transitioning attachment point states. A receptacle can exist in one of three states: empty, disconnected, or connected. An occupant can exist in one of two states: configured or unconfigured.
A receptacle can provide the empty state, which is the normal state of a receptacle when the attachment point has no occupants. A receptacle can also provide the disconnected state if it has the capability of isolating its occupants from normal system access. Typically this state is used for various hardware-specific testing prior to bringing the occupant's resources into full use by the system, or as a step in preparing an occupant for physical removal or reconfiguration. A receptacle in the disconnected state isolates its occupant from the system as much as its hardware allows, but can provide access for testing and setup. A receptacle must provide the connected state, which allows normal access to hardware resources contained on any occupants. The connected state is the normal state of a receptacle that contains an occupant and that is not currently undergoing configuration administration
operations.
The hardware resources contained on an occupant in the unconfigured state are not represented by normal Solaris software data structures and are thus not available for use by the Solaris operating environment. Operations allowed on an unconfigured occupant are limited to configuration administration operations. The hardware resources of an occupant in the configured state are represented by normal Solaris software data structures, and thus some or all of those hardware resources can be in use by the Solaris operating environment. All occupants provide both the configured and unconfigured states.
An attachment point can be in one of five conditions: unknown, ok, failing, failed, or unusable. An attachment point can enter the system in any condition, depending upon results of power-on tests and nonvolatile record keeping.
An attachment point with an occupant in the configured state is in one of four conditions: unknown, ok, failing, or failed. If the condition is not failing or failed, an attachment point can change to failing during the course of operation if a hardware-dependent recoverable error threshold is exceeded. If the condition is not failed, an attachment point can change to failed during operation as a result of an unrecoverable error.
An attachment point with an occupant in the unconfigured state can be in any of the defined conditions. The condition of an attachment point with an unconfigured occupant can decay from ok to unknown after a system-dependent time threshold. Initiating a test function changes the attachment point condition to ok, failing, or failed, depending on the outcome of the test. An attachment point that does not provide a test function can leave the attachment point in the unknown condition. If a test is interrupted, the attachment point condition can be set to the previous condition, to unknown, or to failed. An attachment point in the unknown, ok, failing, or failed conditions can be retested.
An attachment point can exist in the unusable condition for a variety of reasons, such as inadequate power or cooling for the receptacle, an occupant that is unidentifiable, unsupported, incorrectly configured, and so on. An attachment point in the unusable condition can never be used by the system. It typically remains in this condition until the physical cause is remedied.
An attachment point also maintains busy information that indicates when a state change is in progress or the condition is being reevaluated.
Designate attachment points using hardware-specific identifiers (ap_ids) that are related to the type and location of the attachment points in the system device hierarchy. An ap_id cannot be ambiguous; it must identify a single attachment point. Two types of ap_id specifications are supported: physical and logical.
A physical ap_id contains a fully specified path name, while a logical ap_id contains a shorthand notation that identifies an attachment point in a more user-friendly way.
For example, an attachment point representing system board 6 would have a physical ap_id of /devices/pseudo/dr@0:SB6, while the logical ap_id would be SB6.
Attachment points can also be created dynamically. A dynamic attachment point is named relative to a base attachment point that is present in the system. ap_ids for dynamic attachment points consist of a base component followed by two colons (::) and a dynamic component. The base component is the base attachment point ap_id. The dynamic component is hardware-specific and is generated by the corresponding hardware-specific library.
For example, consider a base attachment point, which represents a system board, with the physical ap_id /devices/pseudo/dr@0:SB16 and logical ap_id SB16.
A CPU attached to this system board could be represented by a dynamic attachment point with logical ap_id SB16::cpu2, where SB16 is the base component and cpu2 is the hardware-specific dynamic component. Similarly, the physical ap_id for this dynamic attachment point would be:
/devices/pseudo/dr@0:SB16::cpu2.
An ap_type is a partial form of a logical ap_id that can be ambiguous and not specify a particular attachment point. An ap_type is a substring of the portion of the logical ap_id, up to but not including, the colon (:) separator. For example, an ap_type of pci would show all attachment points whose logical ap_ids begin with pci.
The use of ap_types is discouraged. The new select suboption to the -s option provides a more general and flexible mechanism for selecting attachment points. See OPTIONS.
rcfgadm interacts primarily with hardware-dependent functions contained in hardware-specific libraries, and thus its behavior is hardware-dependent.
For each configuration administration operation, a service interruption can be required. If the requested operation requires a noticeable service interruption to interactive users, confirmation is requested before the operation is started.
A prompt is displayed on the standard error output for confirmation on the standard input. Confirmation can be overridden with the -y or -n option to always answer yes or no, respectively. Hardware-specific options, such as test level, are supplied as suboptions using the -o option.
Operations that change the state of the system configuration are audited by the system log daemon syslogd(1M).
The arguments for this command conform to the getopt(3C) and getsubopt(3C) syntax conventions.
Refer to the Sun Fire 15K/12K Dynamic Reconfiguration User Guide for more information.
|