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
 294 /* upl invocation flags */
 295
 296 #define UPL_FLAGS_NONE          0x0
 297 #define UPL_COPYOUT_FROM        0x1
 298 #define UPL_PRECIOUS            0x2
 299 #define UPL_NO_SYNC             0x4
 300 #define UPL_CLEAN_IN_PLACE      0x8
 301 #define UPL_NOBLOCK             0x10
 302 #define UPL_RET_ONLY_DIRTY      0x20
 303 #define UPL_SET_INTERNAL        0x40
 304 #define UPL_QUERY_OBJECT_TYPE   0x80
 305 #define UPL_RET_ONLY_ABSENT     0x100  /* used only for COPY_FROM = FALSE */
 306 #define UPL_FILE_IO             0x200
 307
 308 /* upl abort error flags */
 309 #define UPL_ABORT_RESTART       0x1
 310 #define UPL_ABORT_UNAVAILABLE   0x2
 311 #define UPL_ABORT_ERROR         0x4
 312 #define UPL_ABORT_FREE_ON_EMPTY 0x8  /* only implemented in wrappers */
 313 #define UPL_ABORT_DUMP_PAGES    0x10
 314 #define UPL_ABORT_NOTIFY_EMPTY  0x20
 315
 316 /* upl pages check flags */
 317 #define UPL_CHECK_DIRTY         0x1
 318
 319 /* upl pagein/pageout  flags */
 320 #define UPL_IOSYNC      0x1
 321 #define UPL_NOCOMMIT    0x2
 322 #define UPL_NORDAHEAD   0x4
 323
 324 /* upl commit flags */
 325 #define UPL_COMMIT_FREE_ON_EMPTY        0x1 /* only implemented in wrappers */
 326 #define UPL_COMMIT_CLEAR_DIRTY          0x2
 327 #define UPL_COMMIT_SET_DIRTY            0x4
 328 #define UPL_COMMIT_INACTIVATE           0x8
 329 #define UPL_COMMIT_NOTIFY_EMPTY         0x10
 330
 331 /* flags for return of state from vm_map_get_upl,  vm_upl address space */
 332 /* based call */
 333 #define UPL_DEV_MEMORY                  0x1
 334 #define UPL_PHYS_CONTIG                 0x2
 335
 336
 337 /* access macros for upl_t */
 338
 339 #define UPL_DEVICE_PAGE(upl) \
 340         (((upl)[(index)].phys_addr != 0) ? (!((upl)[0].device)) : FALSE)
 341
 342 #define UPL_PAGE_PRESENT(upl, index)  \
 343         ((upl)[(index)].phys_addr != 0)
 344
 345 #define UPL_PHYS_PAGE(upl, index) \
 346         (((upl)[(index)].phys_addr != 0) ?  \
 347                         ((upl)[(index)].phys_addr) : (vm_offset_t)NULL)
 348
 349 #define UPL_DIRTY_PAGE(upl, index) \
 350         (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].dirty) : FALSE)
 351
 352 #define UPL_PRECIOUS_PAGE(upl, index) \
 353         (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].precious) : FALSE)
 354
 355 #define UPL_VALID_PAGE(upl, index) \
 356         (((upl)[(index)].phys_addr != 0) ? (!((upl)[(index)].absent)) : FALSE)
 357
 358 #define UPL_PAGEOUT_PAGE(upl, index) \
 359         (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].pageout) : FALSE)
 360
 361 #define UPL_SET_PAGE_FREE_ON_COMMIT(upl, index) \
 362         if ((upl)[(index)].phys_addr != 0)     \
 363                 ((upl)[(index)].pageout) =  TRUE
 364
 365 #define UPL_CLR_PAGE_FREE_ON_COMMIT(upl, index) \
 366         if ((upl)[(index)].phys_addr != 0)     \
 367                 ((upl)[(index)].pageout) =  FALSE
 368
 369
 370 /*
 371  * Flags for the UPL page ops routine.  This routine is not exported
 372  * out of the kernel at the moment and so the defs live here.
 373  */
 374 #define UPL_POP_DIRTY           0x1
 375 #define UPL_POP_PAGEOUT         0x2
 376 #define UPL_POP_PRECIOUS        0x4
 377 #define UPL_POP_ABSENT          0x8
 378 #define UPL_POP_BUSY            0x10
 379
 380 #define UPL_POP_PHYSICAL        0x10000000
 381 #define UPL_POP_DUMP            0x20000000
 382 #define UPL_POP_SET             0x40000000
 383 #define UPL_POP_CLR             0x80000000
 384
 385
 386 #ifdef KERNEL_PRIVATE
 387
 388 extern void memory_object_reference(memory_object_t object);
 389 extern void memory_object_deallocate(memory_object_t object);
 390
 391 extern void memory_object_default_reference(memory_object_default_t);
 392 extern void memory_object_default_deallocate(memory_object_default_t);
 393
 394 extern void memory_object_control_reference(memory_object_control_t control);
 395 extern void memory_object_control_deallocate(memory_object_control_t control);
 396
 397
 398 /* The call prototyped below is used strictly by UPL_GET_INTERNAL_PAGE_LIST */
 399
 400 extern vm_size_t        upl_offset_to_pagelist;
 401 extern vm_size_t upl_get_internal_pagelist_offset();
 402
 403 /* UPL_GET_INTERNAL_PAGE_LIST is only valid on internal objects where the */
 404 /* list request was made with the UPL_INTERNAL flag */
 405
 406 #define UPL_GET_INTERNAL_PAGE_LIST(upl) \
 407         ((upl_page_info_t *)((upl_offset_to_pagelist == 0) ?  \
 408         (unsigned int)upl + (unsigned int)(upl_offset_to_pagelist = upl_get_internal_pagelist_offset()): \
 409         (unsigned int)upl + (unsigned int)upl_offset_to_pagelist))
 410
 411 extern boolean_t        upl_page_present(upl_page_info_t *upl, int index);
 412
 413 extern boolean_t        upl_dirty_page(upl_page_info_t *upl, int index);
 414
 415 extern boolean_t        upl_valid_page(upl_page_info_t *upl, int index);
 416
 417 extern vm_offset_t      upl_phys_page(upl_page_info_t *upl, int index);
 418
 419 extern void             upl_set_dirty(upl_t   upl);
 420
 421 extern void             upl_clear_dirty(upl_t   upl);
 422
 423 #endif  /* KERNEL_PRIVATE */
 424
 425 #endif  /* __APPLE_API_EVOLVING */
 426
 427 #endif  /* _MACH_MEMORY_OBJECT_TYPES_H_ */