ubuntu/vbox/include/iprt/memobj.h

   1 /** @file
   2  * IPRT - Memory Objects (Ring-0).
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2016 Oracle Corporation
   7  *
   8  * This file is part of VirtualBox Open Source Edition (OSE), as
   9  * available from http://www.virtualbox.org. This file is free software;
  10  * you can redistribute it and/or modify it under the terms of the GNU
  11  * General Public License (GPL) as published by the Free Software
  12  * Foundation, in version 2 as it comes in the "COPYING" file of the
  13  * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
  14  * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
  15  *
  16  * The contents of this file may alternatively be used under the terms
  17  * of the Common Development and Distribution License Version 1.0
  18  * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
  19  * VirtualBox OSE distribution, in which case the provisions of the
  20  * CDDL are applicable instead of those of the GPL.
  21  *
  22  * You may elect to license modified versions of this file under the
  23  * terms and conditions of either the GPL or the CDDL or both.
  24  */
  25
  26 #ifndef ___iprt_memobj_h
  27 #define ___iprt_memobj_h
  28
  29 #include <iprt/cdefs.h>
  30 #include <iprt/types.h>
  31
  32 RT_C_DECLS_BEGIN
  33
  34 /** @defgroup grp_rt_memobj     RTMemObj - Memory Object Manipulation (Ring-0)
  35  * @ingroup grp_rt
  36  * @{
  37  */
  38
  39 /** @def RTMEM_TAG
  40  * The default allocation tag used by the RTMem allocation APIs.
  41  *
  42  * When not defined before the inclusion of iprt/memobj.h or iprt/mem.h, this
  43  * will default to the pointer to the current file name.  The memory API will
  44  * make of use of this as pointer to a volatile but read-only string.
  45  */
  46 #ifndef RTMEM_TAG
  47 # define RTMEM_TAG   (__FILE__)
  48 #endif
  49
  50 #ifdef IN_RING0
  51
  52 /**
  53  * Checks if this is mapping or not.
  54  *
  55  * @returns true if it's a mapping, otherwise false.
  56  * @param   MemObj  The ring-0 memory object handle.
  57  */
  58 RTR0DECL(bool) RTR0MemObjIsMapping(RTR0MEMOBJ MemObj);
  59
  60 /**
  61  * Gets the address of a ring-0 memory object.
  62  *
  63  * @returns The address of the memory object.
  64  * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
  65  * @param   MemObj  The ring-0 memory object handle.
  66  */
  67 RTR0DECL(void *) RTR0MemObjAddress(RTR0MEMOBJ MemObj);
  68
  69 /**
  70  * Gets the ring-3 address of a ring-0 memory object.
  71  *
  72  * This only applies to ring-0 memory object with ring-3 mappings of some kind, i.e.
  73  * locked user memory, reserved user address space and user mappings. This API should
  74  * not be used on any other objects.
  75  *
  76  * @returns The address of the memory object.
  77  * @returns NIL_RTR3PTR if the handle is invalid or if it's not an object with a ring-3 mapping.
  78  *          Strict builds will assert in both cases.
  79  * @param   MemObj  The ring-0 memory object handle.
  80  */
  81 RTR0DECL(RTR3PTR) RTR0MemObjAddressR3(RTR0MEMOBJ MemObj);
  82
  83 /**
  84  * Gets the size of a ring-0 memory object.
  85  *
  86  * The returned value may differ from the one specified to the API creating the
  87  * object because of alignment adjustments.  The minimal alignment currently
  88  * employed by any API is PAGE_SIZE, so the result can safely be shifted by
  89  * PAGE_SHIFT to calculate a page count.
  90  *
  91  * @returns The object size.
  92  * @returns 0 if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
  93  * @param   MemObj  The ring-0 memory object handle.
  94  */
  95 RTR0DECL(size_t) RTR0MemObjSize(RTR0MEMOBJ MemObj);
  96
  97 /**
  98  * Get the physical address of an page in the memory object.
  99  *
 100  * @returns The physical address.
 101  * @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
 102  * @returns NIL_RTHCPHYS if the iPage is out of range.
 103  * @returns NIL_RTHCPHYS if the object handle isn't valid.
 104  * @param   MemObj  The ring-0 memory object handle.
 105  * @param   iPage   The page number within the object.
 106  */
 107 RTR0DECL(RTHCPHYS) RTR0MemObjGetPagePhysAddr(RTR0MEMOBJ MemObj, size_t iPage);
 108
 109 /**
 110  * Frees a ring-0 memory object.
 111  *
 112  * @returns IPRT status code.
 113  * @retval  VERR_INVALID_HANDLE if
 114  * @param   MemObj          The ring-0 memory object to be freed. NULL is accepted.
 115  * @param   fFreeMappings   Whether or not to free mappings of the object.
 116  */
 117 RTR0DECL(int) RTR0MemObjFree(RTR0MEMOBJ MemObj, bool fFreeMappings);
 118
 119 /**
 120  * Allocates page aligned virtual kernel memory (default tag).
 121  *
 122  * The memory is taken from a non paged (= fixed physical memory backing) pool.
 123  *
 124  * @returns IPRT status code.
 125  * @param   pMemObj         Where to store the ring-0 memory object handle.
 126  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 127  * @param   fExecutable     Flag indicating whether it should be permitted to executed code in the memory object.
 128  */
 129 #define RTR0MemObjAllocPage(pMemObj, cb, fExecutable) \
 130     RTR0MemObjAllocPageTag((pMemObj), (cb), (fExecutable), RTMEM_TAG)
 131
 132 /**
 133  * Allocates page aligned virtual kernel memory (custom tag).
 134  *
 135  * The memory is taken from a non paged (= fixed physical memory backing) pool.
 136  *
 137  * @returns IPRT status code.
 138  * @param   pMemObj         Where to store the ring-0 memory object handle.
 139  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 140  * @param   fExecutable     Flag indicating whether it should be permitted to executed code in the memory object.
 141  * @param   pszTag          Allocation tag used for statistics and such.
 142  */
 143 RTR0DECL(int) RTR0MemObjAllocPageTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag);
 144
 145 /**
 146  * Allocates page aligned virtual kernel memory with physical backing below 4GB
 147  * (default tag).
 148  *
 149  * The physical memory backing the allocation is fixed.
 150  *
 151  * @returns IPRT status code.
 152  * @param   pMemObj         Where to store the ring-0 memory object handle.
 153  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 154  * @param   fExecutable     Flag indicating whether it should be permitted to executed code in the memory object.
 155  */
 156 #define RTR0MemObjAllocLow(pMemObj, cb, fExecutable) \
 157     RTR0MemObjAllocLowTag((pMemObj), (cb), (fExecutable), RTMEM_TAG)
 158
 159 /**
 160  * Allocates page aligned virtual kernel memory with physical backing below 4GB
 161  * (custom tag).
 162  *
 163  * The physical memory backing the allocation is fixed.
 164  *
 165  * @returns IPRT status code.
 166  * @param   pMemObj         Where to store the ring-0 memory object handle.
 167  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 168  * @param   fExecutable     Flag indicating whether it should be permitted to executed code in the memory object.
 169  * @param   pszTag          Allocation tag used for statistics and such.
 170  */
 171 RTR0DECL(int) RTR0MemObjAllocLowTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag);
 172
 173 /**
 174  * Allocates page aligned virtual kernel memory with contiguous physical backing
 175  * below 4GB (default tag).
 176  *
 177  * The physical memory backing the allocation is fixed.
 178  *
 179  * @returns IPRT status code.
 180  * @param   pMemObj         Where to store the ring-0 memory object handle.
 181  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 182  * @param   fExecutable     Flag indicating whether it should be permitted to executed code in the memory object.
 183  */
 184 #define RTR0MemObjAllocCont(pMemObj, cb, fExecutable) \
 185     RTR0MemObjAllocContTag((pMemObj), (cb), (fExecutable), RTMEM_TAG)
 186
 187 /**
 188  * Allocates page aligned virtual kernel memory with contiguous physical backing
 189  * below 4GB (custom tag).
 190  *
 191  * The physical memory backing the allocation is fixed.
 192  *
 193  * @returns IPRT status code.
 194  * @param   pMemObj         Where to store the ring-0 memory object handle.
 195  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 196  * @param   fExecutable     Flag indicating whether it should be permitted to executed code in the memory object.
 197  * @param   pszTag          Allocation tag used for statistics and such.
 198  */
 199 RTR0DECL(int) RTR0MemObjAllocContTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag);
 200
 201 /**
 202  * Locks a range of user virtual memory (default tag).
 203  *
 204  * @returns IPRT status code.
 205  * @param   pMemObj         Where to store the ring-0 memory object handle.
 206  * @param   R3Ptr           User virtual address. This is rounded down to a page
 207  *                          boundary.
 208  * @param   cb              Number of bytes to lock. This is rounded up to
 209  *                          nearest page boundary.
 210  * @param   fAccess         The desired access, a combination of RTMEM_PROT_READ
 211  *                          and RTMEM_PROT_WRITE.
 212  * @param   R0Process       The process to lock pages in. NIL_R0PROCESS is an
 213  *                          alias for the current one.
 214  *
 215  * @remarks RTR0MemGetAddressR3() and RTR0MemGetAddress() will return therounded
 216  *          down address.
 217  *
 218  * @remarks Linux: This API requires that the memory begin locked is in a memory
 219  *          mapping that is not required in any forked off child process. This
 220  *          is not intented as permanent restriction, feel free to help out
 221  *          lifting it.
 222  */
 223 #define RTR0MemObjLockUser(pMemObj, R3Ptr, cb, fAccess, R0Process) \
 224     RTR0MemObjLockUserTag((pMemObj), (R3Ptr), (cb), (fAccess), (R0Process), RTMEM_TAG)
 225
 226 /**
 227  * Locks a range of user virtual memory (custom tag).
 228  *
 229  * @returns IPRT status code.
 230  * @param   pMemObj         Where to store the ring-0 memory object handle.
 231  * @param   R3Ptr           User virtual address. This is rounded down to a page
 232  *                          boundary.
 233  * @param   cb              Number of bytes to lock. This is rounded up to
 234  *                          nearest page boundary.
 235  * @param   fAccess         The desired access, a combination of RTMEM_PROT_READ
 236  *                          and RTMEM_PROT_WRITE.
 237  * @param   R0Process       The process to lock pages in. NIL_R0PROCESS is an
 238  *                          alias for the current one.
 239  * @param   pszTag          Allocation tag used for statistics and such.
 240  *
 241  * @remarks RTR0MemGetAddressR3() and RTR0MemGetAddress() will return therounded
 242  *          down address.
 243  *
 244  * @remarks Linux: This API requires that the memory begin locked is in a memory
 245  *          mapping that is not required in any forked off child process. This
 246  *          is not intented as permanent restriction, feel free to help out
 247  *          lifting it.
 248  */
 249 RTR0DECL(int) RTR0MemObjLockUserTag(PRTR0MEMOBJ pMemObj, RTR3PTR R3Ptr, size_t cb, uint32_t fAccess,
 250                                     RTR0PROCESS R0Process, const char *pszTag);
 251
 252 /**
 253  * Locks a range of kernel virtual memory (default tag).
 254  *
 255  * @returns IPRT status code.
 256  * @param   pMemObj         Where to store the ring-0 memory object handle.
 257  * @param   pv              Kernel virtual address. This is rounded down to a page boundary.
 258  * @param   cb              Number of bytes to lock. This is rounded up to nearest page boundary.
 259  * @param   fAccess         The desired access, a combination of RTMEM_PROT_READ
 260  *                          and RTMEM_PROT_WRITE.
 261  *
 262  * @remark  RTR0MemGetAddress() will return the rounded down address.
 263  */
 264 #define RTR0MemObjLockKernel(pMemObj, pv, cb, fAccess) \
 265     RTR0MemObjLockKernelTag((pMemObj), (pv), (cb), (fAccess), RTMEM_TAG)
 266
 267 /**
 268  * Locks a range of kernel virtual memory (custom tag).
 269  *
 270  * @returns IPRT status code.
 271  * @param   pMemObj         Where to store the ring-0 memory object handle.
 272  * @param   pv              Kernel virtual address. This is rounded down to a page boundary.
 273  * @param   cb              Number of bytes to lock. This is rounded up to nearest page boundary.
 274  * @param   fAccess         The desired access, a combination of RTMEM_PROT_READ
 275  *                          and RTMEM_PROT_WRITE.
 276  * @param   pszTag          Allocation tag used for statistics and such.
 277  *
 278  * @remark  RTR0MemGetAddress() will return the rounded down address.
 279  */
 280 RTR0DECL(int) RTR0MemObjLockKernelTag(PRTR0MEMOBJ pMemObj, void *pv, size_t cb, uint32_t fAccess, const char *pszTag);
 281
 282 /**
 283  * Allocates contiguous page aligned physical memory without (necessarily) any
 284  * kernel mapping (default tag).
 285  *
 286  * @returns IPRT status code.
 287  * @param   pMemObj         Where to store the ring-0 memory object handle.
 288  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 289  * @param   PhysHighest     The highest permitable address (inclusive).
 290  *                          Pass NIL_RTHCPHYS if any address is acceptable.
 291  */
 292 #define RTR0MemObjAllocPhys(pMemObj, cb, PhysHighest) \
 293     RTR0MemObjAllocPhysTag((pMemObj), (cb), (PhysHighest), RTMEM_TAG)
 294
 295 /**
 296  * Allocates contiguous page aligned physical memory without (necessarily) any
 297  * kernel mapping (custom tag).
 298  *
 299  * @returns IPRT status code.
 300  * @param   pMemObj         Where to store the ring-0 memory object handle.
 301  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 302  * @param   PhysHighest     The highest permitable address (inclusive).
 303  *                          Pass NIL_RTHCPHYS if any address is acceptable.
 304  * @param   pszTag          Allocation tag used for statistics and such.
 305  */
 306 RTR0DECL(int) RTR0MemObjAllocPhysTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, const char *pszTag);
 307
 308 /**
 309  * Allocates contiguous physical memory without (necessarily) any kernel mapping
 310  * (default tag).
 311  *
 312  * @returns IPRT status code.
 313  * @param   pMemObj         Where to store the ring-0 memory object handle.
 314  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 315  * @param   PhysHighest     The highest permitable address (inclusive).
 316  *                          Pass NIL_RTHCPHYS if any address is acceptable.
 317  * @param   uAlignment      The alignment of the reserved memory.
 318  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M, _4M and _1G.
 319  */
 320 #define RTR0MemObjAllocPhysEx(pMemObj, cb, PhysHighest, uAlignment) \
 321     RTR0MemObjAllocPhysExTag((pMemObj), (cb), (PhysHighest), (uAlignment), RTMEM_TAG)
 322
 323 /**
 324  * Allocates contiguous physical memory without (necessarily) any kernel mapping
 325  * (custom tag).
 326  *
 327  * @returns IPRT status code.
 328  * @param   pMemObj         Where to store the ring-0 memory object handle.
 329  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 330  * @param   PhysHighest     The highest permitable address (inclusive).
 331  *                          Pass NIL_RTHCPHYS if any address is acceptable.
 332  * @param   uAlignment      The alignment of the reserved memory.
 333  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M, _4M and _1G.
 334  * @param   pszTag          Allocation tag used for statistics and such.
 335  */
 336 RTR0DECL(int) RTR0MemObjAllocPhysExTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, size_t uAlignment, const char *pszTag);
 337
 338 /**
 339  * Allocates non-contiguous page aligned physical memory without (necessarily)
 340  * any kernel mapping (default tag).
 341  *
 342  * This API is for allocating huge amounts of pages and will return
 343  * VERR_NOT_SUPPORTED if this cannot be implemented in a satisfactory
 344  * manner.
 345  *
 346  * @returns IPRT status code.
 347  * @retval  VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
 348  *          physical memory on this platform. The caller should expect
 349  *          this error and have a fallback strategy for it.
 350  *
 351  * @param   pMemObj         Where to store the ring-0 memory object handle.
 352  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 353  * @param   PhysHighest     The highest permitable address (inclusive).
 354  *                          Pass NIL_RTHCPHYS if any address is acceptable.
 355  */
 356 #define RTR0MemObjAllocPhysNC(pMemObj, cb, PhysHighest) \
 357     RTR0MemObjAllocPhysNCTag((pMemObj), (cb), (PhysHighest), RTMEM_TAG)
 358
 359 /**
 360  * Allocates non-contiguous page aligned physical memory without (necessarily)
 361  * any kernel mapping (custom tag).
 362  *
 363  * This API is for allocating huge amounts of pages and will return
 364  * VERR_NOT_SUPPORTED if this cannot be implemented in a satisfactory
 365  * manner.
 366  *
 367  * @returns IPRT status code.
 368  * @retval  VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
 369  *          physical memory on this platform. The caller should expect
 370  *          this error and have a fallback strategy for it.
 371  *
 372  * @param   pMemObj         Where to store the ring-0 memory object handle.
 373  * @param   cb              Number of bytes to allocate. This is rounded up to nearest page.
 374  * @param   PhysHighest     The highest permitable address (inclusive).
 375  *                          Pass NIL_RTHCPHYS if any address is acceptable.
 376  * @param   pszTag          Allocation tag used for statistics and such.
 377  */
 378 RTR0DECL(int) RTR0MemObjAllocPhysNCTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, const char *pszTag);
 379
 380 /** Memory cache policy for RTR0MemObjEnterPhys.
 381  * @{
 382  */
 383 /** Default caching policy -- don't care. */
 384 #define RTMEM_CACHE_POLICY_DONT_CARE    UINT32_C(0)
 385 /** MMIO caching policy -- uncachable. */
 386 #define RTMEM_CACHE_POLICY_MMIO         UINT32_C(1)
 387 /** @} */
 388
 389 /**
 390  * Creates a page aligned, contiguous, physical memory object (default tag).
 391  *
 392  * No physical memory is allocated, we trust you do know what you're doing.
 393  *
 394  * @returns IPRT status code.
 395  * @param   pMemObj         Where to store the ring-0 memory object handle.
 396  * @param   Phys            The physical address to start at. This is rounded down to the
 397  *                          nearest page boundary.
 398  * @param   cb              The size of the object in bytes. This is rounded up to nearest page boundary.
 399  * @param   uCachePolicy    One of the RTMEM_CACHE_XXX modes.
 400  */
 401 #define RTR0MemObjEnterPhys(pMemObj, Phys, cb, uCachePolicy) \
 402     RTR0MemObjEnterPhysTag((pMemObj), (Phys), (cb), (uCachePolicy), RTMEM_TAG)
 403
 404 /**
 405  * Creates a page aligned, contiguous, physical memory object (custom tag).
 406  *
 407  * No physical memory is allocated, we trust you do know what you're doing.
 408  *
 409  * @returns IPRT status code.
 410  * @param   pMemObj         Where to store the ring-0 memory object handle.
 411  * @param   Phys            The physical address to start at. This is rounded down to the
 412  *                          nearest page boundary.
 413  * @param   cb              The size of the object in bytes. This is rounded up to nearest page boundary.
 414  * @param   uCachePolicy    One of the RTMEM_CACHE_XXX modes.
 415  * @param   pszTag          Allocation tag used for statistics and such.
 416  */
 417 RTR0DECL(int) RTR0MemObjEnterPhysTag(PRTR0MEMOBJ pMemObj, RTHCPHYS Phys, size_t cb, uint32_t uCachePolicy, const char *pszTag);
 418
 419 /**
 420  * Reserves kernel virtual address space (default tag).
 421  *
 422  * If this function fails with VERR_NOT_SUPPORTED, the idea is that you
 423  * can use RTR0MemObjEnterPhys() + RTR0MemObjMapKernel() as a fallback if
 424  * you have a safe physical address range to make use of...
 425  *
 426  * @returns IPRT status code.
 427  * @param   pMemObj         Where to store the ring-0 memory object handle.
 428  * @param   pvFixed         Requested address. (void *)-1 means any address. This must match the alignment.
 429  * @param   cb              The number of bytes to reserve. This is rounded up to nearest page.
 430  * @param   uAlignment      The alignment of the reserved memory.
 431  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 432  */
 433 #define RTR0MemObjReserveKernel(pMemObj, pvFixed, cb, uAlignment) \
 434     RTR0MemObjReserveKernelTag((pMemObj), (pvFixed), (cb), (uAlignment), RTMEM_TAG)
 435
 436 /**
 437  * Reserves kernel virtual address space (custom tag).
 438  *
 439  * If this function fails with VERR_NOT_SUPPORTED, the idea is that you
 440  * can use RTR0MemObjEnterPhys() + RTR0MemObjMapKernel() as a fallback if
 441  * you have a safe physical address range to make use of...
 442  *
 443  * @returns IPRT status code.
 444  * @param   pMemObj         Where to store the ring-0 memory object handle.
 445  * @param   pvFixed         Requested address. (void *)-1 means any address. This must match the alignment.
 446  * @param   cb              The number of bytes to reserve. This is rounded up to nearest page.
 447  * @param   uAlignment      The alignment of the reserved memory.
 448  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 449  * @param   pszTag          Allocation tag used for statistics and such.
 450  */
 451 RTR0DECL(int) RTR0MemObjReserveKernelTag(PRTR0MEMOBJ pMemObj, void *pvFixed, size_t cb, size_t uAlignment, const char *pszTag);
 452
 453 /**
 454  * Reserves user virtual address space in the current process (default tag).
 455  *
 456  * @returns IPRT status code.
 457  * @param   pMemObj         Where to store the ring-0 memory object handle.
 458  * @param   R3PtrFixed      Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
 459  * @param   cb              The number of bytes to reserve. This is rounded up to nearest PAGE_SIZE.
 460  * @param   uAlignment      The alignment of the reserved memory.
 461  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 462  * @param   R0Process       The process to reserve the memory in. NIL_R0PROCESS is an alias for the current one.
 463  */
 464 #define RTR0MemObjReserveUser(pMemObj, R3PtrFixed, cb, uAlignment, R0Process) \
 465     RTR0MemObjReserveUserTag((pMemObj), (R3PtrFixed), (cb), (uAlignment), (R0Process), RTMEM_TAG)
 466
 467 /**
 468  * Reserves user virtual address space in the current process (custom tag).
 469  *
 470  * @returns IPRT status code.
 471  * @param   pMemObj         Where to store the ring-0 memory object handle.
 472  * @param   R3PtrFixed      Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
 473  * @param   cb              The number of bytes to reserve. This is rounded up to nearest PAGE_SIZE.
 474  * @param   uAlignment      The alignment of the reserved memory.
 475  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 476  * @param   R0Process       The process to reserve the memory in. NIL_R0PROCESS is an alias for the current one.
 477  * @param   pszTag          Allocation tag used for statistics and such.
 478  */
 479 RTR0DECL(int) RTR0MemObjReserveUserTag(PRTR0MEMOBJ pMemObj, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment,
 480                                        RTR0PROCESS R0Process, const char *pszTag);
 481
 482 /**
 483  * Maps a memory object into kernel virtual address space (default tag).
 484  *
 485  * This is the same as calling RTR0MemObjMapKernelEx with cbSub and offSub set
 486  * to zero.
 487  *
 488  * @returns IPRT status code.
 489  * @param   pMemObj         Where to store the ring-0 memory object handle of the mapping object.
 490  * @param   MemObjToMap     The object to be map.
 491  * @param   pvFixed         Requested address. (void *)-1 means any address. This must match the alignment.
 492  * @param   uAlignment      The alignment of the reserved memory.
 493  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 494  * @param   fProt           Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
 495  */
 496 #define RTR0MemObjMapKernel(pMemObj, MemObjToMap, pvFixed, uAlignment, fProt) \
 497     RTR0MemObjMapKernelTag((pMemObj), (MemObjToMap), (pvFixed), (uAlignment), (fProt), RTMEM_TAG)
 498
 499 /**
 500  * Maps a memory object into kernel virtual address space (custom tag).
 501  *
 502  * This is the same as calling RTR0MemObjMapKernelEx with cbSub and offSub set
 503  * to zero.
 504  *
 505  * @returns IPRT status code.
 506  * @param   pMemObj         Where to store the ring-0 memory object handle of the mapping object.
 507  * @param   MemObjToMap     The object to be map.
 508  * @param   pvFixed         Requested address. (void *)-1 means any address. This must match the alignment.
 509  * @param   uAlignment      The alignment of the reserved memory.
 510  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 511  * @param   fProt           Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
 512  * @param   pszTag          Allocation tag used for statistics and such.
 513  */
 514 RTR0DECL(int) RTR0MemObjMapKernelTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed,
 515                                      size_t uAlignment, unsigned fProt, const char *pszTag);
 516
 517 /**
 518  * Maps a memory object into kernel virtual address space (default tag).
 519  *
 520  * The ability to map subsections of the object into kernel space is currently
 521  * not implemented on all platforms. All/Most of platforms supports mapping the
 522  * whole object into  kernel space.
 523  *
 524  * @returns IPRT status code.
 525  * @retval  VERR_NOT_SUPPORTED if it's not possible to map a subsection of a
 526  *          memory object on this platform. When you hit this, try implement it.
 527  *
 528  * @param   pMemObj         Where to store the ring-0 memory object handle of the mapping object.
 529  * @param   MemObjToMap     The object to be map.
 530  * @param   pvFixed         Requested address. (void *)-1 means any address. This must match the alignment.
 531  * @param   uAlignment      The alignment of the reserved memory.
 532  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 533  * @param   fProt           Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
 534  * @param   offSub          Where in the object to start mapping. If non-zero
 535  *                          the value must be page aligned and cbSub must be
 536  *                          non-zero as well.
 537  * @param   cbSub           The size of the part of the object to be mapped. If
 538  *                          zero the entire object is mapped. The value must be
 539  *                          page aligned.
 540  */
 541 #define RTR0MemObjMapKernelEx(pMemObj, MemObjToMap, pvFixed, uAlignment, fProt, offSub, cbSub) \
 542     RTR0MemObjMapKernelExTag((pMemObj), (MemObjToMap), (pvFixed), (uAlignment), (fProt), (offSub), (cbSub), RTMEM_TAG)
 543
 544 /**
 545  * Maps a memory object into kernel virtual address space (custom tag).
 546  *
 547  * The ability to map subsections of the object into kernel space is currently
 548  * not implemented on all platforms. All/Most of platforms supports mapping the
 549  * whole object into  kernel space.
 550  *
 551  * @returns IPRT status code.
 552  * @retval  VERR_NOT_SUPPORTED if it's not possible to map a subsection of a
 553  *          memory object on this platform. When you hit this, try implement it.
 554  *
 555  * @param   pMemObj         Where to store the ring-0 memory object handle of the mapping object.
 556  * @param   MemObjToMap     The object to be map.
 557  * @param   pvFixed         Requested address. (void *)-1 means any address. This must match the alignment.
 558  * @param   uAlignment      The alignment of the reserved memory.
 559  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 560  * @param   fProt           Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
 561  * @param   offSub          Where in the object to start mapping. If non-zero
 562  *                          the value must be page aligned and cbSub must be
 563  *                          non-zero as well.
 564  * @param   cbSub           The size of the part of the object to be mapped. If
 565  *                          zero the entire object is mapped. The value must be
 566  *                          page aligned.
 567  * @param   pszTag          Allocation tag used for statistics and such.
 568  */
 569 RTR0DECL(int) RTR0MemObjMapKernelExTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed, size_t uAlignment,
 570                                        unsigned fProt, size_t offSub, size_t cbSub, const char *pszTag);
 571
 572 /**
 573  * Maps a memory object into user virtual address space in the current process
 574  * (default tag).
 575  *
 576  * @returns IPRT status code.
 577  * @param   pMemObj         Where to store the ring-0 memory object handle of the mapping object.
 578  * @param   MemObjToMap     The object to be map.
 579  * @param   R3PtrFixed      Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
 580  * @param   uAlignment      The alignment of the reserved memory.
 581  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 582  * @param   fProt           Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
 583  * @param   R0Process       The process to map the memory into. NIL_R0PROCESS is an alias for the current one.
 584  */
 585 #define RTR0MemObjMapUser(pMemObj, MemObjToMap, R3PtrFixed, uAlignment, fProt, R0Process) \
 586     RTR0MemObjMapUserTag((pMemObj), (MemObjToMap), (R3PtrFixed), (uAlignment), (fProt), (R0Process), RTMEM_TAG)
 587
 588 /**
 589  * Maps a memory object into user virtual address space in the current process
 590  * (custom tag).
 591  *
 592  * @returns IPRT status code.
 593  * @param   pMemObj         Where to store the ring-0 memory object handle of the mapping object.
 594  * @param   MemObjToMap     The object to be map.
 595  * @param   R3PtrFixed      Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
 596  * @param   uAlignment      The alignment of the reserved memory.
 597  *                          Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
 598  * @param   fProt           Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
 599  * @param   R0Process       The process to map the memory into. NIL_R0PROCESS is an alias for the current one.
 600  * @param   pszTag          Allocation tag used for statistics and such.
 601  */
 602 RTR0DECL(int) RTR0MemObjMapUserTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, RTR3PTR R3PtrFixed,
 603                                    size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process, const char *pszTag);
 604
 605 /**
 606  * Change the page level protection of one or more pages in a memory object.
 607  *
 608  * @returns IPRT status code.
 609  * @retval  VERR_NOT_SUPPORTED if the OS doesn't provide any way to manipulate
 610  *          page level protection. The caller must handle this status code
 611  *          gracefully. (Note that it may also occur if the implementation is
 612  *          missing, in which case just go ahead and implement it.)
 613  *
 614  * @param   hMemObj         Memory object handle.
 615  * @param   offSub          Offset into the memory object. Must be page aligned.
 616  * @param   cbSub           Number of bytes to change the protection of. Must be
 617  *                          page aligned.
 618  * @param   fProt           Combination of RTMEM_PROT_* flags.
 619  */
 620 RTR0DECL(int) RTR0MemObjProtect(RTR0MEMOBJ hMemObj, size_t offSub, size_t cbSub, uint32_t fProt);
 621
 622 #endif /* IN_RING0 */
 623
 624 /** @} */
 625
 626 RT_C_DECLS_END
 627
 628 #endif
 629