1*d3c97224SAlexander Kolbasov# 2*d3c97224SAlexander Kolbasov# CDDL HEADER START 3*d3c97224SAlexander Kolbasov# 4*d3c97224SAlexander Kolbasov# The contents of this file are subject to the terms of the 5*d3c97224SAlexander Kolbasov# Common Development and Distribution License (the "License"). 6*d3c97224SAlexander Kolbasov# You may not use this file except in compliance with the License. 7*d3c97224SAlexander Kolbasov# 8*d3c97224SAlexander Kolbasov# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9*d3c97224SAlexander Kolbasov# or http://www.opensolaris.org/os/licensing. 10*d3c97224SAlexander Kolbasov# See the License for the specific language governing permissions 11*d3c97224SAlexander Kolbasov# and limitations under the License. 12*d3c97224SAlexander Kolbasov# 13*d3c97224SAlexander Kolbasov# When distributing Covered Code, include this CDDL HEADER in each 14*d3c97224SAlexander Kolbasov# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15*d3c97224SAlexander Kolbasov# If applicable, add the following below this CDDL HEADER, with the 16*d3c97224SAlexander Kolbasov# fields enclosed by brackets "[]" replaced with your own identifying 17*d3c97224SAlexander Kolbasov# information: Portions Copyright [yyyy] [name of copyright owner] 18*d3c97224SAlexander Kolbasov# 19*d3c97224SAlexander Kolbasov# CDDL HEADER END 20*d3c97224SAlexander Kolbasov# 21*d3c97224SAlexander Kolbasov 22*d3c97224SAlexander Kolbasov# 23*d3c97224SAlexander Kolbasov# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. 24*d3c97224SAlexander Kolbasov# 25*d3c97224SAlexander Kolbasov 26*d3c97224SAlexander Kolbasov# 27*d3c97224SAlexander Kolbasov# Sun::Solaris::Pg documentation 28*d3c97224SAlexander Kolbasov# 29*d3c97224SAlexander Kolbasov 30*d3c97224SAlexander Kolbasov=head1 NAME 31*d3c97224SAlexander Kolbasov 32*d3c97224SAlexander KolbasovSolaris::Pg - Perl interface to Processor Group kstats 33*d3c97224SAlexander Kolbasov 34*d3c97224SAlexander Kolbasov=head1 SYNOPSYS 35*d3c97224SAlexander Kolbasov 36*d3c97224SAlexander Kolbasov use Solaris::Pg; 37*d3c97224SAlexander Kolbasov 38*d3c97224SAlexander Kolbasov $p = Solaris::Pg->new(-cpudata=> 1, -tags=> 1, -swload=> 1); 39*d3c97224SAlexander Kolbasov 40*d3c97224SAlexander Kolbasov @pgs = $p->all(); 41*d3c97224SAlexander Kolbasov 42*d3c97224SAlexander Kolbasov @pgs_depth = $p->all_depth_first(); 43*d3c97224SAlexander Kolbasov 44*d3c97224SAlexander Kolbasov @pgs_breadth = $p->all_breadth_first(); 45*d3c97224SAlexander Kolbasov 46*d3c97224SAlexander Kolbasov @leaves = $p->leaves(); 47*d3c97224SAlexander Kolbasov 48*d3c97224SAlexander Kolbasov $root = $p->root; 49*d3c97224SAlexander Kolbasov 50*d3c97224SAlexander Kolbasov $p->update(); 51*d3c97224SAlexander Kolbasov 52*d3c97224SAlexander Kolbasov $leaf = $leaves[0]; 53*d3c97224SAlexander Kolbasov 54*d3c97224SAlexander Kolbasov $name = $p->sh_name($leaf); 55*d3c97224SAlexander Kolbasov 56*d3c97224SAlexander Kolbasov @names = $p->sharing_relationships(); 57*d3c97224SAlexander Kolbasov 58*d3c97224SAlexander Kolbasov @tags = $p->tags($leaf); 59*d3c97224SAlexander Kolbasov 60*d3c97224SAlexander Kolbasov $p1 = Solaris::Pg->new(-cpudata=> 1, -tags=> 1, -swload=> 1); 61*d3c97224SAlexander Kolbasov 62*d3c97224SAlexander Kolbasov if ($p->has_utilization()) { 63*d3c97224SAlexander Kolbasov $utilization = $p->utilization($p1, $leaf); 64*d3c97224SAlexander Kolbasov $capacity = $p->capacity($p1, $leaf); 65*d3c97224SAlexander Kolbasov $accuracy = $p->accuracy($p1, $leaf); 66*d3c97224SAlexander Kolbasov $tdelta = $p->tdelta($p1); 67*d3c97224SAlexander Kolbasov } 68*d3c97224SAlexander Kolbasov 69*d3c97224SAlexander Kolbasov $sw_utilization = $p->sw_utilization($p1, $leaf);) 70*d3c97224SAlexander Kolbasov 71*d3c97224SAlexander Kolbasov 72*d3c97224SAlexander Kolbasov=head1 DESCRIPTION 73*d3c97224SAlexander Kolbasov 74*d3c97224SAlexander KolbasovThe Solaris::Pg module provides an interface to the Solaris PG information 75*d3c97224SAlexander Kolbasovavailable through B<pg> and B<pg_cpu> kstats. The module provides an object 76*d3c97224SAlexander Kolbasovoriented interface. 77*d3c97224SAlexander Kolbasov 78*d3c97224SAlexander Kolbasov=head1 METHODS 79*d3c97224SAlexander Kolbasov 80*d3c97224SAlexander Kolbasov=head2 new 81*d3c97224SAlexander Kolbasov 82*d3c97224SAlexander KolbasovCreate a new Pg instance. The new() function accepts arguments in the form of a 83*d3c97224SAlexander Kolbasovhash. The following subarguments are supported: 84*d3c97224SAlexander Kolbasov 85*d3c97224SAlexander Kolbasov=over 86*d3c97224SAlexander Kolbasov 87*d3c97224SAlexander Kolbasov=item -cpudata 88*d3c97224SAlexander Kolbasov 89*d3c97224SAlexander KolbasovCollect per-CPU data from kstats if this is True. 90*d3c97224SAlexander Kolbasov 91*d3c97224SAlexander Kolbasov=item -tags 92*d3c97224SAlexander Kolbasov 93*d3c97224SAlexander KolbasovMatch PGs to physical relationships if this is True. 94*d3c97224SAlexander Kolbasov 95*d3c97224SAlexander Kolbasov=item -swload 96*d3c97224SAlexander Kolbasov 97*d3c97224SAlexander KolbasovCollect software CPU load if this is True. 98*d3c97224SAlexander Kolbasov 99*d3c97224SAlexander Kolbasov=back 100*d3c97224SAlexander Kolbasov 101*d3c97224SAlexander Kolbasov=head2 root 102*d3c97224SAlexander Kolbasov 103*d3c97224SAlexander KolbasovReturn ID of the root of Processor Group hierarchy. 104*d3c97224SAlexander Kolbasov 105*d3c97224SAlexander Kolbasov=head2 all 106*d3c97224SAlexander Kolbasov 107*d3c97224SAlexander KolbasovReturn list of all PGs sorted by ID. 108*d3c97224SAlexander Kolbasov 109*d3c97224SAlexander Kolbasov=head2 all_depth_first() 110*d3c97224SAlexander Kolbasov 111*d3c97224SAlexander KolbasovReturn list of all PGs sorted by walking the PG hierarchy depth first, starting 112*d3c97224SAlexander Kolbasovfrom root. 113*d3c97224SAlexander Kolbasov 114*d3c97224SAlexander Kolbasov=head2 all_breadth_first() 115*d3c97224SAlexander Kolbasov 116*d3c97224SAlexander KolbasovReturn list of all PGs sorted by walking the PG hierarchy breadth first, 117*d3c97224SAlexander Kolbasovstarting from root. 118*d3c97224SAlexander Kolbasov 119*d3c97224SAlexander Kolbasov=head2 cpus(PG) 120*d3c97224SAlexander Kolbasov 121*d3c97224SAlexander KolbasovReturn list of all CPUs in the PG specified. The list is sorted by CPU ID. 122*d3c97224SAlexander Kolbasov 123*d3c97224SAlexander Kolbasov=head2 generation([PG]) 124*d3c97224SAlexander Kolbasov 125*d3c97224SAlexander KolbasovReturn the generation number for the given PG. Without arguments, return the 126*d3c97224SAlexander Kolbasovgeneration number for the whole snapshot. Different generation number means that 127*d3c97224SAlexander KolbasovPG configuration may have changed. 128*d3c97224SAlexander Kolbasov 129*d3c97224SAlexander Kolbasov=head2 parent(PG) 130*d3c97224SAlexander Kolbasov 131*d3c97224SAlexander KolbasovReturn parent ID or undef if there is no parent. 132*d3c97224SAlexander Kolbasov 133*d3c97224SAlexander Kolbasov=head2 children(PG) 134*d3c97224SAlexander Kolbasov 135*d3c97224SAlexander KolbasovReturn list of children for the PG. 136*d3c97224SAlexander Kolbasov 137*d3c97224SAlexander Kolbasov=head2 is_leaf(PG) 138*d3c97224SAlexander Kolbasov 139*d3c97224SAlexander KolbasovReturns T iff PG is leaf. 140*d3c97224SAlexander Kolbasov 141*d3c97224SAlexander Kolbasov=head2 leaves 142*d3c97224SAlexander Kolbasov 143*d3c97224SAlexander KolbasovReturns list of leaf PGs. 144*d3c97224SAlexander Kolbasov 145*d3c97224SAlexander Kolbasov=head2 level(PG) 146*d3c97224SAlexander Kolbasov 147*d3c97224SAlexander KolbasovReturn the numeric level of PG in the hierarchy, starting from root which has 148*d3c97224SAlexander Kolbasovlevel zero. 149*d3c97224SAlexander Kolbasov 150*d3c97224SAlexander Kolbasov=head2 sh_name(PG) 151*d3c97224SAlexander Kolbasov 152*d3c97224SAlexander KolbasovReturns sharing name for the PG. 153*d3c97224SAlexander Kolbasov 154*d3c97224SAlexander Kolbasov=head2 sharing_relationships([PG], ...) 155*d3c97224SAlexander Kolbasov 156*d3c97224SAlexander KolbasovWithout any arguments, returns the list of sharing relationships in the 157*d3c97224SAlexander Kolbasovsnapshot. Relationships are sorted by the level in the hierarchy If any PGs are 158*d3c97224SAlexander Kolbasovgiven on the command line, only return sharing relationships for given PGs, but 159*d3c97224SAlexander Kolbasovstill keep them sorted. 160*d3c97224SAlexander Kolbasov 161*d3c97224SAlexander Kolbasov=head2 tags(PG) 162*d3c97224SAlexander Kolbasov 163*d3c97224SAlexander KolbasovReturn list of strings describing physical relationships ('core', 'chip') for the given PG. 164*d3c97224SAlexander Kolbasov 165*d3c97224SAlexander Kolbasov=head2 update() 166*d3c97224SAlexander Kolbasov 167*d3c97224SAlexander KolbasovUpdate utilization and generation data in the PG snapshot. 168*d3c97224SAlexander Kolbasov 169*d3c97224SAlexander Kolbasov=head2 has_utilization(PG) 170*d3c97224SAlexander Kolbasov 171*d3c97224SAlexander KolbasovReturns True if given PG hasd data about hardware utilization. 172*d3c97224SAlexander Kolbasov 173*d3c97224SAlexander Kolbasov=head2 utilization(PGOBJ, PG) 174*d3c97224SAlexander Kolbasov 175*d3c97224SAlexander KolbasovReturn numeric utilization for the time interval represented by two PG objects 176*d3c97224SAlexander Kolbasovfor the given PG. Utilization is a difference in utilization value between two 177*d3c97224SAlexander Kolbasovsnapshots. The given PG must belong to the same generation in both snapshots. 178*d3c97224SAlexander KolbasovReturns B<undef> if utilization can not be obtained. 179*d3c97224SAlexander Kolbasov 180*d3c97224SAlexander Kolbasov=head2 sw_utilization(PGOBJ, PG) 181*d3c97224SAlexander Kolbasov 182*d3c97224SAlexander KolbasovReturn numeric software utilization for the time interval represented by two PG 183*d3c97224SAlexander Kolbasovobjects for the given PG. Utilization is a difference in utilization value 184*d3c97224SAlexander Kolbasovbetween two snapshots. The given PG must belong to the same generation in both 185*d3c97224SAlexander Kolbasovsnapshots. Returns B<undef> if utilization can not be obtained. Software 186*d3c97224SAlexander Kolbasovutilization is combined CPU load for all CPUs in the PG. Returns B<undef> if 187*d3c97224SAlexander Kolbasovutilization can not be obtained. 188*d3c97224SAlexander Kolbasov 189*d3c97224SAlexander Kolbasov=head2 sw_utilization(PGOBJ, PG, CPU) 190*d3c97224SAlexander Kolbasov 191*d3c97224SAlexander KolbasovReturn utilization for the PG for a given CPU in a given PG. Utilization is a 192*d3c97224SAlexander Kolbasovdifference in utilization value between two snapshots. We can only compare 193*d3c97224SAlexander Kolbasovutilization between PGs having the same generation ID. Returns B<undef> if 194*d3c97224SAlexander Kolbasovutilization can not be obtained. 195*d3c97224SAlexander Kolbasov 196*d3c97224SAlexander Kolbasov=head2 capacity(PGOBJ, PG) 197*d3c97224SAlexander Kolbasov 198*d3c97224SAlexander KolbasovReturn numeric capacity for the time interval represented by two PG objects for 199*d3c97224SAlexander Kolbasovthe given PG. Note that the actual capacity is the maximum of all capacities 200*d3c97224SAlexander Kolbasovacross all PGs of this type.The given PG must belong to the same generation in 201*d3c97224SAlexander Kolbasovboth snapshots. Returns B<undef> if capacities can not be obtained. 202*d3c97224SAlexander Kolbasov 203*d3c97224SAlexander Kolbasov=head2 accuracy(PGOBJ, PG) 204*d3c97224SAlexander Kolbasov 205*d3c97224SAlexander KolbasovReturn accuracy of utilization calculation between two snapshots The accuracy is 206*d3c97224SAlexander Kolbasovdetermined based on the total time spent running and not running the counters. 207*d3c97224SAlexander KolbasovIf T1 is the time counters were running during the period and T2 is the time 208*d3c97224SAlexander Kolbasovthey were turned off, the accuracy is T1 / (T1 + T2), expressed in percentages. 209*d3c97224SAlexander Kolbasov 210*d3c97224SAlexander Kolbasov=head2 tdelta(PGOBJ, PG) 211*d3c97224SAlexander Kolbasov 212*d3c97224SAlexander KolbasovReturn time interval between two snapshots for the given PG. The time is expressed in seconds and is a floating-point number. 213*d3c97224SAlexander Kolbasov 214*d3c97224SAlexander Kolbasov=head2 EXPORT 215*d3c97224SAlexander Kolbasov 216*d3c97224SAlexander KolbasovNone by default. 217*d3c97224SAlexander Kolbasov 218*d3c97224SAlexander Kolbasov=head1 SEE ALSO 219*d3c97224SAlexander Kolbasov 220*d3c97224SAlexander KolbasovL<pginfo(1)>, L<pgstat(1)> 221*d3c97224SAlexander Kolbasov 222*d3c97224SAlexander Kolbasov=cut 223*d3c97224SAlexander Kolbasov 224