1cfgadm_sbd(1M) System Administration Commands cfgadm_sbd(1M)
2
6 cfgadm_sbd - cfgadm commands for system board administration
7
9 cfgadm -l [-a] [-o parsable] ap_id...
10 cfgadm -c function [-f] [-y | -n]
13 [-o unassign | nopoweroff] [-v] ap_id...
14 cfgadm -t [-v] ap_id...
17 cfgadm -x [-f] [-v] function ap_id...
20
23 The cfgadm_sbd plugin provides dynamic reconfiguration functionality
24 for connecting, configuring, unconfiguring, and disconnecting class sbd
25 system boards. It also enables you to connect or disconnect a system
26 board from a running system without having to reboot the system.
27 The cfgadm command resides in /usr/sbin. See cfgadm(1M). The cfgadm_sbd
30 plugin resides /usr/platform/sun4u/lib/cfgadm.
31 Each board slot appears as a single attachment point in the device
34 tree. Each component appears as a dynamic attachment point. You can
35 view the type, state, and condition of each component, and the states
36 and condition of each board slot by using the -a option.
37 The cfgadm options perform differently depending on the platform. Addi‐
40 tionally, the form of the attachment points is different depending on
41 the platform. See the Platform Notes section for more information.
42 Component Conditions
44 The following are the names and descriptions of the component condi‐
45 tions:
46 failed The component failed testing.
48 ok The component is operational.
51 unknown The component has not been tested.
54 Component States
57 The following is the name and description of the receptacle state for
58 components:
59 connected The component is connected to the board slot.
61 The following are the names and descriptions of the occupant states for
65 components:
66 configured The component is available for use by the Solaris oper‐
68 ating environment.
69 unconfigured The component is not available for use by the Solaris
72 operating environment.
73 Board Conditions
76 The following are the names and descriptions of the board conditions.
77 failed The board failed testing.
79 ok The board is operational.
82 unknown The board has not been tested.
85 unusable The board slot is unusable.
88 Board States
91 Inserting a board changes the receptacle state from empty to discon‐
92 nected. Removing a board changes the receptacle state from disconnected
93 to empty.
94 Caution: Removing a board that is in the connected state or that is
97 powered on and in the disconnected state crashes the operating system
98 and can result in permanent damage to the system.
99 The following are the names and descriptions of the receptacle states
102 for boards:
103 connected The board is powered on and connected to the system
105 bus. You can view the components on a board only after
106 it is in the connected state.
107 disconnected The board is disconnected from the system bus. A board
110 can be in the disconnected state without being powered
111 off. However, a board must be powered off and in the
112 disconnected state before you remove it from the slot.
113 empty A board is not present.
116 The occupant state of a disconnected board is always unconfigured. The
120 following table contains the names and descriptions of the occupant
121 states for boards:
122 configured At least one component on the board is configured.
124 unconfigured All of the components on the board are unconfigured.
127 Dynamic System Domains
130 Platforms based on dynamic system domains (DSDs, referred to as domains
131 in this document) divide the slots in the chassis into electrically
132 isolated hardware partitions (that is, DSDs). Platforms that are not
133 based on DSDs assign all slots to the system permanently.
134 A slot can be empty or populated, and it can be assigned or available
137 to any number of domains. The number of slots available to a given
138 domain is controlled by an available component list (ACL) that is main‐
139 tained on the system controller. The ACL is not the access control list
140 provided by the Solaris operating environment.
141 A slot is visible to a domain only if the slot is in the domain's ACL
144 and if it is not assigned to another domain. An unassigned slot is vis‐
145 ible to all domains that have the slot in their ACL. After a slot has
146 been assigned to a domain, the slot is no longer visible to any other
147 domain.
148 A slot that is visible to a domain, but not assigned, must first be
151 assigned to the domain before any other state changing commands are
152 applied. The assign can be done explicitly using -x assign or implic‐
153 itly as part of a connect. A slot must be unassigned from a domain
154 before it can be used by another domain. The unassign is always
155 explicit, either directly using -x unassign or as an option to discon‐
156 nect using -o unassign.
157 State Change Functions
159 Functions that change the state of a board slot or a component on the
160 board can be issued concurrently against any attachment point. Only one
161 state changing operation is permitted at a given time. A Y in the Busy
162 field in the state changing information indicates an operation is in
163 progress.
164 The following list contains the functions that change the state:
167 o configure
169 o unconfigure
171 o connect
173 o disconnect
175 Availability Change Functions
177 Commands that change the availability of a board can be issued concur‐
178 rently against any attachment point. Only one availability change oper‐
179 ation is permitted at a given time. These functions also change the
180 information string in the cfgadm -l output. A Y in the Busy field indi‐
181 cates that an operation is in progress.
182 The following list contains the functions that change the availability:
185 o assign
187 o unassign
189 Condition Change Functions
191 Functions that change the condition of a board slot or a component on
192 the board can be issued concurrently against any attachment point. Only
193 one condition change operation is permitted at a given time. These
194 functions also change the information string in the cfgadm -l output. A
195 Y in the Busy field indicates an operation is in progress.
196 The following list contains the functions that change the condition:
199 o poweron
201 o poweroff
203 o test
205 Unconfigure Process
207 This section contains a description of the unconfigure process, and
208 illustrates the states of source and target boards at different stages
209 during the process of moving permanent memory.
210 In the following code examples, the permanent memory on board 0 must be
213 moved to another board in the domain. Thus, board 0 is the source, and
214 board 1 is the target.
215 A status change operation cannot be initiated on a board while it is
218 marked as busy. For brevity, the CPU information has been removed from
219 the code examples.
220 The process is started with the following command:
223 # cfgadm -c unconfigure -y SB0::memory &
225 First, the memory on board 1 in the same address range as the permanent
230 memory on board 0 must be deleted. During this phase, the source board,
231 the target board, and the memory attachment points are marked as busy.
232 You can display the status with the following command:
233 # cfgadm -a -s cols=ap_id:type:r_state:o_state:busy SB0 SB1
235 Ap_Id Type Receptacle Occupant Busy
237 SB0 CPU connected configured y
238 SB0::memory memory connected configured y
239 SB1 CPU connected configured y
240 SB1::memory memory connected configured y
241 After the memory has been deleted on board 1, it is marked as unconfig‐
247 ured. The memory on board 0 remains configured, but it is still marked
248 as busy, as in the following example.
249 Ap_Id Type Receptacle Occupant Busy
251 SB0 CPU connected configured y
252 SB0::memory memory connected configured y
253 SB1 CPU connected configured y
254 SB1::memory memory connected unconfigured n
255 The memory from board 0 is then copied to board 1. After it has been
261 copied, the occupant state for the memory is switched. The memory on
262 board 0 becomes unconfigured, and the memory on board 1 becomes config‐
263 ured. At this point in the process, only board 0 remains busy, as in
264 the following example.
265 Ap_Id Type Receptacle Occupant Busy
267 SB0 CPU connected configured y
268 SB0::memory memory connected unconfigured n
269 SB1 CPU connected configured n
270 SB1::memory memory connected configured n
271 After the entire process has been completed, the memory on board 0
277 remains unconfigured, and the attachment points are not busy, as in the
278 following example.
279 Ap_Id Type Receptacle Occupant Busy
281 SB0 CPU connected configured n
282 SB0::memory memory connected unconfigured n
283 SB1 CPU connected configured n
284 SB1::memory memory connected configured n
285 The permanent memory has been moved, and the memory on board 0 has been
291 unconfigured. At this point, you can initiate a new state changing
292 operation on either board.
293 Platform-Specific Options
295 You can specify platform-specific options that follow the options
296 interpreted by the system board plugin. All platform-specific options
297 must be preceded by the platform keyword. The following example con‐
298 tains the general format of a command with platform-specific options:
299 command -o sbd_options,platform=platform_options
302
304 This man page does not include the -v, -a, -s, or -h options for the
305 cfgadm command. See cfgadm(1M) for descriptions of those options. The
306 following options are supported by the cfgadm_sbd plugin:
307 -c function Performs a state change function. You can use the fol‐
309 lowing functions:
310 unconfigure Changes the occupant state to unconfig‐
312 ured. This function applies to system
313 board slots and to all of the components
314 on the system board.
315 The unconfigure function removes the CPUs
317 from the CPU list and deletes the physi‐
318 cal memory from the system memory pool.
319 If any device is still in use, the cfgadm
320 command fails and reports the failure to
321 the user. You can retry the command as
322 soon as the device is no longer busy. If
323 a CPU is in use, you must ensure that it
324 is off line before you proceed. See
325 pbind(1M), psradm(1M) and psrinfo(1M).
326 The unconfigure function moves the physi‐
328 cal memory to another system board before
329 it deletes the memory from the board you
330 want to unconfigure. Depending of the
331 type of memory being moved, the command
332 fails if it cannot find enough memory on
333 another board or if it cannot find an
334 appropriate physical memory range.
335 For permanent memory, the operating sys‐
337 tem must be suspended (that is, quiesced)
338 while the memory is moved and the memory
339 controllers are reprogrammed. If the
340 operating system must be suspended, you
341 will be prompted to proceed with the
342 operation. You can use the -y or -n
343 options to always answer yes or no
344 respectively.
345 Moving memory can take several minutes to
347 complete, depending on the amount of mem‐
348 ory and the system load. You can monitor
349 the progress of the operation by issuing
350 a status command against the memory
351 attachment point. You can also interrupt
352 the memory operation by stopping the
353 cfgadm command. The deleted memory is
354 returned to the system memory pool.
355 disconnect Changes the receptacle state to discon‐
358 nected. This function applies only to
359 system board slots.
360 If the occupant state is configured, the
362 disconnect function attempts to unconfig‐
363 ure the occupant. It then powers off the
364 system board. At this point, the board
365 can be removed from the slot.
366 This function leaves the board in the
368 assigned state on platforms that support
369 dynamic system domains.
370 If you specify -o nopoweroff, the discon‐
372 nect function leaves the board powered
373 on. If you specify -o unassign, the dis‐
374 connect function unassigns the board from
375 the domain.
376 If you unassign a board from a domain,
378 you can assign it to another domain. How‐
379 ever, if it is assigned to another
380 domain, it is not available to the domain
381 from which is was unassigned.
382 configure Changes the occupant state to configured.
385 This function applies to system board
386 slots and to any components on the system
387 board.
388 If the receptacle state is disconnected,
390 the configure function attempts to con‐
391 nect the receptacle. It then walks the
392 tree of devices that is created by the
393 connect function, and attaches the
394 devices if necessary. Running this func‐
395 tion configures all of the components on
396 the board, except those that have already
397 been configured.
398 For CPUs, the configure function adds the
400 CPUs to the CPU list. For memory, the
401 configure function ensures that the mem‐
402 ory is initialized then adds the memory
403 to the system memory pool. The CPUs and
404 the memory are ready for use after the
405 configure function has been completed
406 successfully.
407 For I/O devices, you must use the mount
409 and the ifconfig commands before the
410 devices can be used. See ifconfig(1M) and
411 mount(1M).
412 connect Changes the receptacle state to con‐
415 nected. This function applies only to
416 system board slots.
417 If the board slot is not assigned to the
419 domain, the connect function attempts to
420 assign the slot to the domain. Next, it
421 powers on and tests the board, then it
422 connects the board electronically to the
423 system bus and probes the components.
424 After the connect function is completed
426 successfully, you can use the -a option
427 to view the status of the components on
428 the board. The connect function leaves
429 all of the components in the unconfigured
430 state.
431 The assignment step applies only to plat‐
433 forms that support dynamic system
434 domains.
435 -f Overrides software state changing constraints.
439 The -f option never overrides fundamental safety and
441 availability constraints of the hardware and operating
442 system.
443 -l Lists the state and condition of attachment points spec‐
446 ified in the format controlled by the -s, -v, and -a
447 options as specified in cfgadm(1M). The cfgadm_sbd plug‐
448 in provides specific information in the info field as
449 described below. The format of this information might be
450 altered by the -o parsable option.
451 The parsable info field is composed of the following:
453 cpu The cpu type displays the following informa‐
455 tion:
456 cpuid=#[,#...] Where # is a number,
458 and represents the ID
459 of the CPU. If more
460 than one # is present,
461 this CPU has multiple
462 active virtual proces‐
463 sors.
464 speed=# Where # is a number
467 and represents the
468 speed of the CPU in
469 MHz.
470 ecache=# Where # is a number
473 and represents the
474 size of the ecache in
475 MBytes. If the CPU has
476 multiple active vir‐
477 tual processors, the
478 ecache could either be
479 shared among the vir‐
480 tual processors, or
481 divided between them.
482 memory The memory type displays the following infor‐
486 mation, as appropriate:
487 address=# Where # is a number,
489 representing the
490 base physical
491 address.
492 size=# Where # is a number,
495 representing the
496 size of the memory
497 in KBytes.
498 permanent=# Where # is a number,
501 representing the
502 size of permanent
503 memory in KBytes.
504 unconfigurable An operating system
507 setting that pre‐
508 vents the memory
509 from being unconfig‐
510 ured.
511 inter-board-interleave The board is partic‐
514 ipating in inter‐
515 leaving with other
516 boards.
517 source=ap_id Represents the
520 source attachment
521 point.
522 target=ap_id Represents the tar‐
525 get attachment
526 point.
527 deleted=# Where # is a number,
530 representing the
531 amount of memory
532 that has already
533 been deleted in
534 KBytes.
535 remaining=# Where # is a number,
538 representing the
539 amount of memory to
540 be deleted in
541 KBytes.
542 io The io type displays the following informa‐
546 tion:
547 device=path Represents the physical path to
549 the I/O component.
550 referenced The I/O component is refer‐
553 enced.
554 board The board type displays the following boolean
558 names. If they are not present, then the oppo‐
559 site applies.
560 assigned The board is assigned to the
562 domain.
563 powered-on The board is powered on.
566 The same items appear in the info field in a
568 more readable format if the -o parsable option
569 is not specified.
570 -o parsable Returns the information in the info field as a boolean
574 name or a set of name=value pairs, separated by a space
575 character.
576 The -o parsable option can be used in conjunction with
578 the -s option. See the cfgadm(1M) man page for more
579 information about the -s option.
580 -t Tests the board.
583 Before a board can be connected, it must pass the appro‐
585 priate level of testing.
586 Use of this option always attempts to test the board,
588 even if it has already passed the appropriate level of
589 testing. Testing is also performed when a -c connect
590 state change function is issued, in which case the test
591 step can be skipped if the board already shows an appro‐
592 priate level of testing. Thus the -t option can be used
593 to explicitly request that the board be tested.
594 -x function Performs an sbd-class function. You can use the follow‐
597 ing functions:
598 assign Assigns a board to a domain.
600 The receptacle state must be disconnected or
602 empty. The board must also be listed in the
603 domain available component list. See Dynamic
604 System Domains.
605 unassign Unassigns a board from a domain.
608 The receptacle state must be disconnected or
610 empty. The board must also be listed in the
611 domain available component list. See Dynamic
612 System Domains.
613 poweron Powers the system board on.
616 The receptacle state must be disconnected.
618 poweroff Powers the system board off.
621 The receptacle state must be disconnected.
623
627 The following operands are supported:
628 Receptacle ap_id For the Sun Fire high-end systems such as the Sun
630 Fire 15K , the receptacle attachment point ID takes
631 the form SBX or IOX, where X equals the slot num‐
632 ber.
633 The exact format depends on the platform and typi‐
635 cally corresponds to the physical labelling on the
636 machine. See the platform specific information in
637 the NOTES section.
638 Component ap_id The component attachment point ID takes the form
641 component_typeX, where component_type equals one of
642 the component types described in "Component Types"
643 and X equals the component number. The component
644 number is a board-relative unit number.
645 The above convention does not apply to memory com‐
647 pontents. Any DR action on a memory attachment
648 point affects all of the memory on the system
649 board.
650
653 The following examples show user input and system output on a Sun Fire
654 15K system. User input, specifically references to attachment points
655 and system output might differ on other Sun Fire systems, such as the
656 Sun Fire midrange systems such as the 6800. Refer to the Platform Notes
657 for specific information about using the cfgadm_sbd plugin on non-Sun
658 Fire high-end models.
659 Example 1 Listing All of the System Board
661 # cfgadm -a -s "select=class(sbd)"
663 Ap_Id Type Receptacle Occupant Condition
665 SB0 CPU connected configured ok
666 SB0::cpu0 cpu connected configured ok
667 SB0::memory memory connected configured ok
668 IO1 HPCI connected configured ok
669 IO1::pci0 io connected configured ok
670 IO1::pci1 io connected configured ok
671 SB2 CPU disconnected unconfigured failed
672 SB3 CPU disconnected unconfigured unusable
673 SB4 unknown empty unconfigured unknown
674 This example demonstrates the mapping of the following conditions:
679 o The board in Slot 2 failed testing.
682 o Slot 3 is unusable; thus, you cannot hot plug a board into
684 that slot.
685 Example 2 Listing All of the CPUs on the System Board
687 # cfgadm -a -s "select=class(sbd):type(cpu)"
689 Ap_Id Type Receptacle Occupant Condition
691 SB0::cpu0 cpu connected configured ok
692 SB0::cpu1 cpu connected configured ok
693 SB0::cpu2 cpu connected configured ok
694 SB0::cpu3 cpu connected configured ok
695 Example 3 Displaying the CPU Information Field
699 # cfgadm -l -s noheadings,cols=info SB0::cpu0
701 cpuid 16, speed 400 MHz, ecache 8 Mbytes
703 Example 4 Displaying the CPU Information Field in Parsable Format
707 # cfgadm -l -s noheadings,cols=info -o parsable SB0::cpu0
709 cpuid=16 speed=400 ecache=8
711 Example 5 Displaying the Devices on an I/O Board
715 # cfgadm -a -s noheadings,cols=ap_id:info -o parsable IO1
717 IO1 powered-on assigned
719 IO1::pci0 device=/devices/saf@0/pci@0,2000 referenced
720 IO1::pci1 device=/devices/saf@0/pci@1,2000 referenced
721 Example 6 Monitoring an Unconfigure Operation
725 In the following example, the memory sizes are displayed in Kbytes.
728 # cfgadm -c unconfigure -y SB0::memory &
731 # cfgadm -l -s noheadings,cols=info -o parsable SB0::memory SB1::memory
732 address=0x0 size=2097152 permanent=752592 target=SB1::memory
734 deleted=1273680 remaining=823472
735 address=0x1000000 size=2097152 source=SB0::memory
736 Example 7 Assigning a Slot to a Domain
740 # cfgadm -x assign SB2
742 Example 8 Unassigning a Slot from a Domain
746 # cfgadm -x unassign SB3
748
752 See attributes(5) for a description of the following attribute:
753 ┌─────────────────────────────┬─────────────────────────────┐
758 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
759 ├─────────────────────────────┼─────────────────────────────┤
760 │Availability │SUNWkvm.u │
761 ├─────────────────────────────┼─────────────────────────────┤
762 │Stability │See below. │
763 └─────────────────────────────┴─────────────────────────────┘
764 The interface stability is evolving. The output stability is unstable.
767
769 cfgadm(1M), devfsadm(1M), ifconfig(1M), mount(1M), pbind(1M),
770 psradm(1M), psrinfo(1M), config_admin(3CFGADM), attributes(5)
771
773 This section contains information on how to monitor the progress of a
774 memory delete operation. It also contains platform specific informa‐
775 tion.
776 Memory Delete Monitoring
778 The following shell script can be used to monitor the progress of a
779 memory delete operation.
780 # cfgadm -c unconfigure -y SB0::memory &
782 # watch_memdel SB0
783 #!/bin/sh
785 # This is the watch_memdel script.
786 if [ -z "$1" ]; then
788 printf "usage: %s board_id\n" `basename $0`
789 exit 1
790 fi
791 board_id=$1
793 cfgadm_info='cfgadm -s noheadings,cols=info -o parsable'
795 eval `$cfgadm_info $board_id::memory`
797 if [ -z "$remaining" ]; then
799 echo no memory delete in progress involving $board_id
800 exit 0
801 fi
802 echo deleting target $target
804 while true
806 do
807 eval `$cfgadm_info $board_id::memory`
808 if [ -n "$remaining" -a "$remaining" -ne 0 ]
810 then
811 echo $deleted KBytes deleted, $remaining KBytes remaining
812 remaining=
813 else
814 echo memory delete is done
815 exit 0
816 fi
817 sleep 1
818 done
819 exit 0
820 Sun Enterprise 10000 Platform Notes
824 The following syntax is used to refer to Platform Notes attachment
825 points on the Sun Enterprise 10000 system:
826 board::component
828 where board refers to the system board; and component refers to the
833 individual component. System boards can range from SB0 (zero) to SB15.
834 A maximum of sixteen system boards are available.
835 The DR 3.0 model running on a Sun Enterprise 10000 domain supports a
838 limited subset of the functionality provided by the cfgadm_sbd plugin.
839 The only supported operation is to view the status of attachment points
840 in the domain. This corresponds to the -l option and all of its associ‐
841 ated options.
842 Attempting to perform any other operation from the domain will result
845 in an error that states that the operation is not supported. All opera‐
846 tions to add or remove a system board must be initiated from the System
847 Service Processor.
848 Sun Fire High-End System Platform Notes
850 The following syntax is used to refer to attachment points on the Sun
851 Fire high-end systems:
852 board::component
854 where board refers to the system board or I/O board; and component
859 refers to the individual component.
860 Depending on the system's configuration, system boards can range from
863 SB0 (zero) through SB17, and I/O boards can range from IO0 (IO zero)
864 through IO17. (A maximum of eighteen system and I/O boards are avail‐
865 able).
866 The -t and -x options behave differently on the Sun Fire high-end sys‐
869 tem platforms. The following list describes their behavior:
870 -t The system controller uses a CPU to test system
872 boards by running LPOST, sequenced by the hpost
873 command. To test I/O boards, the driver starts
874 the testing in response to the -t option, and
875 the test runs automatically without user inter‐
876 vention. The driver unconfigures a CPU and a
877 stretch of contiguous physical memory. Then, it
878 sends a command to the system controller to
879 test the board. The system controller uses the
880 CPU and memory to test the I/O board from
881 inside of a transaction/error cage. You can
882 only use CPUs from system boards (not MCPU
883 boards) to test I/O boards.
884 -x assign | unassign In the Sun Fire high-end system administration
887 model, the platform administrator controls the
888 platform hardware through the use of an avail‐
889 able component list for each domain. This
890 information is maintained on the system con‐
891 troller. Only the platform administrator can
892 modify the available component list for a
893 domain.
894 The domain administrator is only allowed to
896 assign or unassign a board if it is in the
897 available component list for that domain. The
898 platform administrator does not have this
899 restriction, and can assign or unassign a board
900 even if it is not in the available component
901 list for a domain.
902 Sun Fire 15K Component Types
905 The following are the names and descriptions of the component types:
906 cpu CPU
908 io I/O device
911 memory Memory
914 Note: An operation on a memory component affects all of the memory com‐
918 ponents on the board.
919 Sun Fire Midrange Systems Platform Notes
921 References to attachment points are slightly different on Sun Fire
922 midrange servers such as the 6800, 4810, 4800, and 3800 systems than on
923 the Sun Fire high-end systems. The following syntax is used to refer to
924 attachment points on Sun Fire systems other than the Sun Fire 15K:
925 N#.board::component
927 where N# refers to the node; board refers to the system board or I/O
932 board; and component refers to the individual component.
933 Depending on the system's configuration, system boards can range from
936 SB0 through SB5, and I/O boards can range from IB6 through IB9. (A max‐
937 imum of six system and four I/O boards are available).
938 Sun Fire Midrange System Component Types
940 The following are the names and descriptions of the component types:
941 cpu CPU
943 pci I/O device
946 memory Memory
949 Note: An operation on a memory component affects all of the memory com‐
953 ponents on the board.
954SunOS 5.11 13 Oct 2003 cfgadm_sbd(1M)