memobj.h revision 9d80662bfa36cc718a22f982d48148415ca95fb8
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/* $Revision$ */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * innotek Portable Runtime - Ring-0 Memory Objects.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Copyright (C) 2006-2007 innotek GmbH
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * available from http://www.virtualbox.org. This file is free software;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * you can redistribute it and/or modify it under the terms of the GNU
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * General Public License (GPL) as published by the Free Software
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * The contents of this file may alternatively be used under the terms
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * of the Common Development and Distribution License Version 1.0
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * VirtualBox OSE distribution, in which case the provisions of the
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * CDDL are applicable instead of those of the GPL.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * You may elect to license modified versions of this file under the
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * terms and conditions of either the GPL or the CDDL or both.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** @defgroup grp_rt_memobj_int Internals.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @ingroup grp_rt_memobj
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @internal
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Ring-0 memory object type.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The traditional invalid value. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** @name Primary types (parents)
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjAllocPage.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This memory is page aligned and fixed. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjAllocLow.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This memory is page aligned, fixed and is backed by physical memory below 4GB. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjAllocCont.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This memory is page aligned, fixed and is backed by contiguous physical memory below 4GB. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjLockKernel, RTR0MemObjLockUser.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This memory is page aligned and fixed. It was locked/pinned/wired down by the API call. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjAllocPhys, RTR0MemObjEnterPhys.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This memory is physical memory, page aligned, contiguous and doesn't need to have a mapping. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjAllocPhysNC.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This memory is physical memory, page aligned and doesn't need to have a mapping. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjReserveKernel, RTR0MemObjReserveUser.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This memory is page aligned and has no backing. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** @name Secondary types (children)
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MemObjMapUser, RTR0MemObjMapKernel.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This is a user or kernel context mapping of another ring-0 memory object. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The end of the valid types. Used for sanity checking. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsynctypedef struct RTR0MEMOBJINTERNAL *PRTR0MEMOBJINTERNAL;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsynctypedef struct RTR0MEMOBJINTERNAL **PPRTR0MEMOBJINTERNAL;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Ring-0 memory object.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * When using the PRTR0MEMOBJINTERNAL and PPRTR0MEMOBJINTERNAL types
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * we get pMem and ppMem variable names.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * When using the RTR0MEMOBJ and PRTR0MEMOBJ types we get MemObj and
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * pMemObj variable names. We never dereference variables of the RTR0MEMOBJ
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * type, we always convert it to a PRTR0MEMOBJECTINTERNAL variable first.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Magic number (RTR0MEM_MAGIC). */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The size of this structure. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The type of allocation. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The size of the memory allocated, pinned down, or mapped. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The memory address.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * What this really is varies with the type.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * For PAGE, CONT, LOW, RES_VIRT/R0, LOCK/R0 and MAP/R0 it's the ring-0 mapping.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * For LOCK/R3, RES_VIRT/R3 and MAP/R3 it is the ring-3 mapping.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * For PHYS this might actually be NULL if there isn't any mapping.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Object relations. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** This is for tracking child memory handles mapping the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * memory described by the primary handle. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Number of mappings. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Number of mappings in the array. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Pointers to child handles mapping this memory. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Pointer to the primary handle. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Pointer to the parent. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Type specific data for the memory types that requires that. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMTYPE_PAGE. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMTYPE_LOW. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMTYPE_CONT. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The physical address of the first page. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMTYPE_LOCK_USER. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The process that owns the locked memory.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This is NIL_RTR0PROCESS if it's kernel memory. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMTYPE_PHYS. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The base address of the physical memory. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** If set this object was created by RTR0MemPhysAlloc, otherwise it was
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * created by RTR0MemPhysEnter. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMTYPE_PHYS_NC. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMOBJTYPE_RES_VIRT */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The process that owns the reserved memory.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This is NIL_RTR0PROCESS if it's kernel memory. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** RTR0MEMOBJTYPE_MAPPING */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The process that owns the reserved memory.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This is NIL_RTR0PROCESS if it's kernel memory. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Checks if this is mapping or not.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns true if it's a mapping, otherwise false.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pMem The ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @see RTR0MemObjIsMapping
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncDECLINLINE(bool) rtR0MemObjIsMapping(PRTR0MEMOBJINTERNAL pMem)
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync return true;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync return false;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Checks if RTR0MEMOBJ::pv is a ring-3 pointer or not.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns true if it's a object with a ring-3 address, otherwise false.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pMem The ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncDECLINLINE(bool) rtR0MemObjIsRing3(PRTR0MEMOBJINTERNAL pMem)
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync return pMem->u.ResVirt.R0Process != NIL_RTR0PROCESS;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync return pMem->u.Mapping.R0Process != NIL_RTR0PROCESS;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync return false;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Frees the memory object (but not the handle).
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Any OS specific handle resources will be freed by this call.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code. On failure it is assumed that the object remains valid.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pMem The ring-0 memory object handle to the memory which should be freed.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Allocates page aligned virtual kernel memory.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * The memory is taken from a non paged (= fixed physical memory backing) pool.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param ppMem Where to store the ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cb Number of bytes to allocate, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncint rtR0MemObjNativeAllocPage(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Allocates page aligned virtual kernel memory with physical backing below 4GB.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * The physical memory backing the allocation is fixed.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param ppMem Where to store the ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cb Number of bytes to allocate, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncint rtR0MemObjNativeAllocLow(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * The physical memory backing the allocation is fixed.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param ppMem Where to store the ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cb Number of bytes to allocate, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncint rtR0MemObjNativeAllocCont(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Locks a range of user virtual memory.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param ppMem Where to store the ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param R3Ptr User virtual address, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cb Number of bytes to lock, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param R0Process The process to lock pages in.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncint rtR0MemObjNativeLockUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3Ptr, size_t cb, RTR0PROCESS R0Process);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Locks a range of kernel virtual memory.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param ppMem Where to store the ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pv Kernel virtual address, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cb Number of bytes to lock, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncint rtR0MemObjNativeLockKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pv, size_t cb);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Allocates contiguous page aligned physical memory without (necessarily) any kernel mapping.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param ppMem Where to store the ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cb Number of bytes to allocate, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param PhysHighest The highest permittable address (inclusive).
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * NIL_RTHCPHYS if any address is acceptable.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncint rtR0MemObjNativeAllocPhys(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * physical memory on this platform.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param ppMem Where to store the ring-0 memory object handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cb Number of bytes to allocate, page aligned.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param PhysHighest The highest permittable address (inclusive).
* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
int rtR0MemObjNativeReserveKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pvFixed, size_t cb, size_t uAlignment);
* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
int rtR0MemObjNativeReserveUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment, RTR0PROCESS R0Process);
* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
int rtR0MemObjNativeMapKernel(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, void *pvFixed, size_t uAlignment, unsigned fProt);
* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.