Version 1.2 Date : 10/29/09 Revision History : 1.0 - Original submitted specification to FWARC 1.1 - Changes related to alignment restrictions. Matched alignment requirements to MACH_DESC APIs. 1.2 - Corrected group and function numbers for MACH_VARS API. The group number should be 0x105 and function number changed to 0x178. 1.0 Introduction ---------------- The following hypervisor APIs are required to support parallel boot. 2.0 PRI Delivery ---------------- For PRI delivery, a hcall API (see section 2.1) will be provided to retrieve the initial PRI data generated by host config. Future PRI Domain service should only push new PRI updates w.r.t the initial PRI generated by host config. Current existing PRI Domain service do not push initial PRI data. This API is implemented in the PBOOT group, 0x105. 2.1 HV API interface Definition ------------------------------- MACH_PRI Entry: trap# FAST_TRAP function# 0x170 arg0 buffer arg1 length Exit: ret0 status ret1 length This service copies the most current physical resource index (PRI) into the buffer indicated by the real address provided in arg0. If the argument *length* is non-zero, the argument *buf* is the real address of a data buffer. The buffer provided must be 16-byte aligned. Upon success or EINVAL this service returns the actual size of the PRI in ret1. Programming note: a method for determining the appropriate buffer size for the PRI is to first call this service with a buffer length of 0 bytes.) Errors: EBADALIGN buffer is badly aligned ENORADDR buffer is an illegal real address EINVAL buffer length is too small ENOACCESS the calling guest is not the control domain ENOTSUPPORTED the PRI is not accessible using this API 3.0 OBP NVRAM Variables ------------------------ The Updates MD delivered to OBP is simply a data structure in the machine description format with a single root node containing string properties named after nvram variables and containing their non-default values. The Updates MD is also delivered to the LDom Manager on the mdstore domain service so that it can merge the updates into its own version of the control domain guest MD. When an LDoms configuration is subsequently saved to the SP, the variables in the SP variable store are flushed since they are now represented in the running control domain guest MD and in the stored LDoms configuration. If the SP is faulted when the host is powered on, when the control domain OBP boots it will fail to register the var-config-backup ds with vbsc. Any non-default nvram variables will be present in the guest MD on this first boot after poweron since hostconfig is able to include the latest non-default variables from the backing store in the guest MD it creates. Moreover, if OBP setenv command is used to update a variable, it will fail due to the missing variable ds, and so there will be no new non-default settings to persist after the SP is faulted. If any non-default variables are present in the variable backing store but not in the guest MD, they are only retrievable via the Updates MD. This happens if OBP setenv is used and then the control domain is soft reset with reset-all. This also happens if Solaris eeprom is used while the LDom Manager is not running and the control domain is rebooted. There are additional use-cases that can result in this condition. If the SP is faulted while in this condition, absent some recovery, the user will see the OBP variables revert to either a historical value still present in the guest MD or back to the default value. It is proposed that if the SP is faulted OBP will retrieve the Updates MD via a an HV API call. The Updates MD will be stored in the host flash and kept up-to-date by vbsc. Hypervisor will retrieve the Updates MD from the flash and make it available to the control domain OBP. The layout of the flash and the Updates MD in it is described in the host flash section. The control domain OBP will continue to use the variable ds when the SP is present. Non-control domain OBP will continue to only use the variable ds provided by the LDom Manager. The control domain OBP will only fallback to using the HV API when the var-config-backup ds fails to register. This might happen for three reasons: 1) the SP is faulted; 2) host is doing parallel boot and vbsc on the SP is not yet running; 3) a hw/fw bug causes the ldc/ds transport for the variable service to fail. While the HV API is necessary for the case where the SP is faulted, it also provides an ideal recovery when the SP is not faulted but still booting. This might happen during a cold poweron boot of host and SP (parallel boot), or it might happen if the host and control domain are rebooted in parallel (parallel reboot). 3.1 HV API ----------- This is analogous to the MACH_DESC and MACH_PRI APIs. It is implemented in the PBOOT group, 0x105. MACH_VARS Entry: trap# FAST_TRAP function# 0x178 arg0 buffer real address arg1 pointer to uint64_t for size of buffer Exit: ret0 status ret1 required size of buffer / returned data size This service copies the current Variable Updates Machine Description into the buffer indicated by the real address provided in arg0. If the argument *length* is non-zero, the argument *buf* is the real address of a data buffer. The buffer provided must be 16-byte aligned. Upon success or EINVAL this service returns the actual size of the Variable Updates MD in the ret1. Programming note: a method for determining the appropriate buffer size for the Variable Updates MD is to first call this service with a buffer length of 0 bytes. A return value of EOK with a return length of 0 means that there is no OBP Variable Updates MD available. Errors: EBADALIGN buffer is badly aligned ENORADDR buffer is an illegal real address EINVAL buffer length is too small 4.0 Reboot Data ---------------- In SP degraded mode, if a domain is rebooted, Solaris would not be able to save the reboot parameters on the SP. Alternately, if SP goes down after reboot parameters are saved on the SP but before OBP is able to retrieve the parameters, OBP would not be able to boot Solaris using the specified parameters. In order to support a guest domain reboot in SP-degraded mode, a new HV API would be defined. Solaris would use this API to save the reboot parameters for the guest. The reboot parameters are saved with HV. When OBP is ready to boot Solaris, it would use the HV API to retrieve the reboot parameters and initiate the boot. Both Solaris and OBP need to negotiate the API version. If the API version supporting SP-degraded mode is detected, they should only use the HV API for reboot command parameters. If the API version supporting SP-degraded mode is not detected, the guest should continue to use the existing method of storing/retrieving the reboot parameters. 4.1 HV API interface Definition -------------------------------- The following APIs are available by negotiating version 1.0 of the REBOOT-DATA (0x110) API group. REBOOT_DATA_SET Entry: trap# FAST_TRAP function# 0x172 arg0 buf arg1 len Exit: ret0 status This service enables the guest to store data across a domain reset. The stored data will persist across a MACH_SIR. Initially the stored data will be cleared and the stored data length will be reset to the value zero. If the argument *len* is non-zero, the argument *buf* is the real address of a data buffer. The buffer provided must be 16-byte aligned. The argument *len* is the size of the data in the date buffer to be saved. If *len* is zero, the argument *buf* is ignored, and any previously saved data is destroyed and the saved data length is set to zero. If this function returns successfully, the saved data and length have been updated. If the argument *len* is non-zero, *len* bytes of data from the data buffer defined by the argument *buf* have been saved. The saved data and data length may be retrieved via the REBOOT_DATA_GET API. If this function returns an error, the saved data and data length are unchanged. The minimum supported size of the internal data buffer shall be 512 bytes and the actual maximum may be higher. The maximum supported size is specified as 512 bytes. It is the guests responsibility to clear the reboot data after it has been retrieved. The data may be cleared by calling REBOOT_DATA_SET with a length of 0. Errors: EBADALIGN buffer is badly aligned ENORADDR buffer is an illegal real address EINVAL *len* larger than maximum size REBOOT_DATA_GET Entry: trap# FAST_TRAP function# 0x171 arg0 buf arg1 len Exit: ret0 status ret1 actual-len This service returns a copy of the currently saved reboot data. The saved reboot data may be set via the REBOOT_DATA_SET API. If the argument *len* is non-zero, the argument *buf* is the real address of a *len* sized data buffer. The buffer provided must be 16-byte aligned. If the argument *len* is zero, the argument *buf* is ignored. Copies up to *len* bytes of stored data into the data buffer defined by the *buf* argument. In all cases, returns the actual length of the stored data in the return value *actual-len*. If *actual-len* is zero, no data is copied to the buffer defined by the *buf* argument, and there is no stored data. If the argument *len* is zero, return successfully with the return value *actual-len* set to the actual length of the stored data. If the argument *len* is non-zero, and less than the size of the stored data, returns the error code EINVAL. No data is copied. If the argument *len* is non-zero and greater than or equal to the size of the stored data, copies the stored data to the buffer defined by the *buf* argument. If the data buffer defined by the arguments *buf*, *len* is larger than the stored data, excess data bytes in the buffer defined by the arguments *buf*, *len* are undefined. Note: The client can easily determine the size of the stored data by calling this service with the *len* argument set to the value 0. Errors: EBADALIGN buffer is badly aligned ENORADDR buffer is an illegal real address EINVAL invalid buffer size