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 50public: 51 52/*! @function withDescriptors 53 @abstract Create an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors. 54 @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. 55 @param descriptors An array of IOMemoryDescriptors which make up the memory to be described. 56 @param withCount The object count for the descriptors array. 57 @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. 58 @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. 59 @result The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure. */ 60 61 static IOMultiMemoryDescriptor * withDescriptors( 62 IOMemoryDescriptor ** descriptors, 63 UInt32 withCount, 64 IODirection withDirection, 65 bool asReference = false ); 66 67/*! @function withDescriptors 68 @abstract Initialize an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors. 69 @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. 70 @param descriptors An array of IOMemoryDescriptors which make up the memory to be described. 71 @param withCount The object count for the descriptors array. 72 @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. 73 @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. 74 @result The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure. */ 75 76 virtual bool initWithDescriptors( 77 IOMemoryDescriptor ** descriptors, 78 UInt32 withCount, 79 IODirection withDirection, 80 bool asReference = false ); 81 82/*! @function getPhysicalSegment 83 @abstract Break a memory descriptor into its physically contiguous segments. 84 @discussion This method returns the physical address of the byte at the given offset into the memory, and optionally the length of the physically contiguous segment from that offset. 85 @param offset A byte offset into the memory whose physical address to return. 86 @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset. 87 @result A physical address, or zero if the offset is beyond the length of the memory. */ 88 89 virtual addr64_t getPhysicalSegment( IOByteCount offset, 90 IOByteCount * length, 91 IOOptionBits options = 0 ); 92 93/*! @function prepare 94 @abstract Prepare the memory for an I/O transfer. 95 @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. 96 @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor. 97 @result An IOReturn code. */ 98 99 virtual IOReturn prepare(IODirection forDirection = kIODirectionNone); 100 101/*! @function complete 102 @abstract Complete processing of the memory after an I/O transfer finishes. 103 @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. 104 @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor. 105 @result An IOReturn code. */ 106 107 virtual IOReturn complete(IODirection forDirection = kIODirectionNone); 108}; 109 110#endif /* !_IOMULTIMEMORYDESCRIPTOR_H */ 111