OSHW.tex

The Operating system/Hardware Interface is intended to be a low level interface that exposes power and energy relevant architecture features of the underlying hardware, such as the ability to measure and control power and energy characteristics of underlying components. 
In some cases this information will be abstracted for presentation to the application through the Application/Operating System API interface (section \ref{sec:AppOS}) or the resource manager through the Resource Manager/Operating System API (section \ref{sec:RMOS}).
While we have chosen the term \texttt{Operating system} as part of this interface name, we are not strictly implying that all interfaces described in this section should be limited to the domain of the operating system. 
Additionally, we are not implying that this interface requires specific privileges, although many low level operations require elevated privileges. 
Portions of the system software stack, like a runtime system, may use many of the interfaces described in this section.

\subsection{Supported Attributes}\label{sec:OSHWAttributes}
A significant amount of functionality for this interface is exposed through the attribute functions (section \ref{sec:Attributes}).
The attribute functions in conjunction with the following attributes (Table \ref{table:OSHW}) expose numerous measurement  (get) and control (set) capabilities to the operating system.

\begin{attributetable}{Operating System, Hardware - Supported Attributes}{table:OSHW}
\aPstateDesc
\aCstateDesc
\aCstateLimitDesc
\aSstateDesc
\aCurrentDesc
\aVoltageDesc
\aPowerDesc
\aMinPowerDesc
\aMaxPowerDesc
\aFreqDesc
\aFreqLimitMinDesc
\aFreqLimitMaxDesc
\aEnergyDesc
\aTempDesc
\aThrottledIdDesc
\aThrottledCountIdDesc
\aOSIdDesc
\aGovDesc
\end{attributetable}

\subsection{Supported Core (Common) Functions}\label{sec:OSHWSupportedCommon}

\begin{itemize}[noitemsep,nolistsep] 
	\item{Hierarchy Navigation Functions - section \ref{sec:Navigation}}
		\begin{itemize}[noitemsep,nolistsep] 
			\item{ALL}
		\end{itemize}
	\item{Group Functions - section \ref{sec:Group}}
		\begin{itemize}[noitemsep,nolistsep] 
			\item{ALL}
		\end{itemize}
	\item{Attribute Functions - section \ref{sec:Attributes}}
		\begin{itemize}[noitemsep,nolistsep] 
			\item{ALL}
		\end{itemize}
	\item{Metadata Functions - section \ref{sec:METADATA}}
		\begin{itemize}[noitemsep,nolistsep] 
			\item{ALL}
		\end{itemize}
	\item{Statistics Functions - section \ref{sec:StatisticsFunctions}}
		\begin{itemize}[noitemsep,nolistsep] 
			\item{ALL - for real time queries only}
		\end{itemize}
\end{itemize}

%==============================================================================%

\subsection{Supported High-Level (Common) Functions}\label{sec:OSHWHighLevel}

%==============================================================================%

\subsection{Interface Specific Functions}\label{sec:OSHWFunctions}

%=============================================================================%
%int PWR_StateTransitDelay( PWR_Obj obj, PWR_OperState start_state, PWR_OperState end_state, PWR_Time *latency );
\begin{prototype}{StateTransitDelay}
	\longdescription{ The \texttt{PWR_StateTransitDelay} function returns the expected latency to transition between two valid states in nanoseconds.  It is up to the vendor to provide accurate estimates for hardware. For example, P-state transitions could be given a single latency, even though some transitions might take less time (e.g., high voltage to lower voltage versus low to high).  The desired state must be expressed using a \texttt{PWR_OperState} structure described in section \ref{sec:OSHWTypeDefinitions} on page \pageref{sec:OSHWTypeDefinitions}.  This transition time may be a worst case latency time, and may be supplied by the hardware manufacturer (through the BIOS or other reporting mechanism). It is expected that this delay is an estimate of the time required to transition between states, not an estimate of the time that the core is unavailable for use (which may be a shorter interval than the time for the changes to take effect).}
	\returntype{int}
	\parameter{PWR_Ob obj}{\pInput}{The object that the state transition would be applied to.}
	\parameter{PWR_OperState start_state}{\pInput}{The state at the beginning of the transition.}
	\parameter{PWR_OperState end_state}{\pInput}{The state at the end of the transition.}
	\parameter{PWR_Time *latency}{\pOutput}{Pointer to a double that will contain the transition latency in nanoseconds upon return.}
	\returnval{PWR_RET_SUCCESS}{Upon SUCCESS.}
	\returnval{PWR_RET_FAILURE}{Upon FAILURE.}
\end{prototype}