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

include "IMemRegion.idl"

/**
 * A memory space determines mapping from virtual addresses to physical
 * addresses, and the types of access allowed at each virtual addresses.
 */
/** @cond */
interface IMemSpace {
/** @endcond */

  /**
   * @addtogroup IMemSpace
   * @{
   */

  /** @cond */
  /*
   * Memory cannot be mapped as specified because the provided memory
   * region object did not confer the required memory access permissions.
   */
  error ERROR_PERM;

  /*
   * The provided object was not a memory region.
   */
  error ERROR_INVALID_REGION;

  /*
   * Allocation in the App Region failed.
   */
  error ERROR_TA_APP_REGION_ALLOC;

  /*
   * Memory cannot be mapped as specified because it is not in the addressable space
   * for the application (e.g. 32-bit application trying to map memory above 4GB)
   */
  error ERROR_NOT_IN_ADDRESSABLE_SPACE;
  /** @endcond */

  /**
    Makes a memory region visible in the address space as a contiguous range
    of virtual addresses.

    On success, virtual addresses from <tt>addr</tt> to <tt>addr+size-1</tt> are
    accessible with at least the specified permissions, and remain
    accessible until the memmap object is released.

    @param[in]  region  Identifies memory to be made visible.
    @param[in]  perms   Access permissions required for mapping, as defined in
                        IMemRegion::PERM_... constants.  If these permissions cannot
                        be satisfied, the operation fails.
    @param[out] addr    Virtual address of the mapped region.
    @param[out] size    Mapped region size.
    @param[out] memmap  An object that acts as a reference count on mapping.
                        When deleted, the map is removed from the address
                        space.

    @return
    Object_OK on success.
  */
  method map(in IMemRegion region,
             in uint32 perms,
             out uint64 addr,
             out uint64 size,
             out interface memmap);

  /**
    Makes a part of memory region visible in the address space as a contiguous range
    of virtual addresses.

    On success, virtual addresses from <tt>addr</tt> to <tt>addr+size-1</tt> are
    accessible with at least the specified permissions, and remain
    accessible until the memmap object is released.

    @param[in]  region  Identifies memory to be made visible.
    @param[in]  offset  Specifies offset (from beginning of region) to map 
                        Offset should be 4K aligned.
    @param[in]  size    Specifies size to map. size should be non-zero and
                        4K aligned.
    @param[in]  perms   Access permissions required for mapping, as defined in
                        IMemRegion::PERM_... constants.  If these permissions cannot
                        be satisfied, the operation fails.
    @param[out] addr    Virtual address of the mapped region.
    @param[out] memmap  An object that acts as a reference count on mapping.
                        When deleted, the map is removed from the address
                        space.

    @return
    Object_OK on success.
  */
  method mapPartial(in IMemRegion region,
                    in uint64 offset,
                    in uint64 size,
                    in uint32 perms,
                    out uint64 addr,
                    out interface memmap);
  /* @} */ /* end_addtogroup IMemSpace */
};
