reactos/include/ddk/mmfuncs.h

   1 /* MEMORY MANAGMENT ******************************************************/
   2
   3 #include <internal/hal/page.h>
   4
   5 /*
   6  * FUNCTION: Determines if the given virtual address is page aligned
   7  */
   8 #define IS_PAGE_ALIGNED(Va) (((ULONG)Va)&0xfff)
   9
  10 /*
  11  * PURPOSE: Returns the byte offset of a field within a structure
  12  */
  13 #define FIELD_OFFSET(Type,Field) (LONG)(&(((Type *)(0))->Field))
  14
  15 /*
  16  * PURPOSE: Returns the base address structure if the caller knows the
  17  * address of a field within the structure
  18  * ARGUMENTS:
  19  *          Address = address of the field
  20  *          Type = Type of the whole structure
  21  *          Field = Name of the field whose address is none
  22  */
  23 #define CONTAINING_RECORD(Address,Type,Field) (Type *)(((LONG)Address) - FIELD_OFFSET(Type,Field))
  24
  25 /*
  26  * FUNCTION: Returns the number of pages spanned by an address range
  27  * ARGUMENTS:
  28  *          Va = start of range
  29  *          Size = Size of range
  30  * RETURNS: The number of pages
  31  */
  32 extern inline unsigned int ADDRESS_AND_SIZE_TO_SPAN_PAGES(PVOID Va,
  33                                                           ULONG Size)
  34 {
  35    ULONG HighestAddr;
  36    ULONG LowestAddr;
  37
  38    HighestAddr = PAGE_ROUND_UP(Size + ((ULONG)Va));
  39    LowestAddr = PAGE_ROUND_DOWN((ULONG)Va);
  40    return((HighestAddr - LowestAddr) / PAGESIZE);
  41 }
  42
  43 /*
  44  * FUNCTION: Returns FALSE is the pointer is NULL, TRUE otherwise
  45  */
  46 #define ARGUMENT_PRESENT(arg) ((arg)!=NULL)
  47
  48 /*
  49  * FUNCTION: Returns the byte offset of the address within its page
  50  */
  51 #define BYTE_OFFSET(va) (((ULONG)va)%PAGESIZE)
  52
  53 /*
  54  * FUNCTION: Takes a count in bytes and returns the number of pages
  55  * required to hold it
  56  */
  57 #define BYTES_TO_PAGES(size) (?)
  58
  59 /*
  60  * FUNCTION: Allocates a range of physically contiguous cache aligned
  61  * memory from the non-paged pool
  62  * ARGUMENTS:
  63  *          NumberOfBytes = Size of the memory block to allocate
  64  *          HighestAcceptableAddress = Highest address valid for the caller
  65  * RETURNS: The virtual address of the memory block on success
  66  *          NULL on error
  67  */
  68 PVOID MmAllocateContiguousMemory(ULONG NumberOfBytes,
  69                                  PHYSICAL_ADDRESS HighestAcceptableAddress);
  70
  71 /*
  72  * FUNCTION: Allocates a virtual address range of noncached and cache
  73  * aligned memory
  74  * ARGUMENTS:
  75  *         NumberOfBytes = Size of region to allocate
  76  * RETURNS: The base address of the range on success
  77  *          NULL on failure
  78  */
  79 PVOID MmAllocateNonCachedMemory(ULONG NumberOfBytes);
  80
  81 /*
  82  * FUNCTION: Fills in the corresponding physical page array for a given MDL
  83  * for a buffer in nonpaged system space
  84  * ARGUMENTS:
  85  *        MemoryDescriptorList = MDL to fill
  86  */
  87 VOID MmBuildMdlForNonPagedPool(PMDL MemoryDescriptorList);
  88
  89 /*
  90  * FUNCTION: Allocates and initializes an MDL
  91  * ARGUMENTS:
  92  *        MemoryDescriptorList = Optional caller allocated MDL to initalize
  93  *        Base = Base virtual address for buffer
  94  *        Length = Length in bytes of the buffer
  95  * RETURNS: A pointer to the initalized MDL
  96  */
  97 PMDL MmCreateMdl(PMDL MemoryDescriptorList, PVOID Base, ULONG Length);
  98
  99 /*
 100  * FUNCTION: Releases a range of physically contiguous memory allocated
 101  * with MmAllocateContiguousMemory
 102  * ARGUMENTS:
 103  *         BaseAddress = Vritual address of the memory to be freed
 104  */
 105 VOID MmFreeContiguousMemory(PVOID BaseAddress);
 106
 107 /*
 108  * FUNCTION: Releases a range of noncached memory allocated with
 109  * MmAllocateNonCachedMemory
 110  * ARGUMENTS:
 111  *         BaseAddress = Virtual address to be freed
 112  *         NumberOfBytes = size of the region to be freed
 113  */
 114 VOID MmFreeNonCachedMemory(PVOID BaseAddress, ULONG NumberOfBytes);
 115
 116 /*
 117  * FUNCTION: Returns the length in bytes of a buffer described by an MDL
 118  * ARGUMENTS:
 119  *         Mdl = the mdl
 120  * RETURNS: Size of the buffer
 121  */
 122 ULONG MmGetMdlByteCount(PMDL Mdl);
 123
 124 /*
 125  * FUNCTION: Returns the byte offset within a page of the buffer described
 126  * by an MDL
 127  * ARGUMENTS:
 128  *         Mdl = the mdl
 129  * RETURNS: The offset in bytes
 130  */
 131 ULONG MmGetMdlByteOffset(PMDL Mdl);
 132
 133 /*
 134  * FUNCTION: Returns the initial virtual address for a buffer described
 135  * by an MDL
 136  * ARGUMENTS:
 137  *        Mdl = the mdl
 138  * RETURNS: The initial virtual address
 139  */
 140 PVOID MmGetMdlVirtualAddress(PMDL Mdl);
 141
 142 /*
 143  * FUNCTION: Returns the physical address corresponding to a given valid
 144  * virtual address
 145  * ARGUMENTS:
 146  *       BaseAddress = the virtual address
 147  * RETURNS: The physical address
 148  */
 149 PHYSICAL_ADDRESS MmGetPhysicalAddress(PVOID BaseAddress);
 150
 151 /*
 152  * FUNCTION: Maps the physical pages described by an MDL into system space
 153  * ARGUMENTS:
 154  *      Mdl = mdl
 155  * RETURNS: The base system address for the mapped buffer
 156  */
 157 PVOID MmGetSystemAddressForMdl(PMDL Mdl);
 158
 159 /*
 160  * FUNCTION: Initalizes an mdl
 161  * ARGUMENTS:
 162  *       MemoryDescriptorList = MDL to be initalized
 163  *       BaseVa = Base virtual address of the buffer
 164  *       Length = Length in bytes of the buffer
 165  */
 166 VOID MmInitializeMdl(PMDL MemoryDescriptorList, PVOID BaseVa, ULONG Length);
 167
 168 /*
 169  * FUNCTION: Checks whether an address is valid for read/write
 170  * ARGUMENTS:
 171  *       VirtualAddress = address to be check
 172  * RETURNS: TRUE if an access would be valid
 173  */
 174 BOOLEAN MmIsAddressValid(PVOID VirtualAddress);
 175
 176 /*
 177  * FUNCTION: Checks if the current platform is a workstation or a server
 178  * RETURNS: If the system is a server returns true
 179  * NOTE: Drivers can use this as an estimate of the likely resources
 180  * available
 181  */
 182 BOOLEAN MmIsThisAnAsSystem(VOID);
 183
 184 /*
 185  * FUNCTION: Locks a section of the driver's code into memory
 186  * ARGUMENTS:
 187  *        AddressWithinSection = Any address in the region
 188  * RETURNS: A handle to the region
 189  */
 190 PVOID MmLockPagableCodeSection(PVOID AddressWithinSection);
 191
 192 /*
 193  * FUNCTION: Locks a section of the driver's data into memory
 194  * ARGUMENTS:
 195  *        AddressWithinSection = Any address in the region
 196  * RETURNS: A handle to the region
 197  */
 198 PVOID MmLockPagableDataSection(PVOID AddressWithinSection);
 199
 200 /*
 201  * FUNCTION: Locks a section of memory
 202  * ARGUMENTS:
 203  *         ImageSectionHandle = handle returned from MmLockPagableCodeSection
 204  *                              or MmLockPagableDataSection
 205  */
 206 VOID MmLockPagableSectionByHandle(PVOID ImageSectionHandle);
 207
 208 /*
 209  * FUNCTION: Maps a physical memory range into system space
 210  * ARGUMENTS:
 211  *         PhysicalAddress = First physical address to map
 212  *         NumberOfBytes = Number of bytes to map
 213  *         CacheEnable = TRUE if the range can be cached
 214  * RETURNS: The base virtual address which maps the region
 215  */
 216 PVOID MmMapIoSpace(PHYSICAL_ADDRESS PhysicalAddress, ULONG NumberOfBytes,
 217                    BOOLEAN CacheEnable);
 218
 219 /*
 220  * FUNCTION: Maps the pages described by a given MDL
 221  * ARGUMENTS:
 222  *        MemoryDescriptorList = MDL updated by MmProbeAndLockPages
 223  *        AccessMode = Access mode in which to map the MDL
 224  * RETURNS: The base virtual address which maps the buffer
 225  */
 226 PVOID MmMapLockedPages(PMDL MemoryDescriptorList, KPROCESSOR_MODE AccessMode);
 227
 228 /*
 229  * FUNCTION: Makes the whole driver pageable
 230  * ARGUMENTS:
 231  *         AddressWithinSection = Any address within the driver
 232  */
 233 VOID MmPageEntireDriver(PVOID AddressWithinSection);
 234
 235 /*
 236  * FUNCTION: Resets the pageable status of a driver's sections to their
 237  * compile time settings
 238  * ARGUMENTS:
 239  *         AddressWithinSection = Any address within the driver
 240  */
 241 VOID MmResetDriverPaging(PVOID AddressWithinSection);
 242
 243 /*
 244  * FUNCTION: Reinitializes a caller-allocated MDL
 245  * ARGUMENTS:
 246  *         Mdl = Points to the MDL that will be reused
 247  */
 248 VOID MmPrepareMdlForReuse(PMDL Mdl);
 249
 250 /*
 251  * FUNCTION: Probes the specified pages, makes them resident and locks
 252  * the physical pages mapped by the virtual address range
 253  * ARGUMENTS:
 254  *         MemoryDescriptorList = MDL which supplies the virtual address,
 255  *                                byte offset and length
 256  *         AccessMode = Access mode with which to probe the arguments
 257  *         Operation = Types of operation for which the pages should be
 258  *                     probed
 259  */
 260 VOID MmProbeAndLockPages(PMDL MemoryDescriptorList,
 261                          KPROCESSOR_MODE AccessMode,
 262                          LOCK_OPERATION Operation);
 263
 264 /*
 265  * FUNCTION: Returns an estimate of the amount of memory in the system
 266  * RETURNS: Either MmSmallSystem, MmMediumSystem or MmLargeSystem
 267  */
 268 MM_SYSTEM_SIZE MmQuerySystemSize(VOID);
 269
 270 /*
 271  * FUNCTION: Returns the number of bytes to allocate for an MDL
 272  * describing a given address range
 273  * ARGUMENTS:
 274  *          Base = Base virtual address for the region
 275  *          Length = size in bytes of the region
 276  * RETURNS: The number of bytes required for the MDL
 277  */
 278 ULONG MmSizeOfMdl(PVOID Base, ULONG Length);
 279
 280 /*
 281  * FUNCTION: Unlocks the physical pages described by a given MDL
 282  * ARGUMENTS:
 283  *          Mdl = Mdl to unlock
 284  */
 285 VOID MmUnlockPages(PMDL Mdl);
 286
 287 /*
 288  * FUNCTION: Releases a section of driver code or data previously locked into
 289  * memory
 290  * ARGUMENTS:
 291  *         ImageSectionHandle = Handle for the locked section
 292  */
 293 VOID MmUnlockPagableImageSection(PVOID ImageSectionHandle);
 294
 295 VOID MmUnmapIoSpace(PVOID BaseAddress, ULONG NumberOfBytes);
 296 VOID MmUnmapLockedPages(PVOID BaseAddress, PMDL MemoryDescriptorList);
 297 PVOID MmAllocateSection(ULONG Length);