memobj.h revision 7762d495cd5e7192d5e08ef6b9b2e906045eb033
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * innotek Portable Runtime - Memory Objects (Ring-0).
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Copyright (C) 2006-2007 innotek GmbH
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
9019681d4e9b8399b951793a9dd92b63c195e0eevboxsync * available from http://www.virtualbox.org. This file is free software;
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * you can redistribute it and/or modify it under the terms of the GNU
92a27575521748a392dcd1b996fce55b87411a00vboxsync * General Public License as published by the Free Software Foundation,
92a27575521748a392dcd1b996fce55b87411a00vboxsync * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
92a27575521748a392dcd1b996fce55b87411a00vboxsync * distribution. VirtualBox OSE is distributed in the hope that it will
92a27575521748a392dcd1b996fce55b87411a00vboxsync * be useful, but WITHOUT ANY WARRANTY of any kind.
10cdf5733351fdcd857d439ca32189e812f18682vboxsync/** @defgroup grp_rt_memobj RTMemObj - Memory Object Manipulation (Ring-0)
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * @ingroup grp_rt
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * Checks if this is mapping or not.
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * @returns true if it's a mapping, otherwise false.
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * @param MemObj The ring-0 memory object handle.
10cdf5733351fdcd857d439ca32189e812f18682vboxsyncRTR0DECL(bool) RTR0MemObjIsMapping(RTR0MEMOBJ MemObj);
cd9e4940318086a06a68bf301960563dcb72b939vboxsync * Gets the address of a ring-0 memory object.
cd9e4940318086a06a68bf301960563dcb72b939vboxsync * @returns The address of the memory object.
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param MemObj The ring-0 memory object handle.
10cdf5733351fdcd857d439ca32189e812f18682vboxsyncRTR0DECL(void *) RTR0MemObjAddress(RTR0MEMOBJ MemObj);
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * Gets the ring-3 address of a ring-0 memory object.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * This only applies to ring-0 memory object with ring-3 mappings of some kind, i.e.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * locked user memory, reserved user address space and user mappings. This API should
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * not be used on any other objects.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns The address of the memory object.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns NIL_RTR3PTR if the handle is invalid or if it's not an object with a ring-3 mapping.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Strict builds will assert in both cases.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param MemObj The ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR0DECL(RTR3PTR) RTR0MemObjAddressR3(RTR0MEMOBJ MemObj);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Gets the size of a ring-0 memory object.
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * @returns The address of the memory object.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * @param MemObj The ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Get the physical address of an page in the memory object.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns The physical address.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
86abc60770f825f8c2ed4257675b50a08743b687vboxsync * @returns NIL_RTHCPHYS if the iPage is out of range.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns NIL_RTHCPHYS if the object handle isn't valid.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param MemObj The ring-0 memory object handle.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param iPage The page number within the object.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncRTR0DECL(RTHCPHYS) RTR0MemObjGetPagePhysAddr(RTR0MEMOBJ MemObj, size_t iPage);
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync * Frees a ring-0 memory object.
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync * @returns IPRT status code.
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync * @retval VERR_INVALID_HANDLE if
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync * @param MemObj The ring-0 memory object to be freed. NULL is accepted.
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync * @param fFreeMappings Whether or not to free mappings of the object.
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsyncRTR0DECL(int) RTR0MemObjFree(RTR0MEMOBJ MemObj, bool fFreeMappings);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Allocates page aligned virtual kernel memory.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * The memory is taken from a non paged (= fixed physical memory backing) pool.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @returns IPRT status code.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param pMemObj Where to store the ring-0 memory object handle.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param cb Number of bytes to allocate. This is rounded up to nearest page.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR0DECL(int) RTR0MemObjAllocPage(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Allocates page aligned virtual kernel memory with physical backing below 4GB.
86abc60770f825f8c2ed4257675b50a08743b687vboxsync * The physical memory backing the allocation is fixed.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @returns IPRT status code.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param pMemObj Where to store the ring-0 memory object handle.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param cb Number of bytes to allocate. This is rounded up to nearest page.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncRTR0DECL(int) RTR0MemObjAllocLow(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable);
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
360c39d88dfa26b17181b57ebafdb24c2a113c63vboxsync * The physical memory backing the allocation is fixed.
360c39d88dfa26b17181b57ebafdb24c2a113c63vboxsync * @returns IPRT status code.
360c39d88dfa26b17181b57ebafdb24c2a113c63vboxsync * @param pMemObj Where to store the ring-0 memory object handle.
360c39d88dfa26b17181b57ebafdb24c2a113c63vboxsync * @param cb Number of bytes to allocate. This is rounded up to nearest page.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncRTR0DECL(int) RTR0MemObjAllocCont(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable);
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * Locks a range of user virtual memory.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @returns IPRT status code.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param pMemObj Where to store the ring-0 memory object handle.
6967517de4be849f55b0141d6089add0eff2aa7bvboxsync * @param R3Ptr User virtual address. This is rounded down to a page boundrary.
6967517de4be849f55b0141d6089add0eff2aa7bvboxsync * @param cb Number of bytes to lock. This is rounded up to nearest page boundrary.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync * @param R0Process The process to lock pages in. NIL_R0PROCESS is an alias for the current one.
7b213bb002950f9fcf809f605cc584fa543481advboxsync * @remark RTR0MemGetAddressR3() and RTR0MemGetAddress() will return the rounded down address.
7b213bb002950f9fcf809f605cc584fa543481advboxsyncRTR0DECL(int) RTR0MemObjLockUser(PRTR0MEMOBJ pMemObj, RTR3PTR R3Ptr, size_t cb, RTR0PROCESS R0Process);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Locks a range of kernel virtual memory.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns IPRT status code.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pMemObj Where to store the ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pv Kernel virtual address. This is rounded down to a page boundrary.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param cb Number of bytes to lock. This is rounded up to nearest page boundrary.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @remark RTR0MemGetAddress() will return the rounded down address.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR0DECL(int) RTR0MemObjLockKernel(PRTR0MEMOBJ pMemObj, void *pv, size_t cb);
9019681d4e9b8399b951793a9dd92b63c195e0eevboxsync * Allocates contiguous page aligned physical memory without (necessarily) any kernel mapping.
cd9e4940318086a06a68bf301960563dcb72b939vboxsync * @returns IPRT status code.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pMemObj Where to store the ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param cb Number of bytes to allocate. This is rounded up to nearest page.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param PhysHighest The highest permittable address (inclusive).
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Pass NIL_RTHCPHYS if any address is acceptable.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR0DECL(int) RTR0MemObjAllocPhys(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest);
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync * Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
b49952fd6cae765238f4760c700c5ef797a56092vboxsync * This API is for allocating huge amounts of pages and will return
b49952fd6cae765238f4760c700c5ef797a56092vboxsync * VERR_NOT_SUPPORTED if this cannot be implemented in a satisfactory
f9e9ec581188b7f7645e3dea5bafa77cfcec31efvboxsync * @returns IPRT status code.
f9e9ec581188b7f7645e3dea5bafa77cfcec31efvboxsync * @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * physical memory on this platform. The caller should expect
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * this error and have a fallback strategy for it.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pMemObj Where to store the ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param cb Number of bytes to allocate. This is rounded up to nearest page.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param PhysHighest The highest permittable address (inclusive).
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Pass NIL_RTHCPHYS if any address is acceptable.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR0DECL(int) RTR0MemObjAllocPhysNC(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Creates a page aligned, contiguous, physical memory object.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * No physical memory is allocated, we trust you do know what you're doing.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns IPRT status code.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pMemObj Where to store the ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param Phys The physical address to start at. This is rounded down to the
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * nearest page boundrary.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param cb The size of the object in bytes. This is rounded up to nearest page boundrary.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR0DECL(int) RTR0MemObjEnterPhys(PRTR0MEMOBJ pMemObj, RTHCPHYS Phys, size_t cb);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Reserves kernel virtual address space.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * If this function fails with VERR_NOT_SUPPORTED, the idea is that you
c7a92d481aced08517570d43bf75e2a9f3a8aaeavboxsync * can use RTR0MemObjEnterPhys() + RTR0MemObjMapKernel() as a fallback if
c7a92d481aced08517570d43bf75e2a9f3a8aaeavboxsync * you have a safe physical address range to make use of...
c7a92d481aced08517570d43bf75e2a9f3a8aaeavboxsync * @returns IPRT status code.
c7a92d481aced08517570d43bf75e2a9f3a8aaeavboxsync * @param pMemObj Where to store the ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param cb The number of bytes to reserve. This is rounded up to nearest page.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param uAlignment The alignment of the reserved memory.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR0DECL(int) RTR0MemObjReserveKernel(PRTR0MEMOBJ pMemObj, void *pvFixed, size_t cb, size_t uAlignment);
541ba632c438350cc8044d7ce2c8623dca446546vboxsync * Reserves user virtual address space in the current process.
08a80484275b5172ce23729ecccc934c6a92d201vboxsync * @returns IPRT status code.
08a80484275b5172ce23729ecccc934c6a92d201vboxsync * @param pMemObj Where to store the ring-0 memory object handle.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
86abc60770f825f8c2ed4257675b50a08743b687vboxsync * @param cb The number of bytes to reserve. This is rounded up to nearest PAGE_SIZE.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param uAlignment The alignment of the reserved memory.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsync * @param R0Process The process to reserve the memory in. NIL_R0PROCESS is an alias for the current one.
48f33dfd8f615d457106bf76ae2d09b8b9167c1avboxsyncRTR0DECL(int) RTR0MemObjReserveUser(PRTR0MEMOBJ pMemObj, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment, RTR0PROCESS R0Process);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Maps a memory object into kernel virtual address space.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns IPRT status code.
fc148a6b23d25a87561beaffe0ba06c3ba93bf5avboxsync * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
fc148a6b23d25a87561beaffe0ba06c3ba93bf5avboxsync * @param MemObjToMap The object to be map.
fc148a6b23d25a87561beaffe0ba06c3ba93bf5avboxsync * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
fc148a6b23d25a87561beaffe0ba06c3ba93bf5avboxsync * @param uAlignment The alignment of the reserved memory.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsyncRTR0DECL(int) RTR0MemObjMapKernel(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed, size_t uAlignment, unsigned fProt);
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * Maps a memory object into user virtual address space in the current process.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @returns IPRT status code.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @param MemObjToMap The object to be map.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @param uAlignment The alignment of the reserved memory.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync * @param R0Process The process to map the memory into. NIL_R0PROCESS is an alias for the current one.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsyncRTR0DECL(int) RTR0MemObjMapUser(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, RTR3PTR R3PtrFixed, size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process);
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync#endif /* IN_RING0 */