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 _IOMULTIMEMORYDESCRIPTOR_H 30#define _IOMULTIMEMORYDESCRIPTOR_H 31 32#include <IOKit/IOMemoryDescriptor.h> 33 34/*! @class IOMultiMemoryDescriptor : public IOMemoryDescriptor 35 @abstract The IOMultiMemoryDescriptor object describes a memory area made up of several other IOMemoryDescriptors. 36 @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. */ 37 38class IOMultiMemoryDescriptor : public IOMemoryDescriptor 39{ 40 OSDeclareDefaultStructors(IOMultiMemoryDescriptor); 41 42protected: 43 44 IOMemoryDescriptor ** _descriptors; 45 UInt32 _descriptorsCount; 46 bool _descriptorsIsAllocated; 47 48 virtual void free(); 49 50 /* 51 * These methods are not supported under this subclass. 52 */ 53 54 virtual bool initWithAddress( void * address, /* not supported */ 55 IOByteCount withLength, 56 IODirection withDirection ); 57 58 virtual bool initWithAddress( vm_address_t address, /* not supported */ 59 IOByteCount withLength, 60 IODirection withDirection, 61 task_t withTask ); 62 63 virtual bool initWithPhysicalAddress( 64 IOPhysicalAddress address, /* not supported */ 65 IOByteCount withLength, 66 IODirection withDirection ); 67 68 virtual bool initWithPhysicalRanges( 69 IOPhysicalRange * ranges, /* not supported */ 70 UInt32 withCount, 71 IODirection withDirection, 72 bool asReference = false ); 73 74 virtual bool initWithRanges( IOVirtualRange * ranges, /* not supported */ 75 UInt32 withCount, 76 IODirection withDirection, 77 task_t withTask, 78 bool asReference = false ); 79 80 virtual void * getVirtualSegment( IOByteCount offset, /* not supported */ 81 IOByteCount * length ); 82 83 IOMemoryDescriptor::withAddress; /* not supported */ 84 IOMemoryDescriptor::withPhysicalAddress; /* not supported */ 85 IOMemoryDescriptor::withPhysicalRanges; /* not supported */ 86 IOMemoryDescriptor::withRanges; /* not supported */ 87 IOMemoryDescriptor::withSubRange; /* not supported */ 88 89public: 90 91/*! @function withDescriptors 92 @abstract Create an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors. 93 @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. 94 @param descriptors An array of IOMemoryDescriptors which make up the memory to be described. 95 @param withCount The object count for the descriptors array. 96 @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. 97 @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. 98 @result The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure. */ 99 100 static IOMultiMemoryDescriptor * withDescriptors( 101 IOMemoryDescriptor ** descriptors, 102 UInt32 withCount, 103 IODirection withDirection, 104 bool asReference = false ); 105 106/*! @function withDescriptors 107 @abstract Initialize an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors. 108 @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. 109 @param descriptors An array of IOMemoryDescriptors which make up the memory to be described. 110 @param withCount The object count for the descriptors array. 111 @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. 112 @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. 113 @result The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure. */ 114 115 virtual bool initWithDescriptors( 116 IOMemoryDescriptor ** descriptors, 117 UInt32 withCount, 118 IODirection withDirection, 119 bool asReference = false ); 120 121/*! @function getPhysicalAddress 122 @abstract Return the physical address of the first byte in the memory. 123 @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. 124 @result A physical address. */ 125 126 virtual IOPhysicalAddress getPhysicalSegment( IOByteCount offset, 127 IOByteCount * length ); 128 129 virtual addr64_t getPhysicalSegment64( IOByteCount offset, 130 IOByteCount * length ); 131 132/*! @function prepare 133 @abstract Prepare the memory for an I/O transfer. 134 @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. 135 @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor. 136 @result An IOReturn code. */ 137 138 virtual IOReturn prepare(IODirection forDirection = kIODirectionNone); 139 140/*! @function complete 141 @abstract Complete processing of the memory after an I/O transfer finishes. 142 @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. 143 @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor. 144 @result An IOReturn code. */ 145 146 virtual IOReturn complete(IODirection forDirection = kIODirectionNone); 147 148/*! @function readBytes 149 @abstract Copy data from the memory descriptor's buffer to the specified buffer. 150 @discussion This method copies data from the memory descriptor's memory at the given offset, to the caller's buffer. 151 @param offset A byte offset into the memory descriptor's memory. 152 @param bytes The caller supplied buffer to copy the data to. 153 @param withLength The length of the data to copy. 154 @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */ 155 156 virtual IOByteCount readBytes( IOByteCount offset, 157 void * bytes, 158 IOByteCount withLength ); 159 160/*! @function writeBytes 161 @abstract Copy data to the memory descriptor's buffer from the specified buffer. 162 @discussion This method copies data to the memory descriptor's memory at the given offset, from the caller's buffer. 163 @param offset A byte offset into the memory descriptor's memory. 164 @param bytes The caller supplied buffer to copy the data from. 165 @param withLength The length of the data to copy. 166 @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */ 167 168 virtual IOByteCount writeBytes( IOByteCount offset, 169 const void * bytes, 170 IOByteCount withLength ); 171 172 virtual IOPhysicalAddress getSourceSegment(IOByteCount offset, 173 IOByteCount * length); 174}; 175 176#endif /* !_IOMULTIMEMORYDESCRIPTOR_H */ 177