// Copyright (c) 2019 Qualcomm Technologies, Inc.  All Rights Reserved.
// Qualcomm Technologies Proprietary and Confidential.

include "IMemRegion.idl"

/** @cond */
interface IMemRegionPermEscalator {
/** @endcond */

  /**
     @addtogroup IMemRegionPermEscalator
     @{
   */

  /** @cond */
  /**
     A value other than PERM_R, PERM_W or PERM_RW was passed
  */
  error ERROR_UNRECOGNIZED_PERM;

  /**
     Could not guarantee escalated perms for object lifetime
  */
  error ERROR_ACQUIRING_LOCK;

  /**
     Caller has no authority to escalate perms
  */
  error ERROR_NO_AUTHORITY;

  /**
     Input region is a not valid memory region
  */
  error ERROR_INVALID_INPUT_REGION;
  /** @endcond */

  /**
     Attempts to escalates access permission for input memory region
     to value passed in input parameter. Authority to escalate
     privileges for the input memory region are granted by the
     IMemRegionPermEscalator object creator's privileges. On success,
     a new memory region is returned with the requested access
     permission(s).  The returned object will have an access control
     guarantee (See \link IAccessControl \endlink) of "ANY
     NonExclusive" for the set of additional access permissions
     granted by the privileges associated with the TA.  This guarantee
     lasts for the lifetime of the returned memory region.

     @param[in]  inRegion   Memory region to attempt to escalate
                            privileges on.

     @param[in]  newPerms   Access permissions requested for input
                            region.  Valid values defined in
                            IMemRegion::PERM_... constants.
                            Executable permission is not supported.

     @param[out] outRegion  New region with requested permissions.

     @return
     Object_OK on success
   */
  method escalatePerm(in IMemRegion inRegion,
                      in uint32 newPerm,
                      out IMemRegion outRegion);

  /* @} */ /* end_addtogroup IMemRegionPermEscalator */
};