/* **********************************************************
 * Copyright 2010-2012 VMware, Inc.  All rights reserved.
 * **********************************************************/

/*
 * @VMKAPIMOD_LICENSE@
 */

/*
 ******************************************************************************
 * User Space Memory Interface                                             */ /**
 *
 * \addtogroup Core
 * @{
 * \defgroup UserMem User Space Memory
 * @{
 ******************************************************************************
 */

#ifndef _VMKAPI_CORE_USERMEMORY_H_
#define _VMKAPI_CORE_USERMEMORY_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 */


/*
 ***********************************************************************
 * vmk_UserMapCallback --                                         */ /**
 *
 * \brief Callback function invoked when user mapping is released.
 *
 * \param[in] callbackParam    Opaque parameter for callback function.
 *
 ***********************************************************************
 */
typedef void (*vmk_UserMapCallback)(void *);


/**
 * \brief Properties of a vmk_UserMap() map request.
 */
typedef struct vmk_UserMapProps {
   /** \brief Module ID of module requesting mapping. */
   vmk_ModuleID moduleID;
   /** \brief Function to call when mapping is released. */
   vmk_UserMapCallback callbackFunction;
   /** \brief Opaque parameter for callbackFunction. */
   vmk_AddrCookie callbackParam;
   /**
    * \brief Pointer to map request structure.
    *
    * \note See Mapping section for description
    *       of map request structure.
    */
   vmk_MapRequest *mapRequest;
} vmk_UserMapProps;


/*
 ***********************************************************************
 * vmk_UserMap --                                                 */ /**
 *
 * \brief Map the provided request into a contiguous virtual address
 *        space of current user world.
 *
 * \note The only supported mapping attributes are READONLY, READWRITE,
 *       WRITECOMBINE, and UNCACHED.  Any other attribute will cause
 *       mapping to fail with return status VMK_BAD_PARAM.
 *
 * \param[in]     props   Properties of this mapping request.
 * \param[in,out] vaddr   Pointer to virtual address of mapping
 *                        (non-zero to specify a virtual address,
 *                        or zero for default address).
 *
 * \retval VMK_OK              Map is successful.
 * \retval VMK_BAD_PARAM       Input parameter is invalid.
 * \retval VMK_NO_MEMORY       Unable to allocate mapping request.
 * \retval VMK_NO_RESOURCES    Unable to allocate mapping request.
 * \retval VMK_INVALID_ADDRESS Requested address not in map range.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_UserMap(
   vmk_UserMapProps *props,
   vmk_VA *vaddr);

/*
 ***********************************************************************
 * vmk_UserUnmap --                                               */ /**
 *
 * \brief Unmap user world virtual address space mapped by vmk_UserMap().
 *
 * \param[in] vaddr            Virtual address to unmap.
 * \param[in] length           Length of address space in bytes.
 *
 * \retval VMK_OK              Unmap is successful.
 * \retval VMK_NOT_FOUND       Virtual address and length not mapped.
 * \retval VMK_INVALID_ADDRESS Requested address is not page aligned.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_UserUnmap(
   vmk_VA vaddr,
   vmk_ByteCount length);

/*
 ***********************************************************************
 * vmk_UserAddValidMPNRange --                                    */ /**
 *
 * \brief Indicate a range of consecutive MPNs can be referenced by
 *        user worlds.
 *
 * \param[in] mpn              First MPN in range.
 * \param[in] numPages         Number of machine pages in range.
 *
 * \retval VMK_OK              MPNs added to user worlds.
 * \retval VMK_BAD_PARAM       Input parameter is invalid.
 * \retval VMK_NO_MEMORY       Unable to allocate memory for request.
 * \retval VMK_INVALID_PAGE_NUMBER  MPN range intersects with existing
 *                             MPN range.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_UserAddValidMPNRange(
   vmk_MPN mpn,
   vmk_uint32 numPages);

/*
 ***********************************************************************
 * vmk_UserRemoveValidMPNRange --                                 */ /**
 *
 * \brief Remove a range of consecutive MPNs from user worlds.
 *
 * \param[in] mpn              First MPN in range.
 * \param[in] numPages         Number of machine pages in range.
 *
 * \retval VMK_OK              MPNs removed from user worlds.
 * \retval VMK_NOT_FOUND       MPN range not found.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_UserRemoveValidMPNRange(
   vmk_MPN mpn,
   vmk_uint32 numPages);

/*
 ***********************************************************************
 * vmk_UserPinPage --                                             */ /**
 *
 * \brief Marks the VPN in the specified world as not swappable.
 *
 * \param[in]  worldID         ID of world whose mapping will be pinned.
 * \param[in]  vpn             VPN to pin.
 * \param[out] mpn             MPN backing this pinned VPN.
 *
 * \retval VMK_OK              VPNs was pinned successfully.
 * \retval VMK_BAD_PARAM       An invalid argument was provided.
 * \retval VMK_INVALID_WORLD   An invalid worldID was provided.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_UserPinPage(
   vmk_WorldID worldID,
   vmk_VPN vpn,
   vmk_MPN *mpn);

/*
 ***********************************************************************
 * vmk_UserUnpinPage --                                           */ /**
 *
 * \brief Marks the specified VPN in the specified world as swappable.
 *
 * \note  This VPN must have been pinned by a call to vmk_UserPinPage().
 *
 * \param[in]  worldID         ID of world whose mapping will be
 *                             unpinned.
 * \param[in]  vpn             VPN to unpin.
 *
 * \retval VMK_OK              VPNs was unpinned successfully.
 * \retval VMK_BAD_PARAM       An invalid argument was provided.
 * \retval VMK_INVALID_WORLD   An invalid worldID was provided.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_UserUnpinPage(
   vmk_WorldID worldID,
   vmk_VPN vpn);


/*
 ******************************************************************************
 * vmk_CopyFromUser --                                                   */ /**
 *
 * Copy memory from a user space application into a kernel buffer
 *
 * \note Caller must not hold any spinlocks.
 * \note Must be called from a blockable context
 *
 * \param[in] dest   Copy-to location.
 * \param[in] src    Copy-from location.
 * \param[in] len    Amount to copy.
 *
 ******************************************************************************
 */
VMK_ReturnStatus vmk_CopyFromUser(
   vmk_VA dest,
   vmk_VA src,
   vmk_ByteCount len);

/*
 ******************************************************************************
 * vmk_CopyToUser --                                                     */ /**
 *
 * Copy memory from a kernel buffer into a user space application.
 *
 * \note Caller must not hold any spinlocks.
 * \note Must be called from a blockable context
 *
 * \param[in] dest   Copy-to location.
 * \param[in] src    Copy-from location.
 * \param[in] len    Amount to copy.
 *
 ******************************************************************************
 */
VMK_ReturnStatus vmk_CopyToUser(
   vmk_VA dest,
   vmk_VA src,
   vmk_ByteCount len);


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