osfmk/vm/pmap.h

   1 /*
   2  * Copyright (c) 2000-2007 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  * @OSF_COPYRIGHT@
  30  */
  31 /*
  32  * Mach Operating System
  33  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  34  * All Rights Reserved.
  35  *
  36  * Permission to use, copy, modify and distribute this software and its
  37  * documentation is hereby granted, provided that both the copyright
  38  * notice and this permission notice appear in all copies of the
  39  * software, derivative works or modified versions, and any portions
  40  * thereof, and that both notices appear in supporting documentation.
  41  *
  42  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  43  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  44  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  45  *
  46  * Carnegie Mellon requests users of this software to return to
  47  *
  48  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  49  *  School of Computer Science
  50  *  Carnegie Mellon University
  51  *  Pittsburgh PA 15213-3890
  52  *
  53  * any improvements or extensions that they make and grant Carnegie Mellon
  54  * the rights to redistribute these changes.
  55  */
  56 /*
  57  */
  58 /*
  59  *      File:   vm/pmap.h
  60  *      Author: Avadis Tevanian, Jr.
  61  *      Date:   1985
  62  *
  63  *      Machine address mapping definitions -- machine-independent
  64  *      section.  [For machine-dependent section, see "machine/pmap.h".]
  65  */
  66
  67 #ifndef _VM_PMAP_H_
  68 #define _VM_PMAP_H_
  69
  70 #include <mach/kern_return.h>
  71 #include <mach/vm_param.h>
  72 #include <mach/vm_types.h>
  73 #include <mach/vm_attributes.h>
  74 #include <mach/boolean.h>
  75 #include <mach/vm_prot.h>
  76
  77 #ifdef  KERNEL_PRIVATE
  78
  79 /*
  80  *      The following is a description of the interface to the
  81  *      machine-dependent "physical map" data structure.  The module
  82  *      must provide a "pmap_t" data type that represents the
  83  *      set of valid virtual-to-physical addresses for one user
  84  *      address space.  [The kernel address space is represented
  85  *      by a distinguished "pmap_t".]  The routines described manage
  86  *      this type, install and update virtual-to-physical mappings,
  87  *      and perform operations on physical addresses common to
  88  *      many address spaces.
  89  */
  90
  91 /* Copy between a physical page and a virtual address */
  92 /* LP64todo - switch to vm_map_offset_t when it grows */
  93 extern kern_return_t    copypv(
  94                                 addr64_t source,
  95                                 addr64_t sink,
  96                                 unsigned int size,
  97                                 int which);
  98 #define cppvPsnk        1
  99 #define cppvPsnkb      31
 100 #define cppvPsrc        2
 101 #define cppvPsrcb      30
 102 #define cppvFsnk        4
 103 #define cppvFsnkb      29
 104 #define cppvFsrc        8
 105 #define cppvFsrcb      28
 106 #define cppvNoModSnk   16
 107 #define cppvNoModSnkb  27
 108 #define cppvNoRefSrc   32
 109 #define cppvNoRefSrcb  26
 110 #define cppvKmap       64       /* Use the kernel's vm_map */
 111 #define cppvKmapb      25
 112
 113 #ifdef  MACH_KERNEL_PRIVATE
 114
 115 #include <machine/pmap.h>
 116
 117 /*
 118  *      Routines used for initialization.
 119  *      There is traditionally also a pmap_bootstrap,
 120  *      used very early by machine-dependent code,
 121  *      but it is not part of the interface.
 122  *
 123  *      LP64todo -
 124  *      These interfaces are tied to the size of the
 125  *      kernel pmap - and therefore use the "local"
 126  *      vm_offset_t, etc... types.
 127  */
 128
 129 extern void             *pmap_steal_memory(vm_size_t size);
 130                                                 /* During VM initialization,
 131                                                  * steal a chunk of memory.
 132                                                  */
 133 extern unsigned int     pmap_free_pages(void);  /* During VM initialization,
 134                                                  * report remaining unused
 135                                                  * physical pages.
 136                                                  */
 137 extern void             pmap_startup(
 138                                 vm_offset_t *startp,
 139                                 vm_offset_t *endp);
 140                                                 /* During VM initialization,
 141                                                  * use remaining physical pages
 142                                                  * to allocate page frames.
 143                                                  */
 144 extern void             pmap_init(void) __attribute__((section("__TEXT, initcode")));
 145                                                 /* Initialization,
 146                                                  * after kernel runs
 147                                                  * in virtual memory.
 148                                                  */
 149
 150 extern void             mapping_adjust(void);   /* Adjust free mapping count */
 151
 152 extern void             mapping_free_prime(void); /* Primes the mapping block release list */
 153
 154 #ifndef MACHINE_PAGES
 155 /*
 156  *      If machine/pmap.h defines MACHINE_PAGES, it must implement
 157  *      the above functions.  The pmap module has complete control.
 158  *      Otherwise, it must implement
 159  *              pmap_free_pages
 160  *              pmap_virtual_space
 161  *              pmap_next_page
 162  *              pmap_init
 163  *      and vm/vm_resident.c implements pmap_steal_memory and pmap_startup
 164  *      using pmap_free_pages, pmap_next_page, pmap_virtual_space,
 165  *      and pmap_enter.  pmap_free_pages may over-estimate the number
 166  *      of unused physical pages, and pmap_next_page may return FALSE
 167  *      to indicate that there are no more unused pages to return.
 168  *      However, for best performance pmap_free_pages should be accurate.
 169  */
 170
 171 extern boolean_t        pmap_next_page(ppnum_t *pnum);
 172 extern boolean_t        pmap_next_page_hi(ppnum_t *pnum);
 173                                                 /* During VM initialization,
 174                                                  * return the next unused
 175                                                  * physical page.
 176                                                  */
 177 extern void             pmap_virtual_space(
 178                                         vm_offset_t     *virtual_start,
 179                                         vm_offset_t     *virtual_end);
 180                                                 /* During VM initialization,
 181                                                  * report virtual space
 182                                                  * available for the kernel.
 183                                                  */
 184 #endif  /* MACHINE_PAGES */
 185
 186 /*
 187  *      Routines to manage the physical map data structure.
 188  */
 189 extern pmap_t           pmap_create(    /* Create a pmap_t. */
 190                                 vm_map_size_t   size,
 191 #ifdef __i386__
 192                                 boolean_t       is_64bit);
 193 #else
 194                                 __unused boolean_t      is_64bit);
 195 #endif
 196 extern pmap_t           (pmap_kernel)(void);    /* Return the kernel's pmap */
 197 extern void             pmap_reference(pmap_t pmap);    /* Gain a reference. */
 198 extern void             pmap_destroy(pmap_t pmap); /* Release a reference. */
 199 extern void             pmap_switch(pmap_t);
 200
 201
 202 extern void             pmap_enter(     /* Enter a mapping */
 203                                 pmap_t          pmap,
 204                                 vm_map_offset_t v,
 205                                 ppnum_t         pn,
 206                                 vm_prot_t       prot,
 207                                 unsigned int    flags,
 208                                 boolean_t       wired);
 209
 210 extern kern_return_t    pmap_enter_options(
 211                                            pmap_t pmap,
 212                                            vm_map_offset_t v,
 213                                            ppnum_t pn,
 214                                            vm_prot_t prot,
 215                                            unsigned int flags,
 216                                            boolean_t wired,
 217                                            unsigned int options);
 218
 219 extern void             pmap_remove_some_phys(
 220                                 pmap_t          pmap,
 221                                 ppnum_t         pn);
 222
 223
 224 /*
 225  *      Routines that operate on physical addresses.
 226  */
 227
 228 extern void             pmap_page_protect(      /* Restrict access to page. */
 229                                 ppnum_t phys,
 230                                 vm_prot_t       prot);
 231
 232 extern void             (pmap_zero_page)(
 233                                 ppnum_t         pn);
 234
 235 extern void             (pmap_zero_part_page)(
 236                                 ppnum_t         pn,
 237                                 vm_offset_t     offset,
 238                                 vm_size_t       len);
 239
 240 extern void             (pmap_copy_page)(
 241                                 ppnum_t         src,
 242                                 ppnum_t         dest);
 243
 244 extern void             (pmap_copy_part_page)(
 245                                 ppnum_t         src,
 246                                 vm_offset_t     src_offset,
 247                                 ppnum_t         dst,
 248                                 vm_offset_t     dst_offset,
 249                                 vm_size_t       len);
 250
 251 extern void             (pmap_copy_part_lpage)(
 252                                 vm_offset_t     src,
 253                                 ppnum_t         dst,
 254                                 vm_offset_t     dst_offset,
 255                                 vm_size_t       len);
 256
 257 extern void             (pmap_copy_part_rpage)(
 258                                 ppnum_t         src,
 259                                 vm_offset_t     src_offset,
 260                                 vm_offset_t     dst,
 261                                 vm_size_t       len);
 262
 263 extern unsigned int (pmap_disconnect)(  /* disconnect mappings and return reference and change */
 264                                 ppnum_t         phys);
 265
 266 extern kern_return_t    (pmap_attribute_cache_sync)(  /* Flush appropriate
 267                                                        * cache based on
 268                                                        * page number sent */
 269                                 ppnum_t         pn,
 270                                 vm_size_t       size,
 271                                 vm_machine_attribute_t attribute,
 272                                 vm_machine_attribute_val_t* value);
 273
 274 extern unsigned int     (pmap_cache_attributes)(
 275                                 ppnum_t         pn);
 276
 277 /*
 278  * Set (override) cache attributes for the specified physical page
 279  */
 280 extern  void            pmap_set_cache_attributes(
 281                                 ppnum_t,
 282                                 unsigned int);
 283 extern void pmap_sync_page_data_phys(ppnum_t pa);
 284 extern void pmap_sync_page_attributes_phys(ppnum_t pa);
 285
 286 /*
 287  * debug/assertions. pmap_verify_free returns true iff
 288  * the given physical page is mapped into no pmap.
 289  */
 290 extern boolean_t        pmap_verify_free(ppnum_t pn);
 291
 292 /*
 293  *      Statistics routines
 294  */
 295 extern int              (pmap_resident_count)(pmap_t pmap);
 296 extern int              (pmap_resident_max)(pmap_t pmap);
 297
 298 /*
 299  *      Sundry required (internal) routines
 300  */
 301 #ifdef CURRENTLY_UNUSED_AND_UNTESTED
 302 extern void             pmap_collect(pmap_t pmap);/* Perform garbage
 303                                                  * collection, if any */
 304 #endif
 305 /*
 306  *      Optional routines
 307  */
 308 extern void             (pmap_copy)(            /* Copy range of mappings,
 309                                                  * if desired. */
 310                                 pmap_t          dest,
 311                                 pmap_t          source,
 312                                 vm_map_offset_t dest_va,
 313                                 vm_map_size_t   size,
 314                                 vm_map_offset_t source_va);
 315
 316 extern kern_return_t    (pmap_attribute)(       /* Get/Set special memory
 317                                                  * attributes */
 318                                 pmap_t          pmap,
 319                                 vm_map_offset_t va,
 320                                 vm_map_size_t   size,
 321                                 vm_machine_attribute_t  attribute,
 322                                 vm_machine_attribute_val_t* value);
 323
 324 /*
 325  * Routines defined as macros.
 326  */
 327 #ifndef PMAP_ACTIVATE_USER
 328 #ifndef PMAP_ACTIVATE
 329 #define PMAP_ACTIVATE_USER(thr, cpu)
 330 #else   /* PMAP_ACTIVATE */
 331 #define PMAP_ACTIVATE_USER(thr, cpu) {                  \
 332         pmap_t  pmap;                                           \
 333                                                                 \
 334         pmap = (thr)->map->pmap;                                \
 335         if (pmap != pmap_kernel())                              \
 336                 PMAP_ACTIVATE(pmap, (thr), (cpu));              \
 337 }
 338 #endif  /* PMAP_ACTIVATE */
 339 #endif  /* PMAP_ACTIVATE_USER */
 340
 341 #ifndef PMAP_DEACTIVATE_USER
 342 #ifndef PMAP_DEACTIVATE
 343 #define PMAP_DEACTIVATE_USER(thr, cpu)
 344 #else   /* PMAP_DEACTIVATE */
 345 #define PMAP_DEACTIVATE_USER(thr, cpu) {                        \
 346         pmap_t  pmap;                                           \
 347                                                                 \
 348         pmap = (thr)->map->pmap;                                \
 349         if ((pmap) != pmap_kernel())                    \
 350                 PMAP_DEACTIVATE(pmap, (thr), (cpu));    \
 351 }
 352 #endif  /* PMAP_DEACTIVATE */
 353 #endif  /* PMAP_DEACTIVATE_USER */
 354
 355 #ifndef PMAP_ACTIVATE_KERNEL
 356 #ifndef PMAP_ACTIVATE
 357 #define PMAP_ACTIVATE_KERNEL(cpu)
 358 #else   /* PMAP_ACTIVATE */
 359 #define PMAP_ACTIVATE_KERNEL(cpu)                       \
 360                 PMAP_ACTIVATE(pmap_kernel(), THREAD_NULL, cpu)
 361 #endif  /* PMAP_ACTIVATE */
 362 #endif  /* PMAP_ACTIVATE_KERNEL */
 363
 364 #ifndef PMAP_DEACTIVATE_KERNEL
 365 #ifndef PMAP_DEACTIVATE
 366 #define PMAP_DEACTIVATE_KERNEL(cpu)
 367 #else   /* PMAP_DEACTIVATE */
 368 #define PMAP_DEACTIVATE_KERNEL(cpu)                     \
 369                 PMAP_DEACTIVATE(pmap_kernel(), THREAD_NULL, cpu)
 370 #endif  /* PMAP_DEACTIVATE */
 371 #endif  /* PMAP_DEACTIVATE_KERNEL */
 372
 373 #ifndef PMAP_ENTER
 374 /*
 375  *      Macro to be used in place of pmap_enter()
 376  */
 377 #define PMAP_ENTER(pmap, virtual_address, page, protection, flags, wired) \
 378         MACRO_BEGIN                                                     \
 379         pmap_t          __pmap = (pmap);                                \
 380         vm_page_t       __page = (page);                                \
 381                                                                         \
 382         PMAP_ENTER_CHECK(__pmap, __page)                                \
 383         pmap_enter(__pmap,                                      \
 384                 (virtual_address),                                      \
 385                 __page->phys_page,                                      \
 386                         (protection),                                   \
 387                 (flags),                                                \
 388                 (wired));                                               \
 389         MACRO_END
 390 #endif  /* !PMAP_ENTER */
 391
 392 #ifndef PMAP_ENTER_OPTIONS
 393 #define PMAP_ENTER_OPTIONS(pmap, virtual_address, page, protection,     \
 394                                 flags, wired, options, result) \
 395         MACRO_BEGIN                                                     \
 396         pmap_t          __pmap = (pmap);                                \
 397         vm_page_t       __page = (page);                                \
 398                                                                         \
 399         PMAP_ENTER_CHECK(__pmap, __page)                                \
 400         result = pmap_enter_options(__pmap,                             \
 401                 (virtual_address),                                      \
 402                 __page->phys_page,                                      \
 403                         (protection),                                   \
 404                 (flags),                                                \
 405                 (wired),                                                \
 406                 options);                                       \
 407         MACRO_END
 408 #endif  /* !PMAP_ENTER_OPTIONS */
 409
 410 #define PMAP_ENTER_CHECK(pmap, page)                                    \
 411 {                                                                       \
 412         if ((pmap) != kernel_pmap) {                                    \
 413                 ASSERT_PAGE_DECRYPTED(page);                            \
 414         }                                                               \
 415         if ((page)->error) {                                            \
 416                 panic("VM page %p should not have an error\n",          \
 417                         (page));                                        \
 418         }                                                               \
 419 }
 420
 421 /*
 422  *      Routines to manage reference/modify bits based on
 423  *      physical addresses, simulating them if not provided
 424  *      by the hardware.
 425  */
 426                                 /* Clear reference bit */
 427 extern void             pmap_clear_reference(ppnum_t     pn);
 428                                 /* Return reference bit */
 429 extern boolean_t        (pmap_is_referenced)(ppnum_t     pn);
 430                                 /* Set modify bit */
 431 extern void             pmap_set_modify(ppnum_t  pn);
 432                                 /* Clear modify bit */
 433 extern void             pmap_clear_modify(ppnum_t pn);
 434                                 /* Return modify bit */
 435 extern boolean_t        pmap_is_modified(ppnum_t pn);
 436                                 /* Return modified and referenced bits */
 437 extern unsigned int pmap_get_refmod(ppnum_t pn);
 438                                 /* Clear modified and referenced bits */
 439 extern void                     pmap_clear_refmod(ppnum_t pn, unsigned int mask);
 440 #define VM_MEM_MODIFIED         0x01    /* Modified bit */
 441 #define VM_MEM_REFERENCED       0x02    /* Referenced bit */
 442
 443 /*
 444  *      Routines that operate on ranges of virtual addresses.
 445  */
 446 extern void             pmap_protect(   /* Change protections. */
 447                                 pmap_t          map,
 448                                 vm_map_offset_t s,
 449                                 vm_map_offset_t e,
 450                                 vm_prot_t       prot);
 451
 452 extern void             (pmap_pageable)(
 453                                 pmap_t          pmap,
 454                                 vm_map_offset_t start,
 455                                 vm_map_offset_t end,
 456                                 boolean_t       pageable);
 457
 458
 459 extern uint64_t pmap_nesting_size_min;
 460 extern uint64_t pmap_nesting_size_max;
 461
 462 extern kern_return_t pmap_nest(pmap_t,
 463                                pmap_t,
 464                                addr64_t,
 465                                addr64_t,
 466                                uint64_t);
 467 extern kern_return_t pmap_unnest(pmap_t,
 468                                  addr64_t,
 469                                  uint64_t);
 470 extern boolean_t pmap_adjust_unnest_parameters(pmap_t, vm_map_offset_t *, vm_map_offset_t *);
 471 #endif  /* MACH_KERNEL_PRIVATE */
 472
 473 extern boolean_t        pmap_is_noencrypt(ppnum_t);
 474 extern void             pmap_set_noencrypt(ppnum_t pn);
 475 extern void             pmap_clear_noencrypt(ppnum_t pn);
 476
 477 /*
 478  * JMM - This portion is exported to other kernel components right now,
 479  * but will be pulled back in the future when the needed functionality
 480  * is provided in a cleaner manner.
 481  */
 482
 483 extern pmap_t   kernel_pmap;                    /* The kernel's map */
 484 #define         pmap_kernel()   (kernel_pmap)
 485
 486 /* machine independent WIMG bits */
 487
 488 #define VM_MEM_GUARDED          0x1             /* (G) Guarded Storage */
 489 #define VM_MEM_COHERENT         0x2             /* (M) Memory Coherency */
 490 #define VM_MEM_NOT_CACHEABLE    0x4             /* (I) Cache Inhibit */
 491 #define VM_MEM_WRITE_THROUGH    0x8             /* (W) Write-Through */
 492
 493 #define VM_WIMG_USE_DEFAULT     0x80
 494 #define VM_WIMG_MASK            0xFF
 495
 496 #define VM_MEM_SUPERPAGE        0x100           /* map a superpage instead of a base page */
 497
 498 #define PMAP_OPTIONS_NOWAIT     0x1             /* don't block, return
 499                                                  * KERN_RESOURCE_SHORTAGE
 500                                                  * instead */
 501
 502 #if     !defined(__LP64__)
 503 extern vm_offset_t      pmap_extract(pmap_t pmap,
 504                                 vm_map_offset_t va);
 505 #endif
 506 extern void             pmap_change_wiring(     /* Specify pageability */
 507                                 pmap_t          pmap,
 508                                 vm_map_offset_t va,
 509                                 boolean_t       wired);
 510
 511 /* LP64todo - switch to vm_map_offset_t when it grows */
 512 extern void             pmap_remove(    /* Remove mappings. */
 513                                 pmap_t          map,
 514                                 vm_map_offset_t s,
 515                                 vm_map_offset_t e);
 516
 517 extern void             fillPage(ppnum_t pa, unsigned int fill);
 518
 519 extern void pmap_map_sharedpage(task_t task, pmap_t pmap);
 520 extern void pmap_unmap_sharedpage(pmap_t pmap);
 521
 522 #if defined(__LP64__)
 523 void pmap_pre_expand(pmap_t pmap, vm_map_offset_t vaddr);
 524 #endif
 525
 526 #endif  /* KERNEL_PRIVATE */
 527
 528 #endif  /* _VM_PMAP_H_ */