Power Application Programming Interface Specification Version 1.4

138 Pages·2016·1.49 MB·English

SANDIA REPORT
SAND2016-10899
Unlimited Release
Printed October 2016
Supersedes SAND2016-4446
Dated May 2016
High Performance Computing - Power
Application Programming Interface
Specification
Version 1.4
James H. Laros III, David DeBonis, Ryan E. Grant, Suzanne M. Kelly,
Michael Levenhagen, Stephen Olivier, Kevin Pedretti
Preparedby
SandiaNationalLaboratories
Albuquerque,NewMexico87185andLivermore,California94550
SandiaNationalLaboratoriesisamulti-missionlaboratorymanagedandoperatedbySandiaCorporation,
awhollyownedsubsidiaryofLockheedMartinCorporation,fortheU.S.DepartmentofEnergy’s
NationalNuclearSecurityAdministrationundercontractDE-AC04-94AL85000.
Approvedforpublicrelease;furtherdisseminationunlimited.
IssuedbySandiaNationalLaboratories,operatedfortheUnitedStatesDepartmentofEnergy
bySandiaCorporation.
NOTICE:ThisreportwaspreparedasanaccountofworksponsoredbyanagencyoftheUnited
States Government. Neither the United States Government, nor any agency thereof, nor any
of their employees, nor any of their contractors, subcontractors, or their employees, make any
warranty, express or implied, or assume any legal liability or responsibility for the accuracy,
completeness,orusefulnessofanyinformation,apparatus,product,orprocessdisclosed,orrep-
resent that its use would not infringe privately owned rights. Reference herein to any specific
commercialproduct,process,orservicebytradename,trademark,manufacturer,orotherwise,
does not necessarily constitute or imply its endorsement, recommendation, or favoring by the
United States Government, any agency thereof, or any of their contractors or subcontractors.
TheviewsandopinionsexpressedhereindonotnecessarilystateorreflectthoseoftheUnited
StatesGovernment,anyagencythereof,oranyoftheircontractors.
D•E(cid:13)PARTMENTOFENERGY•(cid:13)
UNITEDSTATESOFAMERICA
2
SAND2016-10899
UnlimitedRelease
PrintedOctober2016
Supersedes SAND2016-4446
dated May 2016
High Performance Computing - Power Application
Programming Interface Specification
Version 1.4
James H. Laros III, David DeBonis, Ryan E. Grant,
Suzanne M. Kelly, Michael Levenhagen, Stephen Olivier, Kevin Pedretti
Center for Computing Research
Sandia National Laboratories
P.O. Box 5800
Albuquerque, NM 87185-1319
jhlaros,ddeboni,regrant,smkelly,mjleven,slolivi,[e-mail]
Abstract
Measuring and controlling the power and energy consumption of high performance computing
systemsbyvariouscomponentsinthesoftwarestackisanactiveresearcharea [13,3,5,10,4,21,
19,16,7,17,20,18,11,1,6,14,12]. Implementationsinlowerlevelsoftwarelayersarebeginning
to emerge in some production systems, which is very welcome. To be most effective, a portable
interface to measurement and control features would significantly facilitate participation by all
levelsofthesoftwarestack. WepresentaproposalforastandardpowerApplicationProgramming
Interface(API)thatendeavorstocovertheentiresoftwarespace,fromgenerichardwareinterfaces
totheinputfromthecomputerfacilitymanager.
3
Acknowledgment
Support for this work was provided through the Advanced Simulation and Computing (ASC) pro-
gramfundedbyU.S.DepartmentofEnergy’sNationalNuclearSecurityAgency. Wewishtothank
our colleagues, Steve Hammond, Ryan Elmore, and Kris Munch at the National Renewable En-
ergyLaboratory(NREL)fortheircontributionstotheusecasemodelwhichwastheprogenitorof
thiswork. ThiseffortwasgreatlyenhancedbyinteractionswithstaffthroughoutSandiaaswellas
manyexternalorganizations.
Prior to the first open release of this specification a select group of individuals agreed to re-
viewanearlydraftofthespecificationandprovidefeedback. Wewouldliketorecognizethevery
significant contributions these individuals made and thank them for their time and efforts. The
following individuals participated in an all day face-to-face review of the specification and pro-
vided written feedback (listed in alphabetical order): David Jackson (Adaptive Computing), Steve
Martin (Cray), Indrani Paul (AMD), Phil Pokorny (Penguin Computing), Avi Purkayastha (Na-
tional Renewable Energy Laboratory), Muralidhar Rajappa (Intel), and Jeff Stuecheli (IBM). The
following individuals provided written feedback of the specification (listed in alphabetical order):
Dorian Arnold (University of New Mexico), Natalie Bates (EEHPC), and Chung-Hsing Hsu (Oak
RidgeNationalLaboratory). Wehopetocontinuetheseimportantcollaborationsanddevelopnew
onesinanefforttorepresentandservetheHPCcommunityasbestwecan.
4
Contents
1 Introduction 13
1.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.2 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.3 UseCaseDevelopment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.4 SecurityModel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2 TheoryofOperation 17
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2 PowerAPIInitialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.3 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.4 SystemDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.5 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.6 Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7 ThreadSafety. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3 TypeDefinitions 25
3.1 OpaqueTypes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2 GloballyRelevantDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.3 ContextRelevantTypeDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
PWR CntxtType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
PWR Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.4 ObjectRelevantTypeDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
PWR ObjType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5
3.5 AttributeRelevantTypeDefinitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
PWR AttrName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
PWR AttrDataType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
PWR AttrAccessError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
PWR AttrGov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.6 MetadataRelevantTypeDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
PWR MetaName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.7 ErrorReturnDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.8 TimeRelatedDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
PWR TimePeriod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.9 StatisticsRelevantTypeDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
PWR AttrStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
PWR ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.10 OSHardwareInterfaceTypeDefinitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PWR OperState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.11 ApplicationOSInterfaceTypeDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PWR RegionHint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PWR RegionIntensity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PWR SleepState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
PWR PerfState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4 Core(Common)InterfaceFunctions 37
4.1 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
FunctionPrototypePWR CntxtInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
FunctionPrototypeforPWR CntxtDestroy() . . . . . . . . . . . . . . . . . . . . . . . . 38
4.2 HierarchyNavigationFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6
FunctionPrototypeforPWR CntxtGetEntryPoint(). . . . . . . . . . . . . . . . . . . 39
FunctionPrototypeforPWR ObjGetType() . . . . . . . . . . . . . . . . . . . . . . . . . 40
FunctionPrototypeforPWR ObjGetName() . . . . . . . . . . . . . . . . . . . . . . . . 40
FunctionPrototypeforPWR ObjGetParent(). . . . . . . . . . . . . . . . . . . . . . . . 41
FunctionPrototypeforPWR ObjGetChildren(). . . . . . . . . . . . . . . . . . . . . . 41
FunctionPrototypeforPWR CntxtGetObjByName() . . . . . . . . . . . . . . . . . 42
4.3 GroupFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
FunctionPrototypeforPWR GrpCreate() . . . . . . . . . . . . . . . . . . . . . . . . . . 43
FunctionPrototypeforPWR GrpDestroy() . . . . . . . . . . . . . . . . . . . . . . . . . 44
FunctionPrototypeforPWR GrpAddObj() . . . . . . . . . . . . . . . . . . . . . . . . . 44
FunctionPrototypeforPWR GrpRemoveObj() . . . . . . . . . . . . . . . . . . . . . . 45
FunctionPrototypeforPWR GrpGetNumObjs() . . . . . . . . . . . . . . . . . . . . . 45
FunctionPrototypeforPWR GrpGetObjByIndx(). . . . . . . . . . . . . . . . . . . . 46
FunctionPrototypeforPWR GrpDuplicate(). . . . . . . . . . . . . . . . . . . . . . . . 46
FunctionPrototypeforPWR GrpUnion() . . . . . . . . . . . . . . . . . . . . . . . . . . 47
FunctionPrototypeforPWR GrpIntersection() . . . . . . . . . . . . . . . . . . . . . . 47
FunctionPrototypeforPWR GrpDifference() . . . . . . . . . . . . . . . . . . . . . . . 48
FunctionPrototypeforPWR GrpSymDifference() . . . . . . . . . . . . . . . . . . . 49
FunctionPrototypeforPWR CntxtGetGrpByName() . . . . . . . . . . . . . . . . . 49
4.4 AttributeFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
FunctionPrototypeforPWR ObjAttrGetValue() . . . . . . . . . . . . . . . . . . . . . 51
FunctionPrototypeforPWR ObjAttrSetValue() . . . . . . . . . . . . . . . . . . . . . 51
FunctionPrototypeforPWR StatusCreate() . . . . . . . . . . . . . . . . . . . . . . . . 52
FunctionPrototypeforPWR StatusDestroy() . . . . . . . . . . . . . . . . . . . . . . . 53
FunctionPrototypeforPWR StatusPopError() . . . . . . . . . . . . . . . . . . . . . . 53
FunctionPrototypeforPWR StatusClear() . . . . . . . . . . . . . . . . . . . . . . . . . 54
7
FunctionPrototypeforPWR ObjAttrGetValues() . . . . . . . . . . . . . . . . . . . . 54
FunctionPrototypeforPWR ObjAttrSetValues(). . . . . . . . . . . . . . . . . . . . . 56
FunctionPrototypeforPWR ObjAttrIsValid(). . . . . . . . . . . . . . . . . . . . . . . 56
FunctionPrototypeforPWR GrpAttrGetValue() . . . . . . . . . . . . . . . . . . . . . 57
FunctionPrototypeforPWR GrpAttrSetValue() . . . . . . . . . . . . . . . . . . . . . 58
FunctionPrototypeforPWR GrpAttrGetValues() . . . . . . . . . . . . . . . . . . . . 59
FunctionPrototypeforPWR GrpAttrSetValues() . . . . . . . . . . . . . . . . . . . . 60
4.5 MetadataFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
FunctionPrototypeforPWR ObjAttrGetMeta() . . . . . . . . . . . . . . . . . . . . . 62
FunctionPrototypeforPWR ObjAttrSetMeta(). . . . . . . . . . . . . . . . . . . . . . 63
FunctionPrototypeforPWR MetaValueAtIndex() . . . . . . . . . . . . . . . . . . . 64
4.6 StatisticsFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
FunctionPrototypeforPWR ObjGetStat(). . . . . . . . . . . . . . . . . . . . . . . . . . 67
FunctionPrototypeforPWR GrpGetStats(). . . . . . . . . . . . . . . . . . . . . . . . . 67
FunctionPrototypeforPWR ObjCreateStat() . . . . . . . . . . . . . . . . . . . . . . . 68
FunctionPrototypeforPWR GrpCreateStat() . . . . . . . . . . . . . . . . . . . . . . . 69
FunctionPrototypeforPWR StatStart(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
FunctionPrototypeforPWR StatStop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
FunctionPrototypeforPWR StatClear() . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
FunctionPrototypeforPWR StatGetValue() . . . . . . . . . . . . . . . . . . . . . . . . 71
FunctionPrototypeforPWR StatGetValues() . . . . . . . . . . . . . . . . . . . . . . . 72
FunctionPrototypeforPWR StatGetReduce(). . . . . . . . . . . . . . . . . . . . . . . 73
FunctionPrototypeforPWR GrpGetReduce(). . . . . . . . . . . . . . . . . . . . . . . 75
FunctionPrototypeforPWR StatDestroy() . . . . . . . . . . . . . . . . . . . . . . . . . 77
4.7 VersionFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
FunctionPrototypeforPWR GetMajorVersion(). . . . . . . . . . . . . . . . . . . . . 77
8
FunctionPrototypeforPWR GetMinorVersion(). . . . . . . . . . . . . . . . . . . . . 78
4.8 BigListofAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.9 BigListofMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5 High-Level(Common)Functions 85
5.1 ReportFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
FunctionPrototypePWR GetReportByID(). . . . . . . . . . . . . . . . . . . . . . . . . 85
6 Role/SystemInterfaces 87
6.1 OperatingSystem,HardwareInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.1.1 SupportedAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.1.2 SupportedCore(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.1.3 SupportedHigh-Level(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . 91
6.1.4 InterfaceSpecificFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
FunctionPrototypePWR StateTransitDelay() . . . . . . . . . . . . . . . . . . . . . . . 91
6.2 MonitorandControl,HardwareInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.2.1 SupportedAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.2.2 SupportedCore(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.2.3 SupportedHigh-Level(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . 94
6.2.4 InterfaceSpecificFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.3 Application,OperatingSystemInterface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.3.1 SupportedAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.3.2 SupportedCore(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
6.3.3 SupportedHigh-Level(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . 97
6.3.4 InterfaceSpecificFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
FunctionPrototypePWR AppHintCreate() . . . . . . . . . . . . . . . . . . . . . . . . . 97
FunctionPrototypePWR AppHintDestroy() . . . . . . . . . . . . . . . . . . . . . . . . 98
9
FunctionPrototypePWR AppHintStart(). . . . . . . . . . . . . . . . . . . . . . . . . . . 99
FunctionPrototypePWR AppHintStop() . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
FunctionPrototypePWR AppHintProgress(). . . . . . . . . . . . . . . . . . . . . . . . 100
FunctionPrototypePWR SetSleepStateLimit() . . . . . . . . . . . . . . . . . . . . . . 101
FunctionPrototypeforPWR WakeUpLatency() . . . . . . . . . . . . . . . . . . . . . 101
FunctionPrototypePWR RecommendSleepState() . . . . . . . . . . . . . . . . . . . 102
FunctionPrototypeforPWR SetPerfState(). . . . . . . . . . . . . . . . . . . . . . . . . 103
FunctionPrototypeforPWR GetPerfState() . . . . . . . . . . . . . . . . . . . . . . . . 104
FunctionPrototypeforPWR GetSleepState() . . . . . . . . . . . . . . . . . . . . . . . 104
6.4 User,ResourceManagerInterface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.4.1 SupportedAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.4.2 SupportedCore(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.4.3 SupportedHigh-Level(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . 105
6.4.4 InterfaceSpecificFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.5 ResourceManager,OperatingSystemInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.5.1 SupportedAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.5.2 SupportedCore(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6.5.3 SupportedHigh-Level(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . 108
6.5.4 InterfaceSpecificFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6.6 ResourceManager,MonitorandControlInterface . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.6.1 SupportedAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.6.2 SupportedCore(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.6.3 SupportedHigh-Level(Common)Functions . . . . . . . . . . . . . . . . . . . . . . . . 111
6.6.4 InterfaceSpecificFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.7 Administrator,MonitorandControlInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.7.1 SupportedAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
10