o Interface Between ILOM and Guest Manager - Guest Manager to ILOM 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. JTAG Joint Test Action Group. Standard Test Access Port and Boundary Scan Architecture. NAC Nomenclature Advisory Committee. SP Service Processor. TAP Test Access Port (JTAG) TMS Test Mode State (JTAG) --------------------------------------------------------------------------- 1. Interfaces provided by ILOM for consumption by Guest Manager This document describes interfaces for all the calls made from GM into ILOM. These calls are initiated by GM and are either used to notify ILOM of some events, or to get some data/status from ILOM. These interfaces are provided by two shared libraries (libspapp_plat and libjtag_plat) in the ILOM workspace. GM links with these libraries and makes calls to these routines, many of which generate IPC calls to the appropriate ILOM processes. 2. Interfaces 2.1. SP_Plat_NewHostState Description Notify ILOM the new Host state. When ever host state or guest state changes, GM notifies the change to ILOM via this call. Function prototype int SP_Plat_NewHostState(uint8_t *sys_state, size_t size) Input parameters sys_state Pointer to system state data size Size of system state data Output parameters None. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 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.2. SP_Plat_SetNumCpuSerialInfo Description Send Processor information to ILOM. Information inclues processor serial number and strand available information. Function Prototype int SP_Plat_SetNumCpuSerialInfo(void *cpuserial, int node) Input Parameters cpuserial Pointer to CPU Serial information data node Processor node number. Possible value 0 to MAX_NODE. Output Parameters None. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed CPU Serial Information data is defined as: --------------------------------------------------------- Offset Size Description ------- ------------- --------------------------------- 0 16 bytes Processor Serial Number 16 16 bytes Available Strands bitmask --------------------------------------------------------- struct cpu_serial_info { uint64_t proc_serial_num[2]; uint64_t strand_avail[2]; }; In bitmask, bit 0 represent strand 0, bit 1 represents strand 1, and so on. Bit value of 1 indicates that the strand is present, bit value 0 indicates that the strand is absent. 2.3. SP_Plat_set_part_info Description Send per part information to ILOM. Function Prototype int SP_Plat_set_part_info(char *nac, int32_t value) Input Parameters nac Pointer to the NAC name for a component. Nul terminated string. NAC names are platform specific and defined in Platform Nomenclature document. value Value for the part specified by component pointed by the nac parameter Output Parameters None. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.4. SP_Plat_GetHostType Description Get platform host type value from ILOM. Each platform is assigned a unique Platform Host Id. Function Prototype int SP_Plat_GetHostType(int *platform_id) Input Parameters platform_id Pointer to an integer. ILOM would fill in the Host Type. Space allocated by caller. Output Parameters platform_id ILOM fills in the Platform Host id and returns to GM. Only valid if return value is SP_PLAT_OK. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed Platform Host type is defined in aregistry at - http://sac.eng.sun.com/arc/FWARC/Registries/Host_Type_Registry.txt HOST_TYPE_RESERVED 0 (host platform id cannot be determined) HOST_TYPE_SOLANA 39 HOST_TYPE_SERPA 40 HOST_TYPE_JUMILLA 41 HOST_TYPE_SEVILLE 42 2.5. SP_Plat_sp_nvram_get Description Get the value of an ILOM NVRAM variable. Function Protoype int SP_Plat_sp_nvram_get(char *var_name, char *var_value, size_t size) Input Parameters var_name Pointer to the variable name. Nul terminated string. var_value Pointer to a string. Space allocated by caller. ILOM would fill in the value of variable specified in var_name. size Size of var_value buffer including Nul termination. Maximum value of size is 256 including the Nul character. Output Parameters var_value ILOM fills in the buffer with the value of variable pointed by var_name. At most "size" character are copied in var_value. Nul terminated string. Only valid if return value is SP_PLAT_OK. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.6 SP_Plat_gethrtime Description Returns the current high-resolution real time. Time is expressed as nanoseconds since some arbitrary time in the past; it is not correlated in any way to the time of day. Function Prototype uint64_t SP_Plat_gethrtime(void) Input Parameters None Output Parameters None Return Value Real time 64-bit value, time in nano-seconds 0 Failed 2.7. SP_Plat_notify_powerstate_fail Description Notify ILOM of the failure of host Power ON or Power Off. Function Prototype int SP_Plat_notify_powerstate_fail(uint8_t state); Input Parameters state 0 => Power ON failure 1 => Power Off failure Output Parameters None Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.8. SP_Plat_notify_watchdog_timeout Description Notify ILOM of the guest watchdog timer expiry. The watchdog is between the hypervisor and the guest. Function Prototype void SP_Plat_notify_watchdog_timeout(int guest) Input Parameters guest Guest id of the guest that failed the watchdog. Output Parameters None Return Value None 2.9. SP_Plat_notify_powerglitch Description GM informs ILOM that it detected a power glitch as indicated by the FPGA register. Function Prototype int SP_Plat_notify_powerglitch(uint8_t reg) Input Parameters reg Value of the POK Glitch Capture register in FPGA. Output Parameters None Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.10 SP_Plat_sp_power_button_pressed Description GM notifies ILOM of a PowerON request due to Power Button pressed. Function Prototype void SP_Plat_sp_power_button_pressed(void); Input Parameters None. Output Parameters None. Return Value None. 2.11. SP_Plat_send_nvlist Description Send an unpacked-nvlist-formatted ereport to ILOM. Refer to PSARC 2000/212 for libnvpair documentation. Function Prototype int SP_Plat_send_nvlist(void *ereport); Input Parameters ereport Pointer to the ereport in the form of an unpacked nvlist. Output Parameters None. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.12. SP_Plat_log_alert Description Send an alert message to ILOM. ILOM would send this message to all the consoles and also log into console log. Function Prototype int SP_Plat_log_alert(char *message, int level); Input Parameters message Pointer to the nul terminated alert message. level Severity level Output Parameters None. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed Severity level can have one of the following values: ILOM_SEVERITY_MINOR 1 used for WARNING messages ILOM_SEVERITY_MAJOR 2 used for ERROR messages ILOM_SEVERITY_CRITICAL 3 used for FATAL error messages ILOM_SEVERITY_LOG_FAULT 0x10 used to log a fault that must be specifically cleared by the user. 2.13. SP_Plat_inform_asr_state_change Description Notify ILOM of ASR state change (enabled/disabled, available/ unavailable) for a given component. ILOM is informed whenever there is a change in the ASR state of any component. Function Prototype int SP_Plat_inform_asr_state_change(char *nac, uint8_t available, uint8_t enabled); Input Parameters nac NAC name of the component. Nul-terminated string. available 1 => component is available in the system 0 => component is not available in the system enabled 1 => component is ASR enabled 0 => component is ASR disabled Output Parameters None. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.14. SP_Plat_inform_asr_state Description Send the a list of all the compponents that are ASR disabled. Also, send a list of all the components that are unavailable. Function Prototype int SP_Plat_inform_asr_state(char *unavail_list, int num_unavail, char *disabled_list, int num_disabled); Input Parameters unavail_list List of all the unavailable components. List of nul terminated NAC name strings. num_unavail Size of unavail_list, in bytes. disabled_list List of all the ASR disabled components. List of nul terminated NAC name strings. num_disabled Size of disabled_list, in bytes. Output Parameters None. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.15. SP_Plat_get_sp_macaddr Description Get MAC address of the ILOM. MAC address is in binary format. Function Prototype int SP_Plat_get_sp_macaddr(char *buf); Input Parameters buf Pointer to 6-byte buffer. Allocated by the caller. Output Parameters buf 6-byte MAC address. ILOM fills in the buffer with its own MAC address. Only valid if return value if SP_PLAT_OK. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.16. SP_Plat_get_fru_data Description Get FRU data for the component identified by the NAC name. Function Prototype int SP_Plat_get_fru_data(char *nac, char **part_number, char **serial_number, char **dash_number, char **rev_number); Input Parameters nac NAC name of the component whose FRU data is needed. Nul-terminated string. Maximum length of 128 bytes including nul character. part_number Pointer to location where address of part number string is stored. serial_number Pointer to location where address of serial number string is stored. dash_number Pointer to location where address of dash number string is stored. rev_number Pointer to location where address of revision number string is stored. Output Parameters part_number Component's part number as read from the FRU PROM. Nul-terminated string. String buffer is allocated by provider (ILOM) and freed by the caller. serial_number Component's serial number as read from the FRU PROM. Nul-terminated string. String buffer is allocated by provider (ILOM) and freed by the caller. dash_number Component's dash number as read from the FRU PROM. Nul-terminated string. String buffer is allocated by provider (ILOM) and freed by the caller. rev_number Component's revision number as read from the FRU PROM. Nul-terminated string. String buffer is allocated by provider (ILOM) and freed by the caller. Output valid only if return value is SP_PLAT_OK. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed 2.17. SP_Plat_JTAG_Select_IR Description GM instructs ILOM to select JTAG instruction register. This operation is required before the JTAG instruction register may be loaded with a new value. Function Prototype void SP_Plat_JTAG_Select_IR(void); Input Parameters None. Output Parameters None. Return Value None. 2.18. SP_Plat_JTAG_Select_DR Description GM instrcts ILOM to select JTAG data register. This operation is required before the JTAG data register may be loaded with a new value. Function Prototype void SP_Plat_JTAG_Select_DR(void); Input Parameters None. Output Parameters None. Return Value None. 2.19. SP_Plat_cycle_tck Description Cycle the JTAG TCK register. Function Prototype void SP_Plat_cycle_tck(void); Input Parameters None. Output Parameters None. Return Value None. 2.20. SP_Plat_JTAG_Reset_TAP Description Reset JTAG TAP. Function Prototype void SP_Plat_JTAG_Reset_TAP(void); Input Parameters None. Output Parameters None. Return Value None. 2.21. SP_Plat_JTAG_SetTms Description Set/reset the JTAG TMS bit. Function Prototype void SP_Plat_JTAG_SetTms(int value); Input Parameters value 0 => reset/clear the TMS bit 1 => set the TMS bit Output Parameters None. Return Value None. 2.22. SP_Plat_JTAG_reset_signals Description Reset the JTAG signals. Function Prototype void SP_Plat_JTAG_reset_signals(void); Input Parameters None. Output Parameters None. Return Value None. 2.23. SP_Plat_JTAG_Shift Description Shift a pattern string out to the JTAG port. Function Prototype char *SP_Plat_JTAG_Shift(char *pattern, int length, int recycle, int wait, char pad); Input Parameters pattern String containing a pattern in hex format. length Length of the pattern string in number of bits. recycle If set, it will recycle the bits read from the scan chain. wait Allows optional waiting for 'sentinal' bit to be set. i.e, starts count when 1st 'set' TDO is seen .. If wait = 1, check within Shift-DR If wait = 2, progam BYPASS before RTI if wait = 3, check and program BYPASS before RTI pad If the actual length of "pattern" string is smaller than the specified "length", then the extra bits are added to the "pattern" and each bit is same as the "pad" bit. Output Parameters None. Return Value NULL if failure String Data shifted out of the JTAG scan chain. Data is a sequence of binary characters. 2.24. SP_Plat_get_hostid Description Get the host id for the system. Function Prototype int SP_Plat_get_hostid(uint32_t *hostid); Input Parameters hostid Pointer to a 32-bit unsigned integer. Storage allocated by the caller. Output Parameters hostid Host Id of the system. Valid only if return value is SP_PLAT_OK. Return Value SP_PLAT_OK 0 Call succeeded SP_PLAT_ERROR -1 Call failed