osfmk/vm/vm_object.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * @OSF_COPYRIGHT@
  24  */
  25 /*
  26  * Mach Operating System
  27  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  28  * All Rights Reserved.
  29  *
  30  * Permission to use, copy, modify and distribute this software and its
  31  * documentation is hereby granted, provided that both the copyright
  32  * notice and this permission notice appear in all copies of the
  33  * software, derivative works or modified versions, and any portions
  34  * thereof, and that both notices appear in supporting documentation.
  35  *
  36  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  37  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  38  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  39  *
  40  * Carnegie Mellon requests users of this software to return to
  41  *
  42  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  43  *  School of Computer Science
  44  *  Carnegie Mellon University
  45  *  Pittsburgh PA 15213-3890
  46  *
  47  * any improvements or extensions that they make and grant Carnegie Mellon
  48  * the rights to redistribute these changes.
  49  */
  50 /*
  51  */
  52 /*
  53  *      File:   vm_object.h
  54  *      Author: Avadis Tevanian, Jr., Michael Wayne Young
  55  *      Date:   1985
  56  *
  57  *      Virtual memory object module definitions.
  58  */
  59
  60 #ifndef _VM_VM_OBJECT_H_
  61 #define _VM_VM_OBJECT_H_
  62
  63 #include <mach_pagemap.h>
  64 #include <task_swapper.h>
  65
  66 #include <mach/kern_return.h>
  67 #include <mach/boolean.h>
  68 #include <mach/memory_object_types.h>
  69 #include <mach/port.h>
  70 #include <mach/vm_prot.h>
  71 #include <mach/machine/vm_types.h>
  72 #include <kern/queue.h>
  73 #include <kern/lock.h>
  74 #include <kern/assert.h>
  75 #include <kern/macro_help.h>
  76 #include <ipc/ipc_types.h>
  77 #include <vm/pmap.h>
  78 #include <kern/misc_protos.h>
  79
  80 #if     MACH_PAGEMAP
  81 #include <vm/vm_external.h>
  82 #endif  /* MACH_PAGEMAP */
  83
  84 typedef struct ipc_port *       pager_request_t;
  85 #define PAGER_REQUEST_NULL      ((pager_request_t) 0)
  86
  87 /*
  88  *      Types defined:
  89  *
  90  *      vm_object_t             Virtual memory object.
  91  *
  92  *      We use "struct ipc_port *" instead of "ipc_port_t"
  93  *      to avoid include file circularities.
  94  */
  95
  96 typedef unsigned long long vm_object_size_t;
  97
  98
  99 struct vm_object {
 100         queue_head_t            memq;           /* Resident memory */
 101         decl_mutex_data(,       Lock)           /* Synchronization */
 102
 103         vm_object_size_t        size;           /* Object size (only valid
 104                                                  * if internal)
 105                                                  */
 106         vm_object_size_t        frozen_size;    /* How much has been marked
 107                                                  * copy-on-write (only
 108                                                  * valid if copy_symmetric)
 109                                                  */
 110         int                     ref_count;      /* Number of references */
 111 #if     TASK_SWAPPER
 112         int                     res_count;      /* Residency references (swap)*/
 113 #endif  /* TASK_SWAPPER */
 114         unsigned int            resident_page_count;
 115                                                 /* number of resident pages */
 116
 117         struct vm_object        *copy;          /* Object that should receive
 118                                                  * a copy of my changed pages,
 119                                                  * for copy_delay, or just the
 120                                                  * temporary object that
 121                                                  * shadows this object, for
 122                                                  * copy_call.
 123                                                  */
 124         struct vm_object        *shadow;        /* My shadow */
 125         vm_object_offset_t      shadow_offset;  /* Offset into shadow */
 126
 127         struct ipc_port         *pager;         /* Where to get data */
 128         vm_object_offset_t      paging_offset;  /* Offset into memory object */
 129         pager_request_t         pager_request;  /* Where data comes back */
 130
 131         memory_object_copy_strategy_t
 132                                 copy_strategy;  /* How to handle data copy */
 133
 134         unsigned int            absent_count;   /* The number of pages that
 135                                                  * have been requested but
 136                                                  * not filled.  That is, the
 137                                                  * number of pages for which
 138                                                  * the "absent" attribute is
 139                                                  * asserted.
 140                                                  */
 141
 142         unsigned int            paging_in_progress;
 143                                                 /* The memory object ports are
 144                                                  * being used (e.g., for pagein
 145                                                  * or pageout) -- don't change
 146                                                  * any of these fields (i.e.,
 147                                                  * don't collapse, destroy or
 148                                                  * terminate)
 149                                                  */
 150         unsigned int
 151         /* boolean_t array */   all_wanted:11,  /* Bit array of "want to be
 152                                                  * awakened" notations.  See
 153                                                  * VM_OBJECT_EVENT_* items
 154                                                  * below */
 155         /* boolean_t */ pager_created:1,        /* Has pager been created? */
 156         /* boolean_t */ pager_initialized:1,    /* Are fields ready to use? */
 157         /* boolean_t */ pager_ready:1,          /* Will pager take requests? */
 158
 159         /* boolean_t */         pager_trusted:1,/* The pager for this object
 160                                                  * is trusted. This is true for
 161                                                  * all internal objects (backed
 162                                                  * by the default pager)
 163                                                  */
 164         /* boolean_t */         can_persist:1,  /* The kernel may keep the data
 165                                                  * for this object (and rights
 166                                                  * to the memory object) after
 167                                                  * all address map references
 168                                                  * are deallocated?
 169                                                  */
 170         /* boolean_t */         internal:1,     /* Created by the kernel (and
 171                                                  * therefore, managed by the
 172                                                  * default memory manger)
 173                                                  */
 174         /* boolean_t */         temporary:1,    /* Permanent objects may be
 175                                                  * changed externally by the
 176                                                  * memory manager, and changes
 177                                                  * made in memory must be
 178                                                  * reflected back to the memory
 179                                                  * manager.  Temporary objects
 180                                                  * lack both of these
 181                                                  * characteristics.
 182                                                  */
 183         /* boolean_t */         private:1,      /* magic device_pager object,
 184                                                  * holds private pages only */
 185         /* boolean_t */         pageout:1,      /* pageout object. contains
 186                                                  * private pages that refer to
 187                                                  * a real memory object. */
 188         /* boolean_t */         alive:1,        /* Not yet terminated */
 189
 190         /* boolean_t */         lock_in_progress:1,
 191                                                 /* Is a multi-page lock
 192                                                  * request in progress?
 193                                                  */
 194         /* boolean_t */         lock_restart:1,
 195                                                 /* Should lock request in
 196                                                  * progress restart search?
 197                                                  */
 198         /* boolean_t */         shadowed:1,     /* Shadow may exist */
 199         /* boolean_t */         silent_overwrite:1,
 200                                                 /* Allow full page overwrite
 201                                                  * without data_request if
 202                                                  * page is absent */
 203         /* boolean_t */         advisory_pageout:1,
 204                                                 /* Instead of sending page
 205                                                  * via OOL, just notify
 206                                                  * pager that the kernel
 207                                                  * wants to discard it, page
 208                                                  * remains in object */
 209         /* boolean_t */         true_share:1,
 210                                                 /* This object is mapped
 211                                                  * in more than one place
 212                                                  * and hence cannot be
 213                                                  * coalesced */
 214         /* boolean_t */         terminating:1,
 215                                                 /* Allows vm_object_lookup
 216                                                  * and vm_object_deallocate
 217                                                  * to special case their
 218                                                  * behavior when they are
 219                                                  * called as a result of
 220                                                  * page cleaning during
 221                                                  * object termination
 222                                                  */
 223         /* boolean_t */         named:1,        /* An enforces an internal
 224                                                  * naming convention, by
 225                                                  * calling the right routines
 226                                                  * for allocation and
 227                                                  * destruction, UBC references
 228                                                  * against the vm_object are
 229                                                  * checked.
 230                                                  */
 231         /* boolean_t */         shadow_severed:1,
 232                                                 /* When a permanent object
 233                                                  * backing a COW goes away
 234                                                  * unexpectedly.  This bit
 235                                                  * allows vm_fault to return
 236                                                  * an error rather than a
 237                                                  * zero filled page.
 238                                                  */
 239         /* boolean_t */         phys_contiguous:1;
 240                                                 /* Memory is wired and
 241                                                  * guaranteed physically
 242                                                  * contiguous.  However
 243                                                  * it is not device memory
 244                                                  * and obeys normal virtual
 245                                                  * memory rules w.r.t pmap
 246                                                  * access bits.
 247                                                  */
 248
 249
 250
 251         queue_chain_t           cached_list;    /* Attachment point for the
 252                                                  * list of objects cached as a
 253                                                  * result of their can_persist
 254                                                  * value
 255                                                  */
 256
 257         queue_head_t            msr_q;          /* memory object synchronise
 258                                                    request queue */
 259
 260         vm_object_offset_t      last_alloc;     /* last allocation offset */
 261         vm_size_t               cluster_size;   /* size of paging cluster */
 262 #if     MACH_PAGEMAP
 263         vm_external_map_t       existence_map;  /* bitmap of pages written to
 264                                                  * backing storage */
 265 #endif  /* MACH_PAGEMAP */
 266 #if     MACH_ASSERT
 267         struct vm_object        *paging_object; /* object which pages to be
 268                                                  * swapped out are temporary
 269                                                  * put in current object
 270                                                  */
 271 #endif
 272 #ifdef  UBC_DEBUG
 273         queue_head_t            uplq;           /* List of outstanding upls */
 274 #endif /* UBC_DEBUG */
 275 };
 276
 277 extern
 278 vm_object_t     kernel_object;          /* the single kernel object */
 279
 280 int             vm_object_absent_max;   /* maximum number of absent pages
 281                                            at a time for each object */
 282
 283 # define        VM_MSYNC_INITIALIZED                    0
 284 # define        VM_MSYNC_SYNCHRONIZING                  1
 285 # define        VM_MSYNC_DONE                           2
 286
 287 struct msync_req {
 288         queue_chain_t           msr_q;          /* object request queue */
 289         queue_chain_t           req_q;          /* vm_msync request queue */
 290         unsigned int            flag;
 291         vm_object_offset_t      offset;
 292         vm_object_size_t        length;
 293         vm_object_t             object;         /* back pointer */
 294         decl_mutex_data(,       msync_req_lock) /* Lock for this structure */
 295 };
 296
 297 typedef struct msync_req        *msync_req_t;
 298 #define MSYNC_REQ_NULL          ((msync_req_t) 0)
 299
 300 /*
 301  * Macros to allocate and free msync_reqs
 302  */
 303 #define msync_req_alloc(msr)                                            \
 304         MACRO_BEGIN                                                     \
 305         (msr) = (msync_req_t)kalloc(sizeof(struct msync_req));          \
 306         mutex_init(&(msr)->msync_req_lock, ETAP_VM_MSYNC);              \
 307         msr->flag = VM_MSYNC_INITIALIZED;                               \
 308         MACRO_END
 309
 310 #define msync_req_free(msr)                                             \
 311         (kfree((vm_offset_t)(msr), sizeof(struct msync_req)))
 312
 313 #define msr_lock(msr)   mutex_lock(&(msr)->msync_req_lock)
 314 #define msr_unlock(msr) mutex_unlock(&(msr)->msync_req_lock)
 315
 316 /*
 317  *      Declare procedures that operate on VM objects.
 318  */
 319
 320 extern void             vm_object_bootstrap(void);
 321
 322 extern void             vm_object_init(void);
 323
 324 extern vm_object_t      vm_object_allocate(
 325                                         vm_object_size_t        size);
 326
 327 #if     MACH_ASSERT
 328 extern void             vm_object_reference(
 329                                         vm_object_t     object);
 330 #else   /* MACH_ASSERT */
 331 #define vm_object_reference(object)                     \
 332 MACRO_BEGIN                                             \
 333         vm_object_t Object = (object);                  \
 334         if (Object) {                                   \
 335                 vm_object_lock(Object);                 \
 336                 Object->ref_count++;                    \
 337                 vm_object_res_reference(Object);        \
 338                 vm_object_unlock(Object);               \
 339         }                                               \
 340 MACRO_END
 341 #endif  /* MACH_ASSERT */
 342
 343 extern void             vm_object_deallocate(
 344                                         vm_object_t     object);
 345
 346 extern void             vm_object_pmap_protect(
 347                                         vm_object_t             object,
 348                                         vm_object_offset_t      offset,
 349                                         vm_size_t               size,
 350                                         pmap_t                  pmap,
 351                                         vm_offset_t             pmap_start,
 352                                         vm_prot_t               prot);
 353
 354 extern void             vm_object_page_remove(
 355                                         vm_object_t             object,
 356                                         vm_object_offset_t      start,
 357                                         vm_object_offset_t      end);
 358
 359 extern boolean_t        vm_object_coalesce(
 360                                         vm_object_t             prev_object,
 361                                         vm_object_t             next_object,
 362                                         vm_object_offset_t      prev_offset,
 363                                         vm_object_offset_t      next_offset,
 364                                         vm_object_size_t        prev_size,
 365                                         vm_object_size_t        next_size);
 366
 367 extern boolean_t        vm_object_shadow(
 368                                         vm_object_t             *object,
 369                                         vm_object_offset_t      *offset,
 370                                         vm_object_size_t        length);
 371
 372 extern void             vm_object_collapse(
 373                                         vm_object_t     object);
 374
 375 extern vm_object_t      vm_object_lookup(
 376                                         ipc_port_t      port);
 377
 378 extern ipc_port_t       vm_object_name(
 379                                         vm_object_t     object);
 380
 381 extern boolean_t        vm_object_copy_quickly(
 382                                 vm_object_t             *_object,
 383                                 vm_object_offset_t      src_offset,
 384                                 vm_object_size_t        size,
 385                                 boolean_t               *_src_needs_copy,
 386                                 boolean_t               *_dst_needs_copy);
 387
 388 extern kern_return_t    vm_object_copy_strategically(
 389                                 vm_object_t             src_object,
 390                                 vm_object_offset_t      src_offset,
 391                                 vm_object_size_t        size,
 392                                 vm_object_t             *dst_object,
 393                                 vm_object_offset_t      *dst_offset,
 394                                 boolean_t               *dst_needs_copy);
 395
 396 extern kern_return_t    vm_object_copy_slowly(
 397                                 vm_object_t             src_object,
 398                                 vm_object_offset_t      src_offset,
 399                                 vm_object_size_t        size,
 400                                 int                     interruptible,
 401                                 vm_object_t             *_result_object);
 402
 403 extern void             vm_object_pager_create(
 404                                         vm_object_t     object);
 405
 406 extern void             vm_object_destroy(
 407                                         ipc_port_t      pager);
 408
 409 extern void             vm_object_pager_wakeup(
 410                                         ipc_port_t      pager);
 411
 412 extern void             vm_object_page_map(
 413                                 vm_object_t     object,
 414                                 vm_object_offset_t      offset,
 415                                 vm_object_size_t        size,
 416                                 vm_object_offset_t      (*map_fn)
 417                                         (void *, vm_object_offset_t),
 418                                         void            *map_fn_data);
 419
 420 #if     TASK_SWAPPER
 421
 422 extern void             vm_object_res_reference(
 423                                         vm_object_t object);
 424 extern void             vm_object_res_deallocate(
 425                                         vm_object_t object);
 426 #define VM_OBJ_RES_INCR(object) (object)->res_count++
 427 #define VM_OBJ_RES_DECR(object) (object)->res_count--
 428
 429 #else   /* TASK_SWAPPER */
 430
 431 #define VM_OBJ_RES_INCR(object)
 432 #define VM_OBJ_RES_DECR(object)
 433 #define vm_object_res_reference(object)
 434 #define vm_object_res_deallocate(object)
 435
 436 #endif  /* TASK_SWAPPER */
 437
 438 extern vm_object_t      vm_object_enter(
 439                                         ipc_port_t              pager,
 440                                         vm_object_size_t        size,
 441                                         boolean_t               internal,
 442                                         boolean_t               init,
 443                                         boolean_t               check_named);
 444
 445
 446 extern vm_object_t      vm_object_copy_delayed(
 447                                 vm_object_t             src_object,
 448                                 vm_object_offset_t      src_offset,
 449                                 vm_object_size_t        size);
 450
 451
 452 /*
 453  *      Event waiting handling
 454  */
 455
 456 #define VM_OBJECT_EVENT_INITIALIZED             0
 457 #define VM_OBJECT_EVENT_PAGER_READY             1
 458 #define VM_OBJECT_EVENT_PAGING_IN_PROGRESS      2
 459 #define VM_OBJECT_EVENT_ABSENT_COUNT            3
 460 #define VM_OBJECT_EVENT_LOCK_IN_PROGRESS        4
 461 #define VM_OBJECT_EVENT_UNCACHING               5
 462 #define VM_OBJECT_EVENT_COPY_CALL               6
 463 #define VM_OBJECT_EVENT_CACHING                 7
 464
 465 #define vm_object_assert_wait(object, event, interruptible)             \
 466         MACRO_BEGIN                                                     \
 467         (object)->all_wanted |= 1 << (event);                           \
 468         assert_wait((event_t)((vm_offset_t)(object)+(event)),(interruptible)); \
 469         MACRO_END
 470
 471 #define vm_object_wait(object, event, interruptible)                    \
 472         MACRO_BEGIN                                                     \
 473         vm_object_assert_wait((object),(event),(interruptible));        \
 474         vm_object_unlock(object);                                       \
 475         thread_block((void (*)(void)) 0);                               \
 476         MACRO_END
 477
 478 #define vm_object_wakeup(object, event)                                 \
 479         MACRO_BEGIN                                                     \
 480         if ((object)->all_wanted & (1 << (event)))                      \
 481                 thread_wakeup((event_t)((vm_offset_t)(object) + (event))); \
 482         (object)->all_wanted &= ~(1 << (event));                        \
 483         MACRO_END
 484
 485 #define vm_object_set_wanted(object, event)                             \
 486         MACRO_BEGIN                                                     \
 487         ((object)->all_wanted |= (1 << (event)));                       \
 488         MACRO_END
 489
 490 #define vm_object_wanted(object, event)                                 \
 491         ((object)->all_wanted & (1 << (event)))
 492
 493 /*
 494  *      Routines implemented as macros
 495  */
 496
 497 #define         vm_object_paging_begin(object)                          \
 498         MACRO_BEGIN                                                     \
 499         (object)->paging_in_progress++;                                 \
 500         MACRO_END
 501
 502 #define         vm_object_paging_end(object)                            \
 503         MACRO_BEGIN                                                     \
 504         assert((object)->paging_in_progress != 0);                      \
 505         if (--(object)->paging_in_progress == 0) {                      \
 506                 vm_object_wakeup(object,                                \
 507                         VM_OBJECT_EVENT_PAGING_IN_PROGRESS);            \
 508         }                                                               \
 509         MACRO_END
 510
 511 #define         vm_object_paging_wait(object, interruptible)            \
 512         MACRO_BEGIN                                                     \
 513         while ((object)->paging_in_progress != 0) {                     \
 514                 vm_object_wait( (object),                               \
 515                                 VM_OBJECT_EVENT_PAGING_IN_PROGRESS,     \
 516                                 (interruptible));                       \
 517                 vm_object_lock(object);                                 \
 518                                                                         \
 519                 /*XXX if ((interruptible) &&    */                      \
 520                     /*XXX (current_thread()->wait_result != THREAD_AWAKENED))*/ \
 521                         /*XXX break; */                                 \
 522         }                                                               \
 523         MACRO_END
 524
 525 #define vm_object_absent_assert_wait(object, interruptible)             \
 526         MACRO_BEGIN                                                     \
 527         vm_object_assert_wait(  (object),                               \
 528                         VM_OBJECT_EVENT_ABSENT_COUNT,                   \
 529                         (interruptible));                               \
 530         MACRO_END
 531
 532
 533 #define vm_object_absent_release(object)                                \
 534         MACRO_BEGIN                                                     \
 535         (object)->absent_count--;                                       \
 536         vm_object_wakeup((object),                                      \
 537                          VM_OBJECT_EVENT_ABSENT_COUNT);                 \
 538         MACRO_END
 539
 540 /*
 541  *      Object locking macros
 542  */
 543
 544 #define vm_object_lock_init(object)     mutex_init(&(object)->Lock, ETAP_VM_OBJ)
 545 #define vm_object_lock(object)          mutex_lock(&(object)->Lock)
 546 #define vm_object_unlock(object)        mutex_unlock(&(object)->Lock)
 547 #define vm_object_lock_try(object)      mutex_try(&(object)->Lock)
 548
 549 #endif  /* _VM_VM_OBJECT_H_ */