osfmk/mach/memory_object_types.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26  * @OSF_COPYRIGHT@
  27  */
  28 /*
  29  * Mach Operating System
  30  * Copyright (c) 1991,1990,1989,1988 Carnegie Mellon University
  31  * All Rights Reserved.
  32  *
  33  * Permission to use, copy, modify and distribute this software and its
  34  * documentation is hereby granted, provided that both the copyright
  35  * notice and this permission notice appear in all copies of the
  36  * software, derivative works or modified versions, and any portions
  37  * thereof, and that both notices appear in supporting documentation.
  38  *
  39  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  40  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  41  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  42  *
  43  * Carnegie Mellon requests users of this software to return to
  44  *
  45  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  46  *  School of Computer Science
  47  *  Carnegie Mellon University
  48  *  Pittsburgh PA 15213-3890
  49  *
  50  * any improvements or extensions that they make and grant Carnegie Mellon
  51  * the rights to redistribute these changes.
  52  */
  53 /*
  54  */
  55 /*
  56  *      File:   memory_object.h
  57  *      Author: Michael Wayne Young
  58  *
  59  *      External memory management interface definition.
  60  */
  61
  62 #ifndef _MACH_MEMORY_OBJECT_TYPES_H_
  63 #define _MACH_MEMORY_OBJECT_TYPES_H_
  64
  65 /*
  66  *      User-visible types used in the external memory
  67  *      management interface:
  68  */
  69
  70 #include <mach/port.h>
  71 #include <mach/vm_types.h>
  72 #include <mach/machine/vm_types.h>
  73
  74 #include <sys/appleapiopts.h>
  75
  76 #define VM_64_BIT_DATA_OBJECTS
  77
  78 typedef unsigned long long      memory_object_offset_t;
  79 typedef unsigned long long      memory_object_size_t;
  80
  81 #ifdef __APPLE_API_EVOLVING
  82 /*
  83  * Temporary until real EMMI version gets re-implemented
  84  */
  85 #ifdef KERNEL_PRIVATE
  86 typedef struct          memory_object {
  87         int             *pager;
  88 } *memory_object_t;
  89
  90 typedef struct          memory_object_control {
  91         struct vm_object *object;
  92 } *memory_object_control_t;
  93
  94 #else /* !KERNEL_PRIVATE */
  95
  96 typedef mach_port_t     memory_object_t;
  97 typedef mach_port_t     memory_object_control_t;
  98
  99 #endif /* !KERNEL_PRIVATE */
 100
 101 typedef memory_object_t *memory_object_array_t;
 102                                         /* A memory object ... */
 103                                         /*  Used by the kernel to retrieve */
 104                                         /*  or store data */
 105
 106 typedef mach_port_t     memory_object_name_t;
 107                                         /* Used to describe the memory ... */
 108                                         /*  object in vm_regions() calls */
 109
 110 typedef mach_port_t     memory_object_default_t;
 111                                         /* Registered with the host ... */
 112                                         /*  for creating new internal objects */
 113
 114 #define MEMORY_OBJECT_NULL              ((memory_object_t) 0)
 115 #define MEMORY_OBJECT_CONTROL_NULL      ((memory_object_control_t) 0)
 116 #define MEMORY_OBJECT_NAME_NULL         ((memory_object_name_t) 0)
 117 #define MEMORY_OBJECT_DEFAULT_NULL      ((memory_object_default_t) 0)
 118
 119
 120 typedef int             memory_object_copy_strategy_t;
 121                                         /* How memory manager handles copy: */
 122 #define         MEMORY_OBJECT_COPY_NONE         0
 123                                         /* ... No special support */
 124 #define         MEMORY_OBJECT_COPY_CALL         1
 125                                         /* ... Make call on memory manager */
 126 #define         MEMORY_OBJECT_COPY_DELAY        2
 127                                         /* ... Memory manager doesn't
 128                                          *     change data externally.
 129                                          */
 130 #define         MEMORY_OBJECT_COPY_TEMPORARY    3
 131                                         /* ... Memory manager doesn't
 132                                          *     change data externally, and
 133                                          *     doesn't need to see changes.
 134                                          */
 135 #define         MEMORY_OBJECT_COPY_SYMMETRIC    4
 136                                         /* ... Memory manager doesn't
 137                                          *     change data externally,
 138                                          *     doesn't need to see changes,
 139                                          *     and object will not be
 140                                          *     multiply mapped.
 141                                          *
 142                                          *     XXX
 143                                          *     Not yet safe for non-kernel use.
 144                                          */
 145
 146 #define         MEMORY_OBJECT_COPY_INVALID      5
 147                                         /* ...  An invalid copy strategy,
 148                                          *      for external objects which
 149                                          *      have not been initialized.
 150                                          *      Allows copy_strategy to be
 151                                          *      examined without also
 152                                          *      examining pager_ready and
 153                                          *      internal.
 154                                          */
 155
 156 typedef int             memory_object_return_t;
 157                                         /* Which pages to return to manager
 158                                            this time (lock_request) */
 159 #define         MEMORY_OBJECT_RETURN_NONE       0
 160                                         /* ... don't return any. */
 161 #define         MEMORY_OBJECT_RETURN_DIRTY      1
 162                                         /* ... only dirty pages. */
 163 #define         MEMORY_OBJECT_RETURN_ALL        2
 164                                         /* ... dirty and precious pages. */
 165 #define         MEMORY_OBJECT_RETURN_ANYTHING   3
 166                                         /* ... any resident page. */
 167
 168 /*
 169  *      Data lock request flags
 170  */
 171
 172 #define         MEMORY_OBJECT_DATA_FLUSH        0x1
 173 #define         MEMORY_OBJECT_DATA_NO_CHANGE    0x2
 174 #define         MEMORY_OBJECT_DATA_PURGE        0x4
 175 #define         MEMORY_OBJECT_COPY_SYNC         0x8
 176 #define         MEMORY_OBJECT_DATA_SYNC         0x10
 177
 178 /*
 179  *      Types for the memory object flavor interfaces
 180  */
 181
 182 #define MEMORY_OBJECT_INFO_MAX      (1024)
 183 typedef int     *memory_object_info_t;
 184 typedef int      memory_object_flavor_t;
 185 typedef int      memory_object_info_data_t[MEMORY_OBJECT_INFO_MAX];
 186
 187
 188 #define MEMORY_OBJECT_PERFORMANCE_INFO  11
 189 #define MEMORY_OBJECT_ATTRIBUTE_INFO    14
 190 #define MEMORY_OBJECT_BEHAVIOR_INFO     15
 191
 192 #ifdef  __APPLE_API_UNSTABLE
 193 #define OLD_MEMORY_OBJECT_BEHAVIOR_INFO         10
 194 #define OLD_MEMORY_OBJECT_ATTRIBUTE_INFO        12
 195
 196 struct old_memory_object_behave_info {
 197         memory_object_copy_strategy_t   copy_strategy;
 198         boolean_t                       temporary;
 199         boolean_t                       invalidate;
 200 };
 201
 202 struct old_memory_object_attr_info {                    /* old attr list */
 203         boolean_t                       object_ready;
 204         boolean_t                       may_cache;
 205         memory_object_copy_strategy_t   copy_strategy;
 206 };
 207
 208 typedef struct old_memory_object_behave_info *old_memory_object_behave_info_t;
 209 typedef struct old_memory_object_behave_info old_memory_object_behave_info_data_t;
 210 typedef struct old_memory_object_attr_info *old_memory_object_attr_info_t;
 211 typedef struct old_memory_object_attr_info old_memory_object_attr_info_data_t;
 212
 213 #define OLD_MEMORY_OBJECT_BEHAVE_INFO_COUNT     \
 214                 (sizeof(old_memory_object_behave_info_data_t)/sizeof(int))
 215 #define OLD_MEMORY_OBJECT_ATTR_INFO_COUNT               \
 216                 (sizeof(old_memory_object_attr_info_data_t)/sizeof(int))
 217 #endif  /* __APPLE_API_UNSTABLE */
 218
 219 struct memory_object_perf_info {
 220         vm_size_t                       cluster_size;
 221         boolean_t                       may_cache;
 222 };
 223
 224 struct memory_object_attr_info {
 225         memory_object_copy_strategy_t   copy_strategy;
 226         vm_offset_t                     cluster_size;
 227         boolean_t                       may_cache_object;
 228         boolean_t                       temporary;
 229 };
 230
 231 struct memory_object_behave_info {
 232         memory_object_copy_strategy_t   copy_strategy;
 233         boolean_t                       temporary;
 234         boolean_t                       invalidate;
 235         boolean_t                       silent_overwrite;
 236         boolean_t                       advisory_pageout;
 237 };
 238
 239
 240 typedef struct memory_object_behave_info *memory_object_behave_info_t;
 241 typedef struct memory_object_behave_info memory_object_behave_info_data_t;
 242
 243 typedef struct memory_object_perf_info  *memory_object_perf_info_t;
 244 typedef struct memory_object_perf_info  memory_object_perf_info_data_t;
 245
 246 typedef struct memory_object_attr_info  *memory_object_attr_info_t;
 247 typedef struct memory_object_attr_info  memory_object_attr_info_data_t;
 248
 249 #define MEMORY_OBJECT_BEHAVE_INFO_COUNT         \
 250                 (sizeof(memory_object_behave_info_data_t)/sizeof(int))
 251 #define MEMORY_OBJECT_PERF_INFO_COUNT           \
 252                 (sizeof(memory_object_perf_info_data_t)/sizeof(int))
 253 #define MEMORY_OBJECT_ATTR_INFO_COUNT           \
 254                 (sizeof(memory_object_attr_info_data_t)/sizeof(int))
 255
 256 #define invalid_memory_object_flavor(f)                                 \
 257         (f != MEMORY_OBJECT_ATTRIBUTE_INFO &&                           \
 258          f != MEMORY_OBJECT_PERFORMANCE_INFO &&                         \
 259          f != OLD_MEMORY_OBJECT_BEHAVIOR_INFO &&                        \
 260          f != MEMORY_OBJECT_BEHAVIOR_INFO &&                            \
 261          f != OLD_MEMORY_OBJECT_ATTRIBUTE_INFO)
 262
 263
 264 /*
 265  * Used to support options on memory_object_release_name call
 266  */
 267 #define MEMORY_OBJECT_TERMINATE_IDLE    0x1
 268 #define MEMORY_OBJECT_RESPECT_CACHE     0x2
 269 #define MEMORY_OBJECT_RELEASE_NO_OP     0x4
 270
 271
 272 /*
 273  *  Universal Page List data structures
 274  */
 275
 276 #define MAX_UPL_TRANSFER 256
 277
 278 struct upl_page_info {
 279         vm_offset_t     phys_addr;
 280         unsigned int
 281                         pageout:1,      /* page is to be removed on commit */
 282                         absent:1,       /* No valid data in this page */
 283                         dirty:1,        /* Page must be cleaned (O) */
 284                         precious:1,     /* must be cleaned, we have only copy */
 285                         device:1,       /* no page data, mapped dev memory */
 286                         :0;             /* force to long boundary */
 287 };
 288
 289 typedef struct upl_page_info    upl_page_info_t;
 290 typedef upl_page_info_t         *upl_page_info_array_t;
 291 typedef upl_page_info_array_t   upl_page_list_ptr_t;
 292
 293 /* named entry processor mapping options */
 294 /* enumerated */
 295 #define MAP_MEM_NOOP            0
 296 #define MAP_MEM_COPYBACK        1
 297 #define MAP_MEM_IO              2
 298 #define MAP_MEM_WTHRU           3
 299 #define MAP_MEM_WCOMB           4       /* Write combining mode */
 300                                         /* aka store gather     */
 301
 302 #define GET_MAP_MEM(flags)      \
 303         ((((unsigned int)(flags)) >> 24) & 0xFF)
 304
 305 #define SET_MAP_MEM(caching, flags)     \
 306         ((flags) = ((((unsigned int)(caching)) << 24) \
 307                         & 0xFF000000) | ((flags) & 0xFFFFFF));
 308
 309 /* leave room for vm_prot bits */
 310 #define MAP_MEM_ONLY            0x10000 /* change processor caching  */
 311 #define MAP_MEM_NAMED_CREATE    0x20000 /* create extant object      */
 312
 313 /* upl invocation flags */
 314 /* top nibble is used by super upl */
 315
 316 #define UPL_FLAGS_NONE          0x0
 317 #define UPL_COPYOUT_FROM        0x1
 318 #define UPL_PRECIOUS            0x2
 319 #define UPL_NO_SYNC             0x4
 320 #define UPL_CLEAN_IN_PLACE      0x8
 321 #define UPL_NOBLOCK             0x10
 322 #define UPL_RET_ONLY_DIRTY      0x20
 323 #define UPL_SET_INTERNAL        0x40
 324 #define UPL_QUERY_OBJECT_TYPE   0x80
 325 #define UPL_RET_ONLY_ABSENT     0x100  /* used only for COPY_FROM = FALSE */
 326 #define UPL_FILE_IO             0x200
 327 #define UPL_SET_LITE            0x400
 328 #define UPL_SET_INTERRUPTIBLE   0x800
 329 #define UPL_SET_IO_WIRE         0x1000
 330 #define UPL_FOR_PAGEOUT         0x2000
 331
 332 /* upl abort error flags */
 333 #define UPL_ABORT_RESTART       0x1
 334 #define UPL_ABORT_UNAVAILABLE   0x2
 335 #define UPL_ABORT_ERROR         0x4
 336 #define UPL_ABORT_FREE_ON_EMPTY 0x8  /* only implemented in wrappers */
 337 #define UPL_ABORT_DUMP_PAGES    0x10
 338 #define UPL_ABORT_NOTIFY_EMPTY  0x20
 339
 340 /* upl pages check flags */
 341 #define UPL_CHECK_DIRTY         0x1
 342
 343 /* upl pagein/pageout  flags */
 344 #define UPL_IOSYNC      0x1
 345 #define UPL_NOCOMMIT    0x2
 346 #define UPL_NORDAHEAD   0x4
 347
 348 /* upl commit flags */
 349 #define UPL_COMMIT_FREE_ON_EMPTY        0x1 /* only implemented in wrappers */
 350 #define UPL_COMMIT_CLEAR_DIRTY          0x2
 351 #define UPL_COMMIT_SET_DIRTY            0x4
 352 #define UPL_COMMIT_INACTIVATE           0x8
 353 #define UPL_COMMIT_NOTIFY_EMPTY         0x10
 354
 355 /* flags for return of state from vm_map_get_upl,  vm_upl address space */
 356 /* based call */
 357 #define UPL_DEV_MEMORY                  0x1
 358 #define UPL_PHYS_CONTIG                 0x2
 359
 360
 361 /* access macros for upl_t */
 362
 363 #define UPL_DEVICE_PAGE(upl) \
 364         (((upl)[(index)].phys_addr != 0) ? (!((upl)[0].device)) : FALSE)
 365
 366 #define UPL_PAGE_PRESENT(upl, index)  \
 367         ((upl)[(index)].phys_addr != 0)
 368
 369 #define UPL_PHYS_PAGE(upl, index) \
 370         (((upl)[(index)].phys_addr != 0) ?  \
 371                         ((upl)[(index)].phys_addr) : (vm_offset_t)NULL)
 372
 373 #define UPL_DIRTY_PAGE(upl, index) \
 374         (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].dirty) : FALSE)
 375
 376 #define UPL_PRECIOUS_PAGE(upl, index) \
 377         (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].precious) : FALSE)
 378
 379 #define UPL_VALID_PAGE(upl, index) \
 380         (((upl)[(index)].phys_addr != 0) ? (!((upl)[(index)].absent)) : FALSE)
 381
 382 #define UPL_PAGEOUT_PAGE(upl, index) \
 383         (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].pageout) : FALSE)
 384
 385 #define UPL_SET_PAGE_FREE_ON_COMMIT(upl, index) \
 386         if ((upl)[(index)].phys_addr != 0)     \
 387                 ((upl)[(index)].pageout) =  TRUE
 388
 389 #define UPL_CLR_PAGE_FREE_ON_COMMIT(upl, index) \
 390         if ((upl)[(index)].phys_addr != 0)     \
 391                 ((upl)[(index)].pageout) =  FALSE
 392
 393
 394 /*
 395  * Flags for the UPL page ops routine.  This routine is not exported
 396  * out of the kernel at the moment and so the defs live here.
 397  */
 398 #define UPL_POP_DIRTY           0x1
 399 #define UPL_POP_PAGEOUT         0x2
 400 #define UPL_POP_PRECIOUS        0x4
 401 #define UPL_POP_ABSENT          0x8
 402 #define UPL_POP_BUSY            0x10
 403
 404 #define UPL_POP_PHYSICAL        0x10000000
 405 #define UPL_POP_DUMP            0x20000000
 406 #define UPL_POP_SET             0x40000000
 407 #define UPL_POP_CLR             0x80000000
 408
 409
 410
 411 #ifdef KERNEL_PRIVATE
 412
 413 extern void memory_object_reference(memory_object_t object);
 414 extern void memory_object_deallocate(memory_object_t object);
 415
 416 extern void memory_object_default_reference(memory_object_default_t);
 417 extern void memory_object_default_deallocate(memory_object_default_t);
 418
 419 extern void memory_object_control_reference(memory_object_control_t control);
 420 extern void memory_object_control_deallocate(memory_object_control_t control);
 421
 422
 423 /* The call prototyped below is used strictly by UPL_GET_INTERNAL_PAGE_LIST */
 424
 425 extern vm_size_t        upl_offset_to_pagelist;
 426 extern vm_size_t upl_get_internal_pagelist_offset();
 427
 428 /* UPL_GET_INTERNAL_PAGE_LIST is only valid on internal objects where the */
 429 /* list request was made with the UPL_INTERNAL flag */
 430
 431 #define UPL_GET_INTERNAL_PAGE_LIST(upl) \
 432         ((upl_page_info_t *)((upl_offset_to_pagelist == 0) ?  \
 433         (unsigned int)upl + (unsigned int)(upl_offset_to_pagelist = upl_get_internal_pagelist_offset()): \
 434         (unsigned int)upl + (unsigned int)upl_offset_to_pagelist))
 435
 436 extern boolean_t        upl_page_present(upl_page_info_t *upl, int index);
 437
 438 extern boolean_t        upl_dirty_page(upl_page_info_t *upl, int index);
 439
 440 extern boolean_t        upl_valid_page(upl_page_info_t *upl, int index);
 441
 442 extern vm_offset_t      upl_phys_page(upl_page_info_t *upl, int index);
 443
 444 extern void             upl_set_dirty(upl_t   upl);
 445
 446 extern void             upl_clear_dirty(upl_t   upl);
 447
 448
 449 /*
 450  * The following interface definitions should be generated automatically
 451  * through Mig definitions or whatever follows the MIG tool as part of the
 452  * component API.  Until this is up and running however this explicit
 453  * description will do.
 454  */
 455
 456 #include <mach/message.h>
 457
 458 /*  supply a map and a range, a upl will be returned. */
 459 extern int kernel_vm_map_get_upl(
 460         vm_map_t                map,
 461         vm_address_t            offset,
 462         vm_size_t               *upl_size,
 463         upl_t                   *upl,
 464         upl_page_info_array_t   page_list,
 465         unsigned int            *count,
 466         int                     *flags,
 467         int                     force_data_sync);
 468
 469 extern int kernel_upl_map(
 470         vm_map_t        map,
 471         upl_t           upl,
 472         vm_offset_t     *dst_addr);
 473
 474 extern int kernel_upl_unmap(
 475         vm_map_t        map,
 476         upl_t           upl);
 477
 478 extern int     kernel_upl_commit(
 479         upl_t                   upl,
 480         upl_page_info_t         *pl,
 481         mach_msg_type_number_t   count);
 482
 483 extern int kernel_upl_commit_range(
 484         upl_t                   upl,
 485         vm_offset_t             offset,
 486         vm_size_t               size,
 487         int                     flags,
 488         upl_page_info_array_t   pl,
 489         mach_msg_type_number_t  count);
 490
 491 extern int kernel_upl_abort(
 492         upl_t                   upl,
 493         int                     abort_type);
 494
 495 extern int kernel_upl_abort_range(
 496         upl_t                   upl,
 497         vm_offset_t             offset,
 498         vm_size_t               size,
 499         int                     abort_flags);
 500
 501
 502 #endif  /* KERNEL_PRIVATE */
 503
 504 #endif  /* __APPLE_API_EVOLVING */
 505
 506 #endif  /* _MACH_MEMORY_OBJECT_TYPES_H_ */