Files @ 763922b5834e
Branch filter:

Location: vmkdrivers/BLD/build/HEADERS/vmkapi-current-all-public/vmkernel64/release/core/vmkapi_mempool.h - annotation

unknown
ESXi-5.0-GA
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
763922b5834e
/* **********************************************************
 * Copyright 2007 - 2010 VMware, Inc.  All rights reserved.
 * **********************************************************/

/*
 * @VMKAPIMOD_LICENSE@
 */

/*
 ***********************************************************************
 * MemPool                                                        */ /**
 * \defgroup MemPool Managed Machine-Page Pools
 *
 * Memory pools are used to manage machine memory resources for admission 
 * control and for better resource tracking. Each MemPool entity represents
 * a set of limits that the internal resource management algorithms honor.
 * The functions here provide operations to add such pools starting at
 * the root represented by kmanaged group and and also introduces APIs 
 * to allocate/free memory based on the restrictions of the mempool.
 * 
 * @{
 ***********************************************************************
 */
 
#ifndef _VMKAPI_MEMPOOL_H_
#define _VMKAPI_MEMPOOL_H_

/** \cond never */
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
#error This vmkapi file should never be included directly but only via vmkapi.h
#endif
/** \endcond never */

/** \brief Memory pool with no limit. */
#define VMK_MEMPOOL_NO_LIMIT 0

/**
 * \brief The invalid MemPool object.
 */
#define VMK_MEMPOOL_INVALID ((vmk_MemPool) NULL)

/**
 * \ingroup MemPool
 * \brief Memory pool handle
 */
typedef struct vmk_MemPoolInt* vmk_MemPool;

/**
 * \ingroup MemPool
 * \brief Types of memory pools
 *
 * \note Only VMK_MEM_POOL_LEAF memory pools can be used as memory pools for
 *       allocation functions.
 *
 * \note VMK_MEM_POOL_PARENT memory pools can be used to group other memory
 *       pools together for easier resource admission control and better
 *       resource tracking.
 */
typedef enum vmk_MemPoolType {
   /** \brief Memory pool can be parent of other memory pools. */
   VMK_MEM_POOL_PARENT = 0,

   /** \brief Memory pool cannot be parent of another memory pool. */
   VMK_MEM_POOL_LEAF  = 1,
} vmk_MemPoolType;

/**
 * \ingroup MemPool
 * \brief Properties of the resource limitations of a memory pool
 */
typedef struct vmk_MemPoolResourceProps {
   /** \brief Specifies the min num of guaranteed pages reserved for the pool. */
   vmk_uint32     reservation;
   
   /** \brief Specifies the max num of pages the pool can offer. */
   vmk_uint32     limit;
} vmk_MemPoolResourceProps;

/**
 * \ingroup MemPool
 * \brief Properties of a memory pool
 */
typedef struct vmk_MemPoolProps {
   /** \brief Name associated with this memory pool. */
   vmk_Name name;

   /** \brief Module ID of the module creating this memory pool. */
   vmk_ModuleID module;

   /** \brief Parent memory pool handle, or VMK_MEMPOOL_INVALID. */
   vmk_MemPool parentMemPool;

   /** \brief Type of memory pool. */
   vmk_MemPoolType memPoolType;

   /** \brief Resource properties of memory pool. */
   vmk_MemPoolResourceProps resourceProps;
} vmk_MemPoolProps;

/**
 * \ingroup MemPool
 * \brief Properties of a memory pool allocation
 */
typedef struct vmk_MemPoolAllocProps {
   /** \brief Physical contiguity for this memory allocation. */
   vmk_MemPhysContiguity physContiguity;

   /** \brief Physical address resrictions. */
   vmk_MemPhysAddrConstraint physRange;

   /** \brief How long to wait for memory during allocation. */
   vmk_uint32 creationTimeoutMS;

} vmk_MemPoolAllocProps;

/**
 * \ingroup MemPool
 * \brief Properties of a memory pool allocation
 *
 * This struct describes a memory pool allocation request of machine pages.
 * The user provides a mpns array of size numElements.
 * For an allocation of physical contiguity type VMK_MEM_PHYS_CONTIGUOUS, only
 * the first MPN of the contiguous range is set in the mpnRanges array, otherwise
 * all elements in the mpnRanges array are set.
 */
typedef struct vmk_MemPoolAllocRequest {
   /** \brief Number of pages that should be allocated. */
   vmk_uint32 numPages;

   /** \brief Number of elements in vmk_MpnRange array. */
   vmk_uint32 numElements;

   /** \brief Array of numElements vmk_MpnRanges. */
   vmk_MpnRange *mpnRanges;
} vmk_MemPoolAllocRequest;

/*
 ***********************************************************************
 * vmk_MemPoolCreate --                                           */ /**
 *
 * \ingroup MemPool
 * \brief Create a machine memory pool.
 *
 * This function create a memory pool. A memory pool can be a child
 * of another created memory pool. It cannot exceed the limit or
 * reservation of its parent memory pool.
 *
 * \note A memory pool cannot exceed the reservation of its parent,
 *       but its limit can be larger than the limit of its parent.
 *       However, it will not be possible to allocate more pages than
 *       allowed by the parents limit.
 * \note This function will not block.
 *
 * \param[in]  props          Properties of the new memory pool.
 * \param[out] pool           Handle to the newly created memory pool.
 *
 * \retval VMK_BAD_PARAM             The pool or properties arguments
 *                                   were NULL, or the properties values
 *                                   were invalid.
 * \retval VMK_INVALID_NAME          Provided name was invalid.
 * \retval VMK_RESERVATION_GT_LIMIT  Reservation was larger than the
 *                                   limit in the pool properties. The
 *                                   reservation should always be less 
 *                                   or equal to the limit.
 * \retval VMK_NO_RESOURCES          The requested pool reservation was
 *                                   rejected because the parent's pool
 *                                   did not have the resources to
 *                                   fulfill it. If parentMemPool is 
 *                                   VMK_MEMPOOL_INVALID, the entire
 *                                   system did not have enough
 *                                   resources to fulfill the resource
 *                                   reservation.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_MemPoolCreate(
   vmk_MemPoolProps *props,
   vmk_MemPool *pool);

/*
 ***********************************************************************
 * vmk_MemPoolSetProps --                                         */ /**
 *
 * \ingroup MemPool
 * \brief Change the properties of an existing memory pool
 *
 * \note This function will not block.
 *
 * \param[in,out] pool   Memory pool to change
 * \param[in]     props  New properties for the memory pool
 *
 * \retval VMK_BAD_PARAM             The pool or properties arguments
 *                                   were NULL, the pool was invalid,
 *                                   or the properties values were
 *                                   invalid.
 * \retval VMK_RESERVATION_GT_LIMIT  Reservation was larger than the
 *                                   limit in the pool properties. The
 *                                   reservation should always be less 
 *                                   or equal to the limit.
 * \retval VMK_NO_RESOURCES          The requested pool reservation was
 *                                   rejected because the parent's pool
 *                                   did not have the resources to 
 *                                   fulfill it. If parentMemPool is 
 *                                   VMK_MEMPOOL_INVALID, the entire
 *                                   system did not have enough
 *                                   resources to fulfill the resource
 *                                   reservation.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_MemPoolSetProps(
   const vmk_MemPool pool,
   const vmk_MemPoolResourceProps *props);

/*
 ***********************************************************************
 * vmk_MemPoolGetProps --                                         */ /**
 *
 * \ingroup MemPool
 * \brief   Get the properties of an existing memory pool
 *
 * \note    This function will not block.
 *
 * \param[in]  pool     Memory pool to query
 * \param[out] props    Properties associated with the
 *                      memory pool
 *
 * \retval VMK_BAD_PARAM  The pool or properties argument was invalid.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_MemPoolGetProps(
   const vmk_MemPool pool,
   vmk_MemPoolResourceProps *props);

/*
 ***********************************************************************
 * vmk_MemPoolDestroy --                                          */ /**
 *
 * \ingroup MemPool
 * \brief Destroy a memory pool.
 *
 * \note The memory pool must have no children and no pages allocated to
 *       it, otherwise the operation will fail.
 *
 * \note This function will not block.
 *
 * \param[in]  pool   Memory pool to destroy
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_MemPoolDestroy(
   vmk_MemPool pool);

/*
 ***********************************************************************
 * vmk_MemPoolAlloc --                                            */ /**
 *
 * \ingroup MemPool
 * \brief Allocate a contiguous range of machine pages from a specified
 *        memory pool.
 *
 * \note The provided memory pool must be of type VMK_MEM_POOL_LEAF.
 * 
 * \note For allocations which are not of type VMK_MEM_PHYS_CONTIGUOUS,
 *       one vmk_MpnRange is required per page, otherwise one
 *       vmk_MpnRange is sufficient.
 *
 * \note This function may block if the creationTimeoutMS field of
 *       props is not VMK_TIMEOUT_NONBLOCKING.
 *
 * \param[in] pool            Memory pool to allocate from.
 * \param[in] props           Attributes for this allocation.
 * \param[in,out] request     Allocation request. The mpns array gets
 *                            filled on success.
 *
 * \retval VMK_BAD_PARAM       The pool or props argument was invalid,
 *                             the number of pages requested was zero,
 *                             mpnRanges array was not set, or
 *                             the number of elements was less than one.
 * \retval VMK_LIMIT_EXCEEDED  The number of elements is not sufficient
 *                             to represent the used vmk_MpnRanges.
 * \retval VMK_NO_RESOURCES    The requested allocation was rejected
 *                             because the pool or the pools group
 *                             did not have the resources to fulfill it.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_MemPoolAlloc(
   vmk_MemPool pool,
   const vmk_MemPoolAllocProps *props,
   const vmk_MemPoolAllocRequest *request);

/*
 ***********************************************************************
 * vmk_MemPoolFree --                                             */ /**
 *
 * \ingroup MemPool
 * \brief Free all pages described by the allocRequest.
 *
 * \param[in]  request   Request describing the vmk_MpnRanges to free.
 *
 * \note This function will not block.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_MemPoolFree(
   const vmk_MemPoolAllocRequest *request);

#endif /* _VMKAPI_MEMPOOL_H_ */
/** @} */