o Interface Between ILOM and Guest Manager - ILOM to Guest Manager Calls --------------------------------------------------------------------------- Changes History --------------------------------------------------------------------------- Version Date Updated by Comments --------------------------------------------------------------------------- 1.0 2/2/2010 Sunit Jain Document created. --------------------------------------------------------------------------- --------------------------------------------------------------------------- Glossary/Acronyms --------------------------------------------------------------------------- ASR Automatic System Recovery. FPGA Field Programmable Gate Array. FRU Field Replacable Unit. GM/Guest Manager Daemon running on ILOM. Communication bridge between Host and ILOM. Host-config Reset firmware running on SPARC. Performs initialization of components like CPU, Memory, etc. Host SPARC side of the system. ILOM Integrated Lights Out Management. IPC Inter-Process Communication. NAC Nomenclature Advisory Committee. SP Service Processor. VBSC Virtual Board System Controller. --------------------------------------------------------------------------- 1. Interfaces provided by Guest Manager for consumption by ILOM This document describes interfaces for all the calls made from ILOM into GM. These calls are initiated by ILOM and are either used to notify GM of some events, or to get some data/status from GM. These interfaces are defined in GM workspace and ILOM processes wishing to use these functions make IPC calls which in turn call the functions described below. 2. Interfaces 2.1. VBSC_get_version_info Description ILOM request for GM version information. Function Prototype int VBSC_get_version_info(sp_buffer_t *version_info); Input Parameters version_info Pointer to sp_buffer_t structure. Storage allocated by the caller. Output Parameters version_info Pointer to sp_buffer_t structure filled with GM version information. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer where version info is copied. Allocated by the service provider (GM in this case). Sequence of Nul terminated strings. Each string is guaranteed to be non-nul. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- struct sp_buffer { void *buf; size_t size; int dofree; }; Service provide allocates the buffer where version information is copied and sets the buffer size in size field. Also sets a flag to indicate that caller should free up the memory when it is done using the data. The format of the data in buffer is : Version information may include version string, build path, build machine, build user, etc. information. 2.2. VBSC_HostReset Description ILOM requests GM to reset the host. Function Prototype int VBSC_HostReset(int *ret_val, int entire_host, int stop_at_ok, int force_reset); Input Parameters ret_val Pointer to integer. Storage allocated by the caller. entire_host Indicates whether the entire host or just the control domain is to be reset. 1 = reset entire host 0 = reset only control domain stop_at_ok Indicates if the domain should stop at OpenBoot ok prompt. 1 = force stop at ok prompt 0 = do not force stop at ok prompt force_reset Indicates if the reset should be forced without any grace period. 1 = force reset 0 = graceful shutdown Output Parameters ret_val Pointer to integer. Indicates the success of the reset command. 0 = reset succeeded -1 = reset failed Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.3. VBSC_HostPowerOn Description ILOM requests GM to power on the host. Function Prototype int VBSC_HostPowerOn(void); Input Parameters None. Output Parameters None. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.4. VBSC_HostPowerOff Description ILOM requests GM to Power off the host. Function Prototype int VBSC_HostPowerOff(void); Input Parameters None. Output Parameters None. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.5. VBSC_HostShutdown Description ILOM requests GM to Shutdown the host. Function Prototype int VBSC_HostShutdown(void); Input Parameters None. Output Parameters None. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.6. VBSC_asr_enable_components Description ILOM requests GM to update the enabled status for one or more components in the ASR database. Function Prototype int VBSC_asr_enable_components(sp_buffer_t *nac_list, sp_buffer_t *nacs_failed, int *ret_val) Input Parameters nac_list Pointer to sp_buffer_t structure. Storage allocated by caller. The buffer contains one or more nul-terminated NAC name strings of the components to be enabled in ASR database. nacs_failed Pointer to sp_buffer_t structure. Storage allocated by the caller. ret_val Pointer to integer. Storage allocated by the caller. Output Parameters naces_failed Pointer to sp_buffer_t structure. If ret_val is -2, the buffer will contain nul-terminated NAC name strings of components that could not get updated. Don't care otherwise. ret_val Result of ASR operation. 0 = Ok -1 = ASR DB unavailable -2 = Failed to update ASR status of some or all components. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer where nul-terminated NAC names can be copied. Sequence of Nul terminated strings. Each string is guaranteed to be non-nul. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- 2.7. VBSC_asr_disable_components Description ILOM requests GM to update the disabled status for one or more components in the ASR database. Function Prototype int VBSC_asr_disable_components(sp_buffer_t nac_list, sp_buffer_t *nacs_failed, * int *ret_val); Input Parameters nac_list Pointer to sp_buffer_t structure. Storage allocated by caller. The buffer contains one or more nul-terminated NAC name strings of the components to be disabled in ASR database. nacs_failed Pointer to sp_buffer_t structure. Storage allocated by the caller. ret_val Pointer to integer. Storage allocated by the caller. Output Parameters naces_failed Pointer to sp_buffer_t structure. If ret_val is -2, the buffer will contain nul-terminated NAC name strings of components that could not get updated. Don't care otherwise. ret_val Result of ASR operation. 0 = Ok -1 = ASR DB unavailable -2 = Failed to update ASR status of some or all components. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer where nul-terminated NAC names can be copied. Sequence of Nul terminated strings. Each string is guaranteed to be non-nul. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- 2.8. VBSC_asr_get_reasons Description ILOM requests GM for the reason strings for one or more components specified by their NAC names. The reasn string indicates the reason why device was disabled. Function Prototype int VBSC_asr_get_reasons(sp_buffer_t nac_list, sp_buffer_t *rsn_buf, int *ret_val) Input Parameters nac_list Pointer to sp_buffer_t structure. Storage allocated by caller. The buffer contains one or more nul-terminated NAC name strings of the components for which reason string is requested. rsn_buf Pointer to sp_buffer_t structure. Storage allocated by the caller. ret_val Pointer to integer. Storage allocated by the caller. Output Parameters rsn_buf Pointer to sp_buffer_t structure. The buffer will contain nul-terminated reason strings. Nth reason string corresponds to Nth NAC string in nac_list. If a component is enabled in ASR database, then its reason string would be empty. ret_val Result of ASR operation. 0 = Ok -1 = ASR DB unavailable -2 = Request made to an unavailable device. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer where nul-terminated reason strings can be copied. Sequence of Nul terminated strings. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- 2.9. VBSC_asr_get_state Description ILOM requests the state of entire ASR database. Function Prototype int VBSC_asr_get_state(sp_buffer_t *unavail_list, sp_buffer_t *disabled_list, int *ret_val); Input Parameters unavail_list Pointer to sp_buffer_t. Storage allocated by caller. disabled_list Pointer to sp_buffer_t. Storage allocated by caller. ret_val Pointer to integer. Storage allocated by caller. Output Parameters unavail_list Pointer to sp_buffer_t structure. The buffer will contain nul-terminated NAC strings of all the components that are marked as unavaliable in ASR database. disabled_list Pointer to sp_buffer_t structure. The buffer will contain nul-terminated NAC strings of all the components that are marked as disabled in ASR database. ret_val Result of ASR operation. 0 = Operation succeeded -1 = ASRDB unavailable Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer where nul-terminated NAC strings can be copied. Sequence of Nul terminated strings. List of NAC names of unavailable or disabled components. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- 2.10. VBSC_hostPromAccessReq Description ILOM requests GM to grant access to Host PROM. If access is granted, ILOM is allowed to program the PROM. While ILOM has access, it is guaranteed that GM would not access the PROM. Function Prototype int VBSC_hostPromAccessReq(int *ret_val); Input Parameters ret_val Pointer to integer. Storage allocated by caller. Output Parameters ret_val Indicates if the access to Host PROM is granted. 0 = Access not granted Not 0 = Access granted Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.11. VBSC_hostPromAccessRel Description ILOM notifies GM that it has relinquished access to the Host PROM. GM can access the PROM again. Function Prototype int VBSC_hostPromAccessRel(void); Input Parameters None. Output Parameters None. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.12. VBSC_GetHostState Description ILOM requests GM for the stte of the host. Function Prototype int VBSC_GetHostState(sp_buffer_t *state, int *ret_val); Input Parameters state Pointer to sp_buffer_t structure. Storage allocated by the caller. ret_val Pointer to integer. Storage allocated by caller. Output Parameters state Pointer to sp_buffer_t structure. The buffer contains data in the format of sys_state_t. Buffer should be released by the caller. ret_val 0 = if success in getting the host state -1 = if not able to get host state because host is uninitialized or other internal error. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer containing system state data. Buffer allocated by GM and must be freed by the caller. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- System state data is defined as: --------------------------------------------------------- Offset Size Description ------- ------------- --------------------------------- 0 8 bytes Guest Soft State 8 32 bytes Guest Soft State description 40 4 bytes Host State --------------------------------------------------------- struct sys_state { uint64_t sis_state; /* Guest Soft State */ uint8_t desc[32] /* Description */ int hostState; /* Host State */ }; Guest Soft State field can have following values: SIS_UNDEFINED 0 SIS_NORMAL 1 SIS_TRANSITION 2 Guest Soft State description can have one of the following string values based on Guest Soft State value: "Unknown" when SIS_UNDEFINED "Host started" when SIS_NORMAL "Transition" when SIS_TRANSITION Host State can have following values: LOM_HOST_POWER_STATE 1 LOM_HOST_WARM_START 2 LOM_HOST_GUEST_STARTED 3 LOM_HOST_GUEST_STOPPED 4 LOM_HOST_POWEREDON 5 LOM_HOST_POWEREDOFF 6 LOM_HOST_RESET 7 LOM_HOST_GUEST_UPDATE 8 LOM_CHASSIS_INTRUSION 9 LOM_CHASSIS_SECURE 10 2.13. VBSC_kernel_dump Description ILOM requests GM to send the kernel_dump request to Hypervisor. This in turn would trigger OS kernel to generate core dump. Function Prototype int VBSC_kernel_dump(int *ret_val) Input Parameters ret_val Pointer to integer. Storage allocated by caller. Output Parameters ret_val 0 = If kernel dump request succeeded. -1 = If kernel dump request failed. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.14. VBSC_get_flash_var Description ILOM requests GM to get the specified configuration variable (SC Variables & OBP Configuration Variables) from Data Flash Function Prototype int VBSC_get_flash_var(char *key, sp_buffer_t *val); Input Parameters key Pointer to a string containing the name of the configuration variable whose value is seeked. Nul-terminated string. val Pointer to sp_buffer_t structure. Storage allocated by the caller. Output Parameters val Pointer to sp_buffer_t structure. The buffer contains the value of the configuration variable. Value is in nul-terminated string format. Only valid if return value is SP_OK. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer containing the value of configuration variable. Data in nul-terminated string format. Buffer allocated by service provider. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- 2.15. VBSC_set_flash_var Description ILOM requests GM to set a specified configuration variable (SC variable or OBP Configuration variable) in Data Flash. Function Prototype int VBSC_set_flash_var(char *key, sp_buffer_t *val); Input Parameters key Pointer to a string containing the name of the configuration variable whose value is to be set. Nul-terminated string. val Pointer to sp_buffer_t structure. Storage allocated by the caller. The buffer contains new value (in nul-terminated string format) to which the specified variable need to be set. Output Parameters None. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer containing the value of configuration variable. Data in nul-terminated string format. Buffer allocated by service provider. 4 4 bytes Size of buffer 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- Description Function Prototype Input Parameters Output Parameters Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.16. VBSC_get_console_bootlog Description ILOM requests the GM to deliver the host console log. Function Prototype int VBSC_get_console_bootlog(sp_buffer_t *buf); Input Parameters buf Pointer to sp_buffer_t structure. Storage allocated by the caller. Output Parameters buf Pointer to sp_buffer_t structure. If the host console log is found, it is copied to the buffer and size is also set. If host console log is not found, the size is set to 0. Storage to buffer allocated by the provider. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed sp_buffer_t structure is defined as - ---------------------------------------------------------------- Offset Size Description ------- ------------- ---------------------------------------- 0 4 bytes Pointer to buffer containing the host console data. Storage allocated by the service provider. 4 4 bytes Size of buffer (size of the log) 8 4 bytes Flag to indicate if IPC framework to free the buffer. ---------------------------------------------------------------- 2.17. VBSC_flash_backup Description ILOM requests GM to back up the config data off of the Host Data flash and save in ILOM persistent storage. The following data would be saved : GM owned SC Variables ASR Status OBP Configuration Variables LDOM configurations Function Prototype int VBSC_flash_backup(void); Input Parameters None. Output Parameters None. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed 2.18. VBSC_flash_restore Description ILOM requests GM to restore the Host Data Flash with data that was previously save by VBSC_flash_backup in ILOM persistent storage. Function Prototype int VBSC_flash_restore(void); Input Parameters None. Output Parameters None. Return Value SP_OK 0 Call succeeded SP_FAIL -1 Call Failed