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