iokit/IOKit/IOSubMemoryDescriptor.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, 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 #ifndef _IOSUBMEMORYDESCRIPTOR_H
  30 #define _IOSUBMEMORYDESCRIPTOR_H
  31
  32 #include <IOKit/IOMemoryDescriptor.h>
  33 #include <libkern/c++/OSPtr.h>
  34
  35 /*! @class IOSubMemoryDescriptor : public IOMemoryDescriptor
  36  *   @abstract The IOSubMemoryDescriptor object describes a memory area made up of a portion of another IOMemoryDescriptor.
  37  *   @discussion The IOSubMemoryDescriptor object represents a subrange of memory, specified as a portion of another IOMemoryDescriptor. */
  38
  39 class IOSubMemoryDescriptor : public IOMemoryDescriptor
  40 {
  41         OSDeclareDefaultStructors(IOSubMemoryDescriptor);
  42
  43 protected:
  44         IOMemoryDescriptor * _parent;
  45         IOByteCount          _start;
  46
  47         virtual void free() APPLE_KEXT_OVERRIDE;
  48
  49 public:
  50 /*! @function withSubRange
  51  *   @abstract Create an IOMemoryDescriptor to describe a subrange of an existing descriptor.
  52  *   @discussion  This method creates and initializes an IOMemoryDescriptor for memory consisting of a subrange of the specified memory descriptor. The parent memory descriptor is retained by the new descriptor.
  53  *   @param of The parent IOMemoryDescriptor of which a subrange is to be used for the new descriptor, which will be retained by the subrange IOMemoryDescriptor.
  54  *   @param offset A byte offset into the parent memory descriptor's memory.
  55  *   @param length The length of the subrange.
  56  *   @param options
  57  *       kIOMemoryDirectionMask (options:direction)     This nibble indicates the I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
  58  *   @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
  59
  60         static OSPtr<IOSubMemoryDescriptor>       withSubRange(IOMemoryDescriptor *of,
  61             IOByteCount offset,
  62             IOByteCount length,
  63             IOOptionBits options);
  64
  65 /*
  66  * Initialize or reinitialize an IOSubMemoryDescriptor to describe
  67  * a subrange of an existing descriptor.
  68  *
  69  * An IOSubMemoryDescriptor can be re-used by calling initSubRange
  70  * again on an existing instance -- note that this behavior is not
  71  * commonly supported in other IOKit classes, although it is here.
  72  */
  73         virtual bool initSubRange( IOMemoryDescriptor * parent,
  74             IOByteCount offset, IOByteCount length,
  75             IODirection withDirection );
  76
  77 /*
  78  * IOMemoryDescriptor required methods
  79  */
  80
  81         virtual addr64_t getPhysicalSegment( IOByteCount   offset,
  82             IOByteCount * length,
  83             IOOptionBits  options = 0 ) APPLE_KEXT_OVERRIDE;
  84
  85         virtual IOReturn prepare(IODirection forDirection = kIODirectionNone) APPLE_KEXT_OVERRIDE;
  86
  87         virtual IOReturn complete(IODirection forDirection = kIODirectionNone) APPLE_KEXT_OVERRIDE;
  88
  89 #ifdef __LP64__
  90         virtual IOReturn redirect( task_t safeTask, bool redirect ) APPLE_KEXT_OVERRIDE;
  91 #else
  92         IOReturn redirect( task_t safeTask, bool redirect );
  93 #endif /* __LP64__ */
  94
  95         virtual IOReturn setPurgeable( IOOptionBits newState,
  96             IOOptionBits * oldState ) APPLE_KEXT_OVERRIDE;
  97
  98         IOReturn setOwnership( task_t newOwner,
  99             int newLedgerTag,
 100             IOOptionBits newLedgerOptions );
 101
 102 // support map() on kIOMemoryTypeVirtual without prepare()
 103         virtual IOMemoryMap *       makeMapping(
 104                 IOMemoryDescriptor *    owner,
 105                 task_t                  intoTask,
 106                 IOVirtualAddress        atAddress,
 107                 IOOptionBits            options,
 108                 IOByteCount             offset,
 109                 IOByteCount             length ) APPLE_KEXT_OVERRIDE;
 110
 111         virtual uint64_t getPreparationID( void ) APPLE_KEXT_OVERRIDE;
 112
 113 /*! @function getPageCounts
 114  *   @abstract Retrieve the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.
 115  *   @discussion This method returns the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.
 116  *   @param residentPageCount - If non-null, a pointer to a byte count that will return the number of resident pages encompassed by this IOMemoryDescriptor.
 117  *   @param dirtyPageCount - If non-null, a pointer to a byte count that will return the number of dirty pages encompassed by this IOMemoryDescriptor.
 118  *   @result An IOReturn code. */
 119
 120         IOReturn getPageCounts(IOByteCount * residentPageCount,
 121             IOByteCount * dirtyPageCount);
 122 };
 123
 124 #endif /* !_IOSUBMEMORYDESCRIPTOR_H */