[Skiboot] [PATCH 2/2] FSP/EPOW: Add EPOW event driver in OPAL

[Stewart Smith]

Vipin K Parashar <vipin at linux.vnet.ibm.com> writes:
> EPOW event driver adds support in OPAL for handling EPOW events on FSP
> based systems.
> 	On these systems upon detecting any error conditions that can can cause
> an unexpected system shutdown, SPCN/FSP HW sends alerts to system software by
> generating an Early Power Off Warning (EPOW) event. As a result hypervisor/OS
> shall start shutdown procedure upon receiving an EPOW event. OPAL EPOW event
> driver handles these EPOW notifications from FSP, processes event information,
> sends notifications to host kernel and makes EPOW event details available to it.
> 	This driver provides OPAL_GET_EPOW_EVENT_INFO OPAL call for host kernel
> to obtain EPOW event information available with OPAL. For cases when EPOW
> condition is cleared, FSP send notification again to inform about EPOW condition
> returning to normal. OPAL EPOW event driver notifies host kernel for such
> scenarions too and host kernel should cancel shutdown timer if shutdown hasn't
> started yet.

So, there's non-FSP systems too, and this interface must be suitable and
extensible to non-FSP based systems.

> HW details
> ===========
> 	EPOW events are of two types: EPOW3, EPOW4.
> Thse events are triggered by SPCN due to various reasons like utility
> power loss, high ambient temperature etc.
>
> * EPOW3 event is triggered for critical platform conditions that
> require system shutdown in 15 mins time like system AC power loss and
> system running on UPS power.
> * EPOW4 event is triggered for critical platform conditions that
> require system shutdown within 20 secs time like system AC power loss,
> system running on UPS and UPS battery running low on charge.

EPOW3 and EPOW4 aren't very good names, and neither is hard coding
specific timeouts for action to be taken.

Perhaps on some other system, the timeouts could be different, or even
be computed based on what the current power demands are on the UPS in
the datacenter.

> 	FSP sends EPOW notifications via mbox panel status notification alerts.
> This notification contains information about EPOW event. Among these notification
> UPS utility fail and UPS battery low bits in byte1 determine the EPOW event type
> and byte5 value informs about EPOW reason. For any change in these two bits
> SPCN triggers EPOW alerts.
>
> EPOW event flow from HW to guest OS
> ====================================
> 	Upon receiving a EPOW alert from OPAL, host kernel should make OPAL
> OPAL_GET_EPOW_EVENT_INFO call to get EPOW event details. For any EPOW event
> missed while booting, host kernel should use same call to request EPOW event
> info. Kernel should prepare for graceful system shutdown within time available
> once it is notified about EPOW event. Prior to host shutdown, host kernel
> should also notify guest OSes about EPOW event via EPOW interrupt mechanism
> and pass on needed EPOW event info to guest OS to handle events. Since guest OS
> follow PAPR standards thus host kerel should map EPOW event info details to
> needed EPOP event details in PAPR format.
> Below table summarises HW EPOW event to PAPR EPOW event info mappings.
>
> HW EPOW event = EPOW3
> PAPR EPOW Sensor value = 3
> PAPR EPOW Action code = 3 (SYSTEM_SHUTDOWN)
>
> HW EPOW event = EPOW4
> PAPR EPOW Sensor value = 4
> PAPR EPOW Action code = 4 (SYSTEM_HALT)
>
> HW EPOW event = EPOW0
> PAPR EPOW Sensor value = 0
> PAPR EPOW Action Code = 0 (EPOW_RESET)
>
> PAPR EPOW modifier value is obtained from EPOW reason code.

All of this documentation should go in doc/opal-api/

But as mentioned, I don't understand why you're replacing the old
interface with a very FSP specific looking one.

> +static int64_t opal_get_epow_event_info(struct opal_epow_event *epow_data)
> +{
> +	if (epow_data == NULL)
> +		return OPAL_PARAMETER;
> +
> +	lock(&epow_lock);
> +	memcpy(epow_data, &epow, sizeof(struct opal_epow_event));
> +	unlock(&epow_lock);
> +
> +	return OPAL_SUCCESS;
> +}

This API does not leave room for future expansion.

we must be able to add things and have existing kernels work.