iokit/IOKit/IOMultiMemoryDescriptor.h

   1 /*
   2  * Copyright (c) 1998-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 #ifndef _IOMULTIMEMORYDESCRIPTOR_H
  24 #define _IOMULTIMEMORYDESCRIPTOR_H
  25
  26 #include <IOKit/IOMemoryDescriptor.h>
  27
  28 /*! @class IOMultiMemoryDescriptor : public IOMemoryDescriptor
  29     @abstract The IOMultiMemoryDescriptor object describes a memory area made up of several other IOMemoryDescriptors.
  30     @discussion The IOMultiMemoryDescriptor object represents multiple ranges of memory, specified as an ordered list of IOMemoryDescriptors.  The descriptors are chained end-to-end to make up a single contiguous buffer. */
  31
  32 class IOMultiMemoryDescriptor : public IOMemoryDescriptor
  33 {
  34     OSDeclareDefaultStructors(IOMultiMemoryDescriptor);
  35
  36 protected:
  37
  38     IOMemoryDescriptor ** _descriptors;
  39     UInt32                _descriptorsCount;
  40     bool                  _descriptorsIsAllocated;
  41
  42     virtual void free();
  43
  44     /*
  45      * These methods are not supported under this subclass.
  46      */
  47
  48     virtual bool initWithAddress( void *      address,       /* not supported */
  49                                   IOByteCount withLength,
  50                                   IODirection withDirection );
  51
  52     virtual bool initWithAddress( vm_address_t address,      /* not supported */
  53                                   IOByteCount  withLength,
  54                                   IODirection  withDirection,
  55                                   task_t       withTask );
  56
  57     virtual bool initWithPhysicalAddress(
  58                                   IOPhysicalAddress address, /* not supported */
  59                                   IOByteCount       withLength,
  60                                   IODirection       withDirection );
  61
  62     virtual bool initWithPhysicalRanges(
  63                                   IOPhysicalRange * ranges,  /* not supported */
  64                                   UInt32            withCount,
  65                                   IODirection       withDirection,
  66                                   bool              asReference = false );
  67
  68     virtual bool initWithRanges(  IOVirtualRange * ranges,   /* not supported */
  69                                   UInt32           withCount,
  70                                   IODirection      withDirection,
  71                                   task_t           withTask,
  72                                   bool             asReference = false );
  73
  74     virtual void * getVirtualSegment( IOByteCount   offset,  /* not supported */
  75                                       IOByteCount * length );
  76
  77     IOMemoryDescriptor::withAddress;                         /* not supported */
  78     IOMemoryDescriptor::withPhysicalAddress;                 /* not supported */
  79     IOMemoryDescriptor::withPhysicalRanges;                  /* not supported */
  80     IOMemoryDescriptor::withRanges;                          /* not supported */
  81     IOMemoryDescriptor::withSubRange;                        /* not supported */
  82
  83 public:
  84
  85 /*! @function withDescriptors
  86     @abstract Create an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
  87     @discussion This method creates and initializes an IOMultiMemoryDescriptor for memory consisting of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer.  Passing the descriptor array as a reference will avoid an extra allocation.
  88     @param descriptors An array of IOMemoryDescriptors which make up the memory to be described.
  89     @param withCount The object count for the descriptors array.
  90     @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
  91     @param asReference If false, the IOMultiMemoryDescriptor object will make a copy of the descriptors array, otherwise, the array will be used in situ, avoiding an extra allocation.
  92     @result The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure. */
  93
  94     static IOMultiMemoryDescriptor * withDescriptors(
  95                                   IOMemoryDescriptor ** descriptors,
  96                                   UInt32                withCount,
  97                                   IODirection           withDirection,
  98                                   bool                  asReference = false );
  99
 100 /*! @function withDescriptors
 101     @abstract Initialize an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
 102     @discussion This method initializes an IOMultiMemoryDescriptor for memory consisting of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer.  Passing the descriptor array as a reference will avoid an extra allocation.
 103     @param descriptors An array of IOMemoryDescriptors which make up the memory to be described.
 104     @param withCount The object count for the descriptors array.
 105     @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
 106     @param asReference If false, the IOMultiMemoryDescriptor object will make a copy of the descriptors array, otherwise, the array will be used in situ, avoiding an extra allocation.
 107     @result The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 108
 109     virtual bool initWithDescriptors(
 110                                   IOMemoryDescriptor ** descriptors,
 111                                   UInt32                withCount,
 112                                   IODirection           withDirection,
 113                                   bool                  asReference = false );
 114
 115 /*! @function getPhysicalAddress
 116     @abstract Return the physical address of the first byte in the memory.
 117     @discussion This method returns the physical address of the  first byte in the memory. It is most useful on memory known to be physically contiguous.
 118     @result A physical address. */
 119
 120     virtual IOPhysicalAddress getPhysicalSegment( IOByteCount   offset,
 121                                                   IOByteCount * length );
 122
 123 /*! @function prepare
 124     @abstract Prepare the memory for an I/O transfer.
 125     @discussion This involves paging in the memory, if necessary, and wiring it down for the duration of the transfer.  The complete() method completes the processing of the memory after the I/O transfer finishes.  This method needn't called for non-pageable memory.
 126     @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
 127     @result An IOReturn code. */
 128
 129     virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);
 130
 131 /*! @function complete
 132     @abstract Complete processing of the memory after an I/O transfer finishes.
 133     @discussion This method should not be called unless a prepare was previously issued; the prepare() and complete() must occur in pairs, before and after an I/O transfer involving pageable memory.
 134     @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
 135     @result An IOReturn code. */
 136
 137     virtual IOReturn complete(IODirection forDirection = kIODirectionNone);
 138
 139 /*! @function readBytes
 140     @abstract Copy data from the memory descriptor's buffer to the specified buffer.
 141     @discussion This method copies data from the memory descriptor's memory at the given offset, to the caller's buffer.
 142     @param offset A byte offset into the memory descriptor's memory.
 143     @param bytes The caller supplied buffer to copy the data to.
 144     @param withLength The length of the data to copy.
 145     @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */
 146
 147     virtual IOByteCount readBytes( IOByteCount offset,
 148                                    void *      bytes,
 149                                    IOByteCount withLength );
 150
 151 /*! @function writeBytes
 152     @abstract Copy data to the memory descriptor's buffer from the specified buffer.
 153     @discussion This method copies data to the memory descriptor's memory at the given offset, from the caller's buffer.
 154     @param offset A byte offset into the memory descriptor's memory.
 155     @param bytes The caller supplied buffer to copy the data from.
 156     @param withLength The length of the data to copy.
 157     @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */
 158
 159     virtual IOByteCount writeBytes( IOByteCount  offset,
 160                                     const void * bytes,
 161                                     IOByteCount  withLength );
 162
 163     virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
 164                                                IOByteCount * length);
 165 };
 166
 167 #endif /* !_IOMULTIMEMORYDESCRIPTOR_H */