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