VM Guest Library Functions
The vSphere Guest SDK contains the header file
vmGuestLib.h
. This file declares the functions and data
types that you use to call the VM Guest API. The following sections describe the VM Guest
API functions: Calling Context
Functions
The VM Guest API provides a set of functions that initialize and
manipulate the context where the Guest API operates. Before your application can use
the accessor functions to retrieve information about a virtual machine, use the
following functions to initialize the VM Guest API environment.
- Call theVMGuestLib_OpenHandlefunction to obtain a handle for accessing information about the virtual machine. The guest library handle is a parameter to every Guest API function.
- Call theVMGuestLib_UpdateInfofunction to update the information available through the handle.
- Call theVMGuestLib_GetSessionIdfunction to retrieve a session ID.
About Context
Functions
The code block below shows a C language fragment that illustrates the
function calls for initialization. (Code fragments in this section do not perform
error handling. For information about error handling, see VM Guest API Error Codes.)
Initializing the VM Guest API Environment
VMGuestLibHandle glHandle; VMGuestLibError glError; VMSessionId sid = 0; glError = VMGuestLib_OpenHandle(&glHandle); glError = VMGuestLib_UpdateInfo(glHandle); glError = VMGuestLib_GetSessionId(glHandle, &sid);
You can use the session ID to detect changes that invalidate previously
retrieved data. The code block below shows a fragment that illustrates how to use
the session ID to detect stale data. The
ResetStats
function in the following fragment represents application
code to handle the session change.Detecting Stale Data
VMGuestLibHandle glHandle; VMGuestLibError glError; VMSessionId oldSid; VMSessionId newSid; /* [...code here would access data based on an existing, valid session ID (oldSid)...] */ /* Update the library, get the session ID, and compare it to the previous session ID */ glError = VMGuestLib_UpdateInfo(glHandle); glError = GuestLib_GetSessionId(glHandle, &newSid); if (oldSid != newSid) { ResetStats(); oldSid = newSid; }
Table 1 lists the context functions for
creating and releasing handles, updating information, and obtaining session
IDs.
Function
| Description
|
VMGuestLib_OpenHandle
| Gets a handle for use with other VM Guest API
functions. The guest library handle provides a context for accessing
information about the virtual machine. Virtual machine statistics
and state data are associated with a particular guest library
handle, so using one handle does not affect the data associated with
another handle. |
VMGuestLib_CloseHandle
| Releases a handle
acquired with
VMGuestLib_OpenHandle .
|
VMGuestLib_UpdateInfo
| Updates information about the virtual machine. This
information is associated with the VMGuestLibHandle . VMGuestLib_UpdateInfo
requires similar CPU resources to a system call and therefore
can affect performance. If you are concerned about performance,
minimize the number of calls to VMGuestLib_UpdateInfo . If your program uses multiple threads,
each thread must use a different handle. Otherwise, you must
implement a locking scheme around update calls. The VM Guest API
does not implement internal locking around access with a handle.
|
VMGuestLib_GetSessionId
| Retrieves the
VMSessionID for the
current session. Call this function after calling
VMGuestLib_UpdateInfo .
If
VMGuestLib_UpdateInfo
has never been called,
VMGuestLib_GetSessionId
returns
VMGUESTLIB_ERROR_NO_INFO .
|
Accessor Functions
(Virtual Machine)
Accessor functions retrieve information about a virtual machine. When you
call an accessor function, you pass a guest library handle (type
VMGuestLibHandle
) to the function. If the
function is successful, it returns the requested data as an output parameter. The
function return value is an error code (type VMGuestLibError
) that indicates success or failure. The code block
below shows a C language fragment that illustrates calling VMGuestLib_GetCpuLimitMHz
to retrieve the
processor limit available to the virtual machine. Using an Accessor Function
uint32 cpuLimitMHz = 0; glError = VMGuestLib_GetCpuLimitMHz(glHandle, &cpuLimitMHz);
When a call completes successfully, the function
returns the value
VMGUESTLIB_ERROR_SUCCESS
. If
the call is unsuccessful, the error code name contains an appropriate
description. For details, see
VM Guest API Error Codes.
Call
VMGuestLib_UpdateInfo
once to
refresh all statistics before calling an accessor function or a series of
accessor functions.
Function
| Description
|
VMGuestLib_GetCpuLimitMHz
| Retrieves the upper limit
of processor use in MHz available to the virtual machine. For information about
setting the CPU limit, see
Limits and Reservations.
|
VMGuestLib_GetCpuReservationMHz
| Retrieves the minimum
processing power in MHz reserved for the virtual machine. For information about
setting a CPU reservation, see
Limits and Reservations.
|
VMGuestLib_GetCpuShares
| Retrieves the number of
CPU shares allocated to the virtual machine. For information about how an ESXi
host uses CPU shares to manage virtual machine priority, see the
vSphere Resource Management
Guide .
|
VMGuestLib_GetCpuStolenMs
| Retrieves the number of
milliseconds that the virtual machine was in a ready state (able to transition
to a run state), but was not scheduled to run.
|
VMGuestLib_GetCpuUsedMs
| Retrieves the number of
milliseconds during which the virtual machine has used the CPU. This value
includes the time used by the guest operating system and the time used by
virtualization code for tasks for this virtual machine. You can combine this
value with the elapsed time ( VMGuestLib_GetElapsedMs ) to estimate the
effective virtual machine CPU speed. This value is a subset of elapsedMs.
|
VMGuestLib_GetElapsedMs
| Retrieves the number of
milliseconds that have passed in the virtual machine since it last started
running on the server. The count of elapsed time restarts each time the virtual
machine is powered on, resumed, or migrated using VMotion. This value counts
milliseconds, regardless of whether the virtual machine is using processing
power during that time. You can combine this value with the CPU time used by
the virtual machine ( VMGuestLib_GetCpuUsedMs ) to estimate the
effective virtual machine CPU speed. cpuUsedMS is a subset of this value.
|
VMGuestLib_GetHostProcessorSpeed
| Retrieves the speed of
the ESXi host’s physical CPU in MHz.
|
VMGuestLib_GetMemActiveMB
| Retrieves the amount of
memory the virtual machine is actively using—its estimated working set size.
|
VMGuestLib_GetMemBalloonedMB
| Retrieves the amount of
memory that has been reclaimed from this virtual machine by the vSphere memory
balloon driver, which is also called the “vmmemctl” driver.
|
VMGuestLib_GetMemLimitMB
| Retrieves the upper limit
of memory that is available to the virtual machine. For information about
setting a memory limit, see
Limits and Reservations.
|
VMGuestLib_GetMemMappedMB
| Retrieves the amount of
memory that is allocated to the virtual machine. Memory that is ballooned,
swapped, or has never been accessed is excluded.
|
VMGuestLib_GetMemOverheadMB
| Retrieves the amount of
“overhead” memory associated with this virtual machine that is currently
consumed on the host system. Overhead memory is additional memory that is
reserved for data structures required by the virtualization layer.
|
VMGuestLib_GetMemReservationMB
| Retrieves the minimum
amount of memory that is reserved for the virtual machine. For information
about setting a memory reservation, see
Limits and Reservations.
|
VMGuestLib_GetMemSharedMB
| Retrieves the amount of
physical memory associated with this virtual machine that is copy-on-write
(COW) shared on the host.
|
VMGuestLib_GetMemSharedSavedMB
| Retrieves the estimated
amount of physical memory on the host saved from copy-on-write (COW) shared
guest physical memory.
|
VMGuestLib_GetMemShares
| Retrieves the number of memory shares allocated to the
virtual machine, as an unsigned 32-bit value. If the value cannot
fit in 32-bits, this call returns an error. In that case, use
VMGuestLib_GetMemShares64 instead. For
information about how ESXi hosts use memory shares to manage virtual
machine priority, see the vSphere
Resource Management Guide . |
VMGuestLib_GetMemShares64
| This call was added in vSphere 7.0 to get the 64-bit
value of memory shares allocated to the virtual machine. |
VMGuestLib_GetMemSwappedMB
| Retrieves the amount of
memory that has been reclaimed from this virtual machine by transparently
swapping guest memory to disk.
|
VMGuestLib_GetMemTargetSizeMB
| Retrieves the size of the
target memory allocation for this virtual machine.
|
VMGuestLib_GetMemUsedMB
| Retrieves the estimated
amount of physical host memory currently consumed for this virtual machine's
physical memory.
|
VMGuestLib_GetResourcePoolPath
| Retrieves the path name of the resource pool
affiliated with the virtual machine on the ESXi host where it is
running. VMGuestLib_GetResourcePoolPath
uses an additional parameter to determine the size of the path
name output string buffer. VMGuestLibError
VmGuestLib_GetResourcePoolPath(
VMGuestLibHandle handle,
size_t *bufferSize,
char *pathBuffer ); handle is an input parameter specifying the guest
library handle. bufferSize is an
input/output parameter. It is a pointer to the size of the
pathBuffer in bytes. If bufferSize is not large enough to
accommodate the path (including a NULL terminator), the function
returns VMGUESTLIB_ERROR_BUFFER_TOO_SMALL. In this case, the
function uses the bufferSize parameter to return the number of
bytes required for the string. pathBuffer is an
output parameter. It is a pointer to a buffer that receives the
resource pool path string. The path string is NULL-terminated.
For information about using
resource pools, see the vSphere
Resource Management Guide . |
For more information about ESXi resource
management, see the
vSphere Resource Management Guide
,
available on the VMware Web site.
Limits and
Reservations
You use the Guest API to retrieve information
about limits and reservations for CPU and memory. To set limits and
reservations, you can use the vSphere (Web) Client or the vSphere API. Setting
limits and reservations on a virtual machine ensures that resources are
available to that machine and to other virtual machines that draw resources
from the same resource pool.
To use the vSphere Client to set limits or
reservations:
- In the vSphere Client window, click the Resource Allocation tab.
- In either the CPU or Memory section, click Edit.
- In the Virtual Machine Properties Window, click the Resources tab.
- Select either the CPU or Memory setting.
- Use the slider controls to set limits or reservations.
For more information, see online help for the
vSphere Client.
To use the vSphere API to set limits or
reservations, call the ReconfigVM_Task method. In the method call, use the
VirtualMachineConfigSpec data object to set the cpuAllocation or
memoryAllocation property. These properties are of type ResourceAllocationInfo,
which has limit and reservation properties. For more information, see the
VMware vSphere API Reference Documentation.