You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Common.tex
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,7 @@
18
18
Core functions include the following areas:
19
19
\begin{itemize}[noitemsep,nolistsep]
20
20
\item{\textbf{Initialization}, required to use any of the functionality described in this specification, }
21
-
\item{\textbf{Navigation} functions allow the user to traverse the system description and discover information about the underlying platform, }
21
+
\item{\textbf{Navigation} functions allow the user to traverse the system description and discover information about the underlying facility/platform, }
22
22
\item{\textbf{Group} functions, primarily a convenience abstraction,}
23
23
\item{\textbf{Attribute} functions expose measurement and control functionality, }
24
24
\item{\textbf{Metadata} functions allow the user to access additional information about objects and attributes (often device or instrumentation specific information), }
\longdescription{The \texttt{PWR_ObjGetParent} function is used to find the object immediately above the specified object in the system description available to the user through the current context. Note, currently, there are some cases where an object has no parent, namely the platform object.}
149
+
\longdescription{The \texttt{PWR_ObjGetParent} function is used to find the object immediately above the specified object in the system description available to the user through the current context. Note, currently, there are some cases where an object has no parent, namely the facility object.}
150
150
\returntype{int}
151
151
\parameter{PWR_Obj object} {\pInput} {The object that the user wishes to determine the parent of.}
152
152
\parameter{PWR_Obj* parent}{\pOutput} {The parent object of the specified input object.}
Copy file name to clipboardExpand all lines: TheoryOfOperation.tex
+25-14Lines changed: 25 additions & 14 deletions
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ \section{Overview}
11
11
It should be noted that many terms commonly used when discussing object oriented languages are used in this section and the document as a whole.
12
12
The use of these terms in no way implies that the Power API specification must be implemented using an object oriented language.
13
13
%The authors of this specification in fact, recommend the contrary.
14
-
We have attempted to achieve two goals, listed in order of priority: 1) programmer portability, where the programmer is the user of the API, and 2) the latitude of the implementor who will often become the user of the API benefitting from our first priority.
14
+
We have attempted to achieve two goals, listed in order of priority: 1) programmer portability, where the programmer is the user of the API, and 2) the latitude of the implementor who will often become the user of the API benefiting from our first priority.
@@ -24,7 +24,7 @@ \section{Power API Initialization}\label{sec:PowerAPIInit}
24
24
25
25
26
26
Using any of the Power API interfaces requires initialization.
27
-
Initializaton returns a context.
27
+
Initialization returns a context.
28
28
In the specification, the context is defined as an opaque pointer.
29
29
This approach was taken to allow the maximum amount of flexibility to the implementor.
30
30
The context returned will contain (act as the entry point to) the system description that is exposed to the user, all policy and privilege information, basically everything the user of the API requires to perform the functionality specified by the API.
\item{\textbf{Application} The application or application library executing on the compute resource. May also include run-time components running in user space.}
49
49
\item{\textbf{Monitor and Control} Cluster management or Reliability Availability and Serviceability (RAS) systems, for example.}
50
50
\item{\textbf{Operating System} Linux or specialized Light Weight Kernels which are found on HPC platforms and potentially portions of run-time systems. }
51
-
\item{\textbf{User} The user of the HPC platform. }
51
+
\item{\textbf{User} The user of the HPC facility, typically using one platform but potentially using multiple platforms. }
52
52
\item{\textbf{Resource Manager} This can include work load managers, schedulers, allocators and even portions of run-time systems. }
53
-
\item{\textbf{Administrator} The system administrator or HPC platform manager. }
54
-
\item{\textbf{HPCS Manager} The individual or individuals responsible for managing policy for the HPC platform, for example. }
55
-
\item{\textbf{Accounting} Individual or software that produces reports of metrics for the HPC platform. }
53
+
\item{\textbf{Administrator} The system administrator or HPC facility/platform manager. }
54
+
\item{\textbf{HPCS Manager} The individual or individuals responsible for managing policy for the HPC facility and platforms, for example. }
55
+
\item{\textbf{Accounting} Individual or software that produces reports of metrics for the HPC facility and associated platforms. }
56
56
\end{itemize}
57
57
These brief definitions are not meant to be exhaustive.
58
58
Roles are analogous with the \textit{Actors} discussed in section \ref{sec:UseCase}.
The system description is the \textit{view} of the system exposed to the user upon initialization via the context that is returned.
109
-
Figure \ref{fig:BaseSystemMap} depicts an example of a system description showing a hierarchical arrangement of objects.
109
+
Figure \ref{fig:BaseSystemMap} depicts an example of a system description showing a hierarchical arrangement of objects where there is only one platform.
110
110
All object types listed in the specification must be defined by any implementation, but do not have to be used in the system description.
111
111
The implementation chooses which objects will be employed in the system description and how they will be arranged.
112
112
An object can only have a single parent but may have multiple children.
113
-
Currently, a system description may only describe a single platform and have a single object of type \texttt{Platform} which represents the top of the hierarchy.
114
-
Later revisions of the specification may include the ability to combine multiple platforms in the system description.
115
-
This might be useful, for example, in representing an entire datacenter.
113
+
A system description may describe more than a single platform as a facility object where the facility object has multiple objects of type \texttt{Platform} and the facility represents the top of the hierarchy.
114
+
Due to the large number of variations in software, hardware and security profiles between platforms and the difficulty in providing a universal Power API implementation that would work between any and all platforms, control over platform objects is confined to within that platform object.
115
+
Power API contexts initialized below the facility level (platform or lower in the system hierarchy) can only read attributes at the facility level, not modify them.
116
+
For example, a compute node in a given platform cannot query or modify the CPU frequency of a object on another platform.
117
+
However, that compute node could query (it can only read attributes, not modify them at the facility level) the facility object to inquire about the overall facility power usage if security policies allow such queries.
118
+
A user with a role initialized at the facility level is meant to interact with high-level platform objects, it is not intended for low-level object control (i.e. controlling per socket power budgets). Such low level controls should be done with roles initialized at the platform level.
116
119
While figure \ref{fig:BaseSystemMap} depicts a homogeneous system description, homogeneity is \textit{not} a requirement.
117
120
In practice a system description can be heterogeneous and unbalanced.
118
121
119
122
To summarize the requirements:
120
123
\begin{itemize}[noitemsep,nolistsep] %
121
124
\item{
122
-
The \texttt{Platform} object type must be defined by the implementation and must appear at the top of the system description.
125
+
At least one \texttt{Platform} object type must be defined by the implementation and may appear at the top of the system description or immediately underneath a facility object.
123
126
}
124
127
\item{
125
128
All object types in this specification must be defined in any implementation. The use of the object types, with the exception of the \texttt{Platform} object type, is optional.
126
129
}
127
130
\item{
128
-
Objects can only have one parent but may have many children. Currently the \texttt{Platform} object has no parent since it appears at the top of the system description. This will likely change in future versions of the specification.
131
+
Objects can have at most one parent but may have many children. Currently the \texttt{Facility} object has no parent as it represents the top of the system description.
129
132
}
130
133
\item{
131
134
If an implementation chooses to add objects not defined in the specification they should only be exposed to the user in a vendor specific context to avoid unpredictable or non-portable behaviour (see \funcref{CntxtInit}).
The following is a list of the object types currently included in the specification along with a short description of each.
142
145
\begin{itemize}[noitemsep,nolistsep] %
143
146
\item{
144
-
Platform - Currently, the one and only Platform object is the top level object of the system description exposed to the user of the API.
147
+
Facility - The Facility object is the highest level object allowed in a system description.
148
+
It represents an entire computing facility that may be made up of multiple platforms.
149
+
Facility objects are useful for including resources like cooling or power delivery that may be shared by multiple platforms.
150
+
Facility objects are not necessarily traversible between users on different platforms.
151
+
That is, users may not be able to interact or even discover other platforms within the same facility.
152
+
}
153
+
\item{
154
+
Platform - A Platform object is the top level object of the system description exposed to a typical user of the API.
155
+
It represents one of the main system divisions in a given compute facility and may be the highest level object in facilities that have only one platform.
145
156
The Platform object is intended to conceptually represent the entire Platform.
146
157
For example, if the Platform object has a power or energy measurement or control capability exposed through the Platform objects attributes the scope of these attributes should be platform wide.
Note, in the list above all the attributes are implicit.
232
243
Explicit attributes are defined in the \typeref{AttrName} type definition.
233
-
The majority of the attributes defined in the specification, and likely those added by an implementator, are, and will be, explicit.
244
+
The majority of the attributes defined in the specification, and likely those added by an implementor, are, and will be, explicit.
234
245
The implicit attributes defined above are primarily used for navigation and are accessed through attribute specific functions which are described in Section \ref{sec:Navigation}.
235
246
236
247
Explicit attributes are either accessed through the generic attribute interface (Section \ref{sec:Attributes}) or attribute specific functions found in either the section describing the specific interface in which they are used or in Chapter \ref{chap:Common}, \textit{Core (Common) Interface Functions}.
0 commit comments