AMSVIS(1)

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

SYNOPSIS
/usr/bin/amsvis -l [-u SEC] [-v]

/usr/bin/amsvis -r [-c] [--hosts HOSTNAME[:PORT][,...]] [-u SEC] [-v]

/usr/bin/amsvis -r -s [-p PORT] [-v]

/usr/bin/amsvis -h

DESCRIPTION
This program helps visualize operating system data as it relates to running within an Active Memory Sharing (AMS) environment. The tool can be run both locally or remotely. Additionally, it can be run as a local data server, without a graphical user interface (GUI), to provide data for running the GUI remotely.

When the GUI is run for a single host a number of panels will be displayed for the operating system, these are the System, IO Bus Memory, and IO Devices panels.

When the GUI is run for multiple hosts only the System Panel will be displayed for each of the hosts. This is achieved by specifying multiple systems on the command-line via the --hosts option.

  System Panel
In an AMS environment, the amount of memory available will change as memory is loaned to other partitions by the Cooperative Memory Manager (CMM) module. This panel will show how the total amount of memory provided to the system is being utilized. The graph displays a histogram showing the loaned, used, and free memory; the most recent value is displayed to the right.

For the system memory panel there are six values displays beneath the graph, they are:

Total
    This value, expressed in kilobytes, is the maximum amount of memory available to the operating system. This value represents the graph's total height.

Loaned
    This is the amount of memory, in kilobytes, that the operating system has temporarily given back to the platform firmware to be used by other partitions. This value fluctuates to meet the demands of all of the partitions in the shared memory pool of an AMS environment.

Used
    This value, displayed in kilobytes, is the amount of system memory in-use, not including buffers or cache.

Free
    This value, displayed in kilobytes, is the amount of system memory which is unused.

Faults
    A fault occurs when an attempt to access memory is made where the platform firmware must suspend the partition and request data from disk. This value is a sum of the number of faults since the system was booted. Increases in this value indicate contention for memory between partitions in the AMS environment.

Fault time
    This value is a running sum of the amount of time, since boot time, that the operating system has been suspended by platform firmware to process faults.

  IO Bus Memory Panel
This panel shows how the memory given to the operating system for IO operations is being used by the bus and the devices present on the bus.

The graph will display a histogram for the spare and in use memory with the most recent value on the right side of the graph. The graph is overlayed with a dashed line corresponding in color to the high water value and another dashed line for the reserve pool.

For the system's IO bus memory panel there are eight values displayed beneath the graph, they are:

Entitled
    The entitled memory is a specific amount of memory given to the operating system that will be available to be mapped for IO operations; this guarantee is maintained by the platform firmware and can be tuned through the HMC or IVM depending on the particular environment. This value is displayed in kilobytes. The amount of entitled memory is changed by the HMC or IVM in response to hot-plug events or explicit tuning. This value represents the graph's total height.

Desired
    Each device in the system that requires memory for mapping IO operations will specify an amount of memory which is desired for optimal performance. This value is the sum of the requests made by individual devices on the bus and is measured in kilobytes.

High water
    This value, measured in kilobytes, represents the largest amount of memory mapped at any one point in time since the system was booted or the field was last reset. This value can be reset by writing a '0' to the file /sys/bus/vio/cmo_high.

In use
    This value represents the amount of memory, in kilobytes, that is currently mapped by device drivers for IO operations.

Spare
    This value represents the amount of memory, in kilobytes, kept unused to handle hot-plug events, entitlement rebalancing between devices, and module loading.

Reserve pool
    The entitled memory is split into two pools, the first of which is the reserve pool. This value, expressed in kilobytes, represents the amount of memory guaranteed to individual devices on the bus.

Excess pool
    This pool contains any amount of entitled memory not placed in the reserve pool; the value is displayed in kilobytes. Any device can map memory from this pool for IO operations, after having used up its own allocation from the reserve pool, until the excess pool is exhausted.

Excess free
    This value represents the amount of memory, in kilobytes, currently available for devices to use from the excess pool.

  IO Devices Panel
There will be one panel for each VIO device present in the system that maps memory for IO operations. Panels will be added and removed for devices as a result of DLPAR hot-plug operations and module load/unload events.

The graph will display a histogram for the values of allocated memory, with the most recent value on the right side of the graph. The graph is overlaid with a dashed line that represents the latest value of entitled memory. The area of the graph above the dashed line represents the excess Pool of IO bus memory, any portion of this area that is grayed out has been mapped by other devices and is currently unavailable to the particular device.

For each device panel there are five values displayed beneath the graph, they are:

Device Name
    The name displayed for the device is its location on the bus.

Entitled
    The amount of memory, in kilobytes, that the device is guaranteed that it may map for IO operations. The bus will guarantee that the device can map this number of kilobytes of memory for IO operations. The allocation of this entitled memory is made to the device from the bus' reserve pool.

Desired
    The amount of memory, in kilobytes, that the device has requested from the bus to provide optimal performance. The amount of entitled memory will not exceed this amount. The device may receive a memory entitlement less than its desired level in cases where resources are limited.

Allocated
    The amount of memory, in kilobytes, that the device has currently mapped for IO operations.

Allocs failed
    When the amount of memory allocated has exhausted both the entitled memory and the bus' excess pool, memory mapping failures will occur. For each failed attempt, the value displayed here will increase by 1. Large changes in this value would indicate resource contention that may require system tuning. The device drivers are written such that these failures, while impacting performance, do not impede functionality. To reset this counter, the value '0' can be written to the file /sys/bus/vio/devices/<device name>/cmo_allocs_failed.

OPTIONS

-c, --client
    When running with remote data, function as the client to display the GUI. [default]

-h, --help
    Display a help message and exit.

--hosts=HOSTNAME[:PORT][,HOSTNAME[:PORT],...]
    Hostname(s) with optional port number, the default is localhost:50000. If more than one hostname is specified, only the System Panel is displayed for each host.

-l, --local
    Run on the local system to gather data and display it in a GUI. [default]

-pPORT, --port=PORT
    Network port number while running as a server, the default is 50000.

-r, --remote
    Run as a network client/server to gather data or display it in a GUI.

-s, --server
    When running remotely, function as the server to provide AMS data to clients. No GUI is displayed.

-uSECONDS, --update=SECONDS
    Specify the number of seconds between updates of the GUI, the default is 5.

-v, --verbose
    Enable verbose output.

EXAMPLES
Running locally:

amsvis --local --update=10
    Display the AMS data for the local system, providing an update every 10 seconds.

Running remotely:

amsvis --remote --server --port=50000
    Start a server for AMS data on port 50000.

amsvis --remote --client --hostname=server.example.org --port=50000
    Display the AMS data from the remote system, providing an update every 10 seconds.

FILES
/proc/sys/meminfo
/proc/ppc64/lparcfg
/sys/devices/system/cmm/cmm0/
/sys/bus/vio/cmo_*
/sys/bus/vio/devices/*/cmo_*

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

VERSION
$Revision: 1.1 $