sun microsystems Systems Architecture Committee _________________________________________________________________ Subject: Solaris Hotplug Framework Submitted by: Colin Zou File: PSARC/2008/181/opinion.ms Date: September 3rd, 2009 Committee: Garrett D'Amore (opinion written by Phi Tran), Sebastien Roy. Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary The main goal of this project is to deliver a generic common hotplug framework -- a foundation which can support the hot- plug functionality for any hotpluggable bus and also, to support device migration functionality in a virtualized environment through virtual hotplug. 2. Decision & Precedence Information The project is approved as specified in references [1] - [3]. The project may be delivered in a minor and/or patch release of the ON consolidation. 3. Interfaces The project exports the following interfaces. _______________________________________________________________________________ | Interfaces Exported | |_________________________|_______________________|___________________________| |Interface | Classification | Comments | |_________________________|_______________________|___________________________| |MODHPOPS | Project Private | Modctl command for | | | | hotplug operations | |MODHPOPS_CHANGE_STATE | Project Private | Modctl sub-command for | | | | changing hotplug state | |MODHPOPS_CREATE_PORT | Project Private | Modctl sub-command for | |_________________________|_______________________|___________________________| PSARC/2008/181 Copyright 2009 Sun Microsystems - 2 - _______________________________________________________________________________ | Interfaces Exported | |_________________________|_______________________|___________________________| |Interface | Classification | Comments | |_________________________|_______________________|___________________________| | | | creating a port | |MODHPOPS_REMOVE_PORT | Project Private | Modctl sub-command for | | | | removing a port | |MODHPOPS_BUS_SET | Project Private | Modctl sub-command for | | | | setting bus specific | | | | hotplug properties. | |MODHPOPS_BUS_GET | Project Private | Modctl sub-command for | | | | getting bus specific | | | | hotplug properties. | |ddi_hp_property_t | Project Private | Structure used to get/set| | | | bus specific hotplug | | | | properties. | |ndi_hp_register() | Consolidation Private| Register a connection to | | | | hotplug framework | |ndi_hp_unregister() | Consolidation Private| Unregister a connection | | | | from hotplug framework | |ndi_hp_state_change_req()| Consolidation Private| Submit a state change | | | | request to hotplug | | | | framework | |ndi_hp_walk_cn() | Consolidation Private| Walk the connections | | | | linked to a device | | | | node | |ddi_hp_cn_info_t | Consolidation Private| Structure for the | | | | information of a | | | | connection | |ddi_hp_cn_state_t | Consolidation Private| enum for the hotplug | | | | states of a connection | |BUSO_REV_10 | Consolidation Private| bus_ops busops_rev | |bus_hp_op() | Consolidation Private| Add a bus_ops entry for | | | | hotplug operations | |ddi_hp_op_t | Consolidation Private| Hotplug operations | |pcicfg_configure() | Consolidation Private| Update the existing | | | | interface for probing and| | | | configuring a connection.| |pcicfg_unconfigure() | Consolidation Private| Update the existing | | | | interface for unprobing | | | | and unconfiguring a | | | | connection. | |pcicfg_flags_t | Consolidation Private| New flags for the | | | | argument to | | | | pcicfg_configure() and | | | | pcicfg_unconfigure(). | |_________________________|_______________________|___________________________| PSARC/2008/181 Copyright 2009 Sun Microsystems - 3 - ______________________________________________________________________________ | Interfaces Exported | |__________________________|_______________________|_________________________| |Interface | Classification | Comments | |__________________________|_______________________|_________________________| |/usr/sbin/hotplug | Committed | hotplug(1M) CLI | |/usr/lib/hotplugd | Project Private | hotplugd(1M) daemon | |/usr/lib/cfgadm/shp.so.1 | Uncommitted | cfgadm_shp(1M) plugin | |/lib/libhotplug.so.1 | Consolidation Private| libhotplug(3LIB) | |/var/run/hotplugd_door | Project Private | Door file, hotplugd(1M)| |Hotplug Management | Uncommitted | Rights Prof. | |solaris.hotplug. | Uncommitted | Hierarchy | |solaris.hotplug.modify | Uncommitted | Modify Auth. | |solaris.smf.manage.hotplug| Uncommitted | SMF Auth. | |__________________________|_______________________|_________________________| _______________________________________________________________________________ | Interfaces Exported | |____________________________________________________|_____________|__________| |Interface | Class. | Comments| |____________________________________________________|_____________|__________| |/usr/lib/help/auths/locale/HotplugHeader.html | Uncommitted| Help | | | | Files | |/usr/lib/help/auths/locale/HotplugModify.html | Uncommitted| "" | |/usr/lib/help/auths/locale/SmfManageHotplug.html | Uncommitted| "" | |/usr/lib/help/auths/locale/C/HotplugHeader.html | Uncommitted| "" | |/usr/lib/help/auths/locale/C/HotplugModify.html | Uncommitted| "" | |/usr/lib/help/auths/locale/C/SmfManageHotplug.html | Uncommitted| "" | |/usr/lib/help/profiles/locale/RtHotplugMngmnt.html | Uncommitted| "" | |/usr/lib/help/profiles/locale/C/RtHotplugMngmnt.html| Uncommitted| "" | |svc:/system/hotplug | Committed | FMRI | |/var/svc/manifest/system/hotplug.xml | Proj. Priv.| Service | | | | Manifest| |/lib/svc/method/svc-hotplug | Proj. Priv.| Method | | | | Script | |____________________________________________________|_____________|__________| _____________________________________________________________________ | Interfaces Exported | |___________________|________________|______________________________| |Interface | Classification| Comments | |___________________|________________|______________________________| |DINFOHP | Consol. Priv. | Flag for di_init() to | | | | include hotplug information | | | | in snapshot. | |DI_HP_NIL | Consol. Priv. | A NULL di_hp_t structure. | |DI_HP_CONNECTOR | Consol. Priv. | Flag for di_walk_hp() | | | | to traverse hotplug | | | | connectors. | |DI_HP_PORT | Consol. Priv. | Flag for di_walk_hp() | | | | to traverse hotplug | | | | ports. | |___________________|________________|______________________________| PSARC/2008/181 Copyright 2009 Sun Microsystems - 4 - _____________________________________________________________________ | Interfaces Exported | |___________________|________________|______________________________| |Interface | Classification| Comments | |___________________|________________|______________________________| |di_hp_t | Consol. Priv. | Structure of a hotplug | | | | connector associated | | | | with a di_node_t. | |di_walk_hp() | Consol. Priv. | Traverse hotplug | | | | connectors associated | | | | with a di_node_t. | |di_hp_next() | Consol. Priv. | Get next di_hp_t | | | | in a list. | |di_hp_name() | Consol. Priv. | Get name of a | | | | di_hp_t connector. | |di_hp_state() | Consol. Priv. | Get state of a | | | | di_hp_t connector. | |di_hp_last_change()| Consol. Priv. | Get timestamp of last | | | | state change of | | | | a di_hp_t connection. | |di_hp_type() | Consol. Priv. | Return connection type. | |di_hp_description()| Consol. Priv. | Return description of the | | | | hotplug handle | | | | (e.g. "PCI Slot", etc.) | |di_hp_child() | Consol. Priv. | Return child device | | | | node of a virtual | | | | hotplug port. | |di_hp_connection() | Consol. Priv. | Return connection number. | |di_hp_depends_on() | Consol. Priv. | Return depended upon | | | | connection number | |HP_NODE_DEVICE | Consol. Priv. | Node type for a device | | | | node. | |HP_NODE_CONNECTOR | Consol. Priv. | Node type for physical | | | | connector | |HP_NODE_PORT | Consol. Priv. | Node type for virtual | | | | port. | |HP_NODE_USAGE | Consol. Priv. | Node type for usage | | | | record. | |hp_node_t | Consol. Priv. | Structure of a node | | | | in snapshot. | |hp_init() | Consol. Priv. | Initialize a hotplug | | | | snapshot. | |hp_fini() | Consol. Priv. | Cleanup/Remove hotplug | | | | snapshot. | |hp_traverse() | Consol. Priv. | Traverse nodes in a | | | | snapshot. | |hp_name() | | Consol. Priv. | |hp_path() | | Consol. Priv. | |hp_type() | Consol. Priv. | Get a node's type. | |hp_description() | Consol. Priv. | Get description of | | | | connector or port. | |hp_state() | Consol. Priv. | Get a node's current state. | |hp_last_change() | Consol. Priv. | Get timestamp when a | | | | connector or port's | |___________________|________________|______________________________| PSARC/2008/181 Copyright 2009 Sun Microsystems - 5 - _____________________________________________________________________ | Interfaces Exported | |___________________|________________|______________________________| |Interface | Classification| Comments | |___________________|________________|______________________________| | | | state was last changed. | |hp_usage() | Consol. Priv. | Get a node's usage | | | | description. | |hp_parent() | Consol. Priv. | Get a node's parent. | |hp_child() | Consol. Priv. | Get a node's first child. | |hp_sibling() | Consol. Priv. | Get a node's next sibling. | |hp_set_state() | Consol. Priv. | Command to initiate | | | | state change. | |hp_set_private() | Consol. Priv. | Bus specific 'set' function.| |hp_get_private() | Consol. Priv. | Bus specific 'get' function.| |___________________|________________|______________________________| The project imports the following interfaces. ________________________________________________________________ | Interfaces Imported | |_________|_______________________|____________________________| |Interface| Classification | Comments | |_________|_______________________|____________________________| |pcicfg | Consolidation Private| configure/unconfigure PCI | | | | devices | |modctl() | See comments. | A system call with a | | | | long history. | | | | Unknown interface level, | | | | but recent modctl commands| | | | are usually Consolidation | | | | Private or Project | | | | Private. | |ibdevinfo| Committed | To access device and | | | | connection information. | |librcm | Consolidation Private| To get RCM usage, and | | | | RCM offline. | |libsecdb | Committed | To perform RBAC | | | | authorization checks. | |libbsm | Contract Private | To perform auditing. | |_________|_______________________|____________________________| 4. Opinion 4.1. DDI_HP_CN_TYPE A member suggested that the project could predefine more values for DDI_HP_CN_TYPE for devices such as USB, PCMCIA, CARDBUS, FIREWIRE, SCSI, FC, IB, and SDCARD. The project team responded that they do not have enough information on which buses will be supported or how exactly the PSARC/2008/181 Copyright 2009 Sun Microsystems - 6 - implementation would look. An example given is that there are different versions of USB and it is not understood yet if one value or multiple values should be reserved. 4.2. hotplug(1M) -o Option A member noted that the hotplug(1M) man page doesn't docu- ment the arguments that can be used with the -o option. The project team agreed to add a feature that will allow the user to get help about the supported options and their pos- sible values through the hotplug(1M) command. 5. Minority Opinion(s) None. 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required None. 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory PSARC/2008/181. 1. 20 Questions File: commitment2.materials/shp-proj-20q.txt 2. Project Specification File: commitment2.materials/shp-overview.pdf 3. Issues and Responses File: issues 4. Man Page for hotplug commands File: commitment2.materials/hotplug.1m.txt 5. Man Page for hotplug daemon File: commitment2.materials/hotplugd.1m.txt PSARC/2008/181 Copyright 2009 Sun Microsystems