1AMSVIS(1)                Linux on Power Service Tools                AMSVIS(1)
2
3
4

NAME

6       amsvis  -  view Active Memory Sharing (AMS) metrics in a GUI locally or
7       remotely.
8

SYNOPSIS

10       /usr/bin/amsvis -l [-u SEC] [-v]
11
12       /usr/bin/amsvis -r [-c] [--hosts HOSTNAME[:PORT][,...]] [-u SEC] [-v]
13
14       /usr/bin/amsvis -r -s [-p PORT] [-v]
15
16       /usr/bin/amsvis -h
17

DESCRIPTION

19       This program helps visualize operating system data  as  it  relates  to
20       running  within  an  Active Memory Sharing (AMS) environment.  The tool
21       can be run both locally or remotely. Additionally, it can be run  as  a
22       local data server, without a graphical user interface (GUI), to provide
23       data for running the GUI remotely.
24
25       When the GUI is run for a single host a number of panels will  be  dis‐
26       played  for  the operating system, these are the System, IO Bus Memory,
27       and IO Devices panels.
28
29       When the GUI is run for multiple hosts only the System  Panel  will  be
30       displayed for each of the hosts.  This is achieved by specifying multi‐
31       ple systems on the command-line via the --hosts option.
32
33   System Panel
34       In an AMS environment, the amount of memory available  will  change  as
35       memory  is loaned to other partitions by the Cooperative Memory Manager
36       (CMM) module.  This panel will show how the total amount of memory pro‐
37       vided  to the system is being utilized.  The graph displays a histogram
38       showing the loaned, used, and free memory; the  most  recent  value  is
39       displayed to the right.
40
41       For  the  system memory panel there are six values displays beneath the
42       graph, they are:
43
44       Total  This value, expressed in kilobytes, is  the  maximum  amount  of
45              memory available to the operating system.  This value represents
46              the graph's total height.
47
48       Loaned This is the amount of memory, in kilobytes, that  the  operating
49              system has temporarily given back to the platform firmware to be
50              used by other partitions.  This value  fluctuates  to  meet  the
51              demands of all of the partitions in the shared memory pool of an
52              AMS environment.
53
54       Used   This value, displayed in kilobytes, is the amount of system mem‐
55              ory in-use, not including buffers or cache.
56
57       Free   This value, displayed in kilobytes, is the amount of system mem‐
58              ory which is unused.
59
60       Faults A fault occurs when an attempt to access memory  is  made  where
61              the  platform  firmware  must  suspend the partition and request
62              data from disk.  This value is a sum of  the  number  of  faults
63              since  the  system was booted.  Increases in this value indicate
64              contention for memory between partitions in the AMS environment.
65
66       Fault time
67              This value is a running sum of the amount of  time,  since  boot
68              time,  that  the operating system has been suspended by platform
69              firmware to process faults.
70
71   IO Bus Memory Panel
72       This panel shows how the memory given to the operating  system  for  IO
73       operations is being used by the bus and the devices present on the bus.
74
75       The graph will display a histogram for the spare and in use memory with
76       the most recent value on the right side of the  graph.   The  graph  is
77       overlayed  with  a dashed line corresponding in color to the high water
78       value and another dashed line for the reserve pool.
79
80       For the system's IO bus memory panel there are eight  values  displayed
81       beneath the graph, they are:
82
83       Entitled
84              The  entitled memory is a specific amount of memory given to the
85              operating system that will be available  to  be  mapped  for  IO
86              operations;   this  guarantee  is  maintained  by  the  platform
87              firmware and can be tuned through the HMC or  IVM  depending  on
88              the  particular  environment.   This value is displayed in kilo‐
89              bytes.  The amount of entitled memory is changed by the  HMC  or
90              IVM  in  response  to  hot-plug events or explicit tuning.  This
91              value represents the graph's total height.
92
93       Desired
94              Each device in the system that requires memory  for  mapping  IO
95              operations will specify an amount of memory which is desired for
96              optimal performance.  This value is the sum of the requests made
97              by individual devices on the bus and is measured in kilobytes.
98
99       High water
100              This value, measured in kilobytes, represents the largest amount
101              of memory mapped at any one point in time since the  system  was
102              booted  or the field was last reset.  This value can be reset by
103              writing a '0' to the file /sys/bus/vio/cmo_high.
104
105       In use This value represents the amount of memory, in  kilobytes,  that
106              is currently mapped by device drivers for IO operations.
107
108       Spare  This  value  represents the amount of memory, in kilobytes, kept
109              unused  to  handle  hot-plug  events,  entitlement   rebalancing
110              between devices, and module loading.
111
112       Reserve pool
113              The  entitled memory is split into two pools, the first of which
114              is the reserve pool.  This value, expressed in kilobytes, repre‐
115              sents  the  amount of memory guaranteed to individual devices on
116              the bus.
117
118       Excess pool
119              This pool contains any amount of entitled memory not  placed  in
120              the  reserve  pool;  the  value  is displayed in kilobytes.  Any
121              device can map memory from this pool for  IO  operations,  after
122              having  used  up its own allocation from the reserve pool, until
123              the excess pool is exhausted.
124
125       Excess free
126              This value represents the amount of memory, in  kilobytes,  cur‐
127              rently available for devices to use from the excess pool.
128
129   IO Devices Panel
130       There  will be one panel for each VIO device present in the system that
131       maps memory for IO operations.  Panels will be added  and  removed  for
132       devices as a result of DLPAR hot-plug operations and module load/unload
133       events.
134
135       The graph will display a histogram for the values of allocated  memory,
136       with  the  most recent value on the right side of the graph.  The graph
137       is overlaid with a dashed line that  represents  the  latest  value  of
138       entitled  memory.   The  area of the graph above the dashed line repre‐
139       sents the excess Pool of IO bus memory, any portion of this  area  that
140       is  grayed  out  has  been  mapped  by  other  devices and is currently
141       unavailable to the particular device.
142
143       For each device panel there  are  five  values  displayed  beneath  the
144       graph, they are:
145
146       Device Name
147              The name displayed for the device is its location on the bus.
148
149       Entitled
150              The  amount  of memory, in kilobytes, that the device is guaran‐
151              teed that it may map for IO operations.  The bus will  guarantee
152              that  the  device can map this number of kilobytes of memory for
153              IO operations.  The allocation of this entitled memory  is  made
154              to the device from the bus' reserve pool.
155
156       Desired
157              The  amount  of  memory,  in  kilobytes,  that  the  device  has
158              requested from the bus  to  provide  optimal  performance.   The
159              amount  of  entitled  memory  will  not exceed this amount.  The
160              device may receive a memory entitlement less  than  its  desired
161              level in cases where resources are limited.
162
163       Allocated
164              The  amount  of  memory,  in kilobytes, that the device has cur‐
165              rently mapped for IO operations.
166
167       Allocs failed
168              When the amount of memory allocated has exhausted both the enti‐
169              tled  memory  and  the bus' excess pool, memory mapping failures
170              will occur.  For each failed attempt, the value  displayed  here
171              will  increase by 1.  Large changes in this value would indicate
172              resource contention that may require system tuning.  The  device
173              drivers  are  written  such that these failures, while impacting
174              performance,  do  not  impede  functionality.   To  reset   this
175              counter,   the   value   '0'   can   be   written  to  the  file
176              /sys/bus/vio/devices/<device name>/cmo_allocs_failed.
177

OPTIONS

179       -c, --client
180              When running with remote data, function as the client to display
181              the GUI. [default]
182
183       -h, --help
184              Display a help message and exit.
185
186       --hosts=HOSTNAME[:PORT][,HOSTNAME[:PORT],...]
187              Hostname(s)  with  optional  port  number, the default is local‐
188              host:50000.  If more than one hostname is  specified,  only  the
189              System Panel is displayed for each host.
190
191       -l, --local
192              Run  on the local system to gather data and display it in a GUI.
193              [default]
194
195       -pPORT, --port=PORT
196              Network port number while running as a server,  the  default  is
197              50000.
198
199       -r, --remote
200              Run as a network client/server to gather data or display it in a
201              GUI.
202
203       -s, --server
204              When running remotely, function as the  server  to  provide  AMS
205              data to clients.  No GUI is displayed.
206
207       -uSECONDS, --update=SECONDS
208              Specify  the  number  of seconds between updates of the GUI, the
209              default is 5.
210
211       -v, --verbose
212              Enable verbose output.
213

EXAMPLES

215       Running locally:
216
217       amsvis --local --update=10
218              Display the AMS data for the local system, providing  an  update
219              every 10 seconds.
220
221       Running remotely:
222
223       amsvis --remote --server --port=50000
224              Start a server for AMS data on port 50000.
225
226       amsvis --remote --client --hostname=server.example.org --port=50000
227              Display the AMS data from the remote system, providing an update
228              every 10 seconds.
229

FILES

231       /proc/sys/meminfo
232       /proc/ppc64/lparcfg
233       /sys/devices/system/cmm/cmm0/
234       /sys/bus/vio/cmo_*
235       /sys/bus/vio/devices/*/cmo_*
236

BUGS

238       Though not a bug, the name of a number of files and  variables  are  of
239       the form cmo* rather than Active Memory Sharing (AMS).  The kernel code
240       for this feature was committed under the name Cooperative Memory  Over‐
241       commitment  (CMO).   Kernel  support is enabled using the kernel config
242       option CONFIG_PPC_SMLPAR, for shared memory logical partition support.
243

VERSION

245       $Revision: 1.1 $
246
247
248
249Linux                            January 2009                        AMSVIS(1)
Impressum