X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/de355530ae67247cbd0da700edb3a2a1dae884c2..5d5c5d0d5b79ade9a973d55186ffda2638ba2b6e:/iokit/IOKit/IOBufferMemoryDescriptor.h diff --git a/iokit/IOKit/IOBufferMemoryDescriptor.h b/iokit/IOKit/IOBufferMemoryDescriptor.h index 4e40b5a8b..fcfba8f8a 100644 --- a/iokit/IOKit/IOBufferMemoryDescriptor.h +++ b/iokit/IOKit/IOBufferMemoryDescriptor.h @@ -1,23 +1,31 @@ /* * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved. * - * @APPLE_LICENSE_HEADER_START@ + * @APPLE_LICENSE_OSREFERENCE_HEADER_START@ * - * The contents of this file constitute Original Code as defined in and - * are subject to the Apple Public Source License Version 1.1 (the - * "License"). You may not use this file except in compliance with the - * License. Please obtain a copy of the License at - * http://www.apple.com/publicsource and read it before using this file. - * - * This Original Code and all software distributed under the License are - * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER - * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, - * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the - * License for the specific language governing rights and limitations - * under the License. - * - * @APPLE_LICENSE_HEADER_END@ + * This file contains Original Code and/or Modifications of Original Code + * as defined in and that are subject to the Apple Public Source License + * Version 2.0 (the 'License'). You may not use this file except in + * compliance with the License. The rights granted to you under the + * License may not be used to create, or enable the creation or + * redistribution of, unlawful or unlicensed copies of an Apple operating + * system, or to circumvent, violate, or enable the circumvention or + * violation of, any terms of an Apple operating system software license + * agreement. + * + * Please obtain a copy of the License at + * http://www.opensource.apple.com/apsl/ and read it before using this + * file. + * + * The Original Code and all software distributed under the License are + * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER + * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, + * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. + * Please see the License for the specific language governing rights and + * limitations under the License. + * + * @APPLE_LICENSE_OSREFERENCE_HEADER_END@ */ #ifndef _IOBUFFERMEMORYDESCRIPTOR_H #define _IOBUFFERMEMORYDESCRIPTOR_H @@ -25,15 +33,19 @@ #include enum { - kIOMemoryDirectionMask = 0x0000000f, kIOMemoryPhysicallyContiguous = 0x00000010, kIOMemoryPageable = 0x00000020, + kIOMemoryPurgeable = 0x00000040, kIOMemorySharingTypeMask = 0x000f0000, kIOMemoryUnshared = 0x00000000, - kIOMemoryKernelUserShared = 0x00010000, + kIOMemoryKernelUserShared = 0x00010000 }; #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1 +/*! + @class IOBufferMemoryDescriptor + @abstract Provides a simple memory descriptor that allocates its own buffer memory. +*/ class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor { @@ -65,9 +77,19 @@ private: vm_size_t capacity, vm_offset_t alignment, task_t inTask); - OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0); + +#if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT)) + virtual bool initWithPhysicalMask( + task_t inTask, + IOOptionBits options, + mach_vm_size_t capacity, + mach_vm_address_t alignment, + mach_vm_address_t physicalMask); + OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1); +#else OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1); +#endif OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2); OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3); OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4); @@ -136,16 +158,18 @@ public: vm_offset_t alignment = 1); /*! @function inTaskWithOptions - @abstract Create a memory buffer with memory descriptor for that buffer. Added in Mac OS X 10.2. - @discussion This method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. + @abstract Creates a memory buffer with memory descriptor for that buffer. + @discussion Added in Mac OS X 10.2, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. @param inTask The task the buffer will be allocated in. - @param options Options for the allocation: - kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute. - kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired. + @param options Options for the allocation:
+ kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.
+ kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.
+ kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.
+ kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.
kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications. @param capacity The number of bytes to allocate. @param alignment The minimum required alignment of the buffer in bytes - 1 is the default for no required alignment. For example, pass 256 to get memory allocated at an address with bits 0-7 zero. - @result An instance of class IOBufferMemoryDescriptor. To be released by the caller, which will free the memory desriptor and associated buffer. */ + @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ static IOBufferMemoryDescriptor * inTaskWithOptions( task_t inTask, @@ -153,6 +177,26 @@ public: vm_size_t capacity, vm_offset_t alignment = 1); +#if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT)) +/*! @function inTaskWithPhysicalMask + @abstract Creates a memory buffer with memory descriptor for that buffer. + @discussion Added in Mac OS X 10.5, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. + @param inTask The task the buffer will be mapped in. Pass NULL to create memory unmapped in any task (eg. for use as a DMA buffer). + @param options Options for the allocation:
+ kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.
+ kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.
+ kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications. + @param capacity The number of bytes to allocate. + @param mask The buffer will be allocated with pages such that physical addresses will only have bits set present in physicalMask. For example, pass 0x00000000FFFFFFFFULL for a buffer to be accessed by hardware that has 32 address bits. + @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ + + static IOBufferMemoryDescriptor * inTaskWithPhysicalMask( + task_t inTask, + IOOptionBits options, + mach_vm_size_t capacity, + mach_vm_address_t physicalMask); +#endif + /* * withCapacity: * @@ -238,14 +282,10 @@ public: */ virtual bool appendBytes(const void *bytes, vm_size_t withLength); - /* - * getPhysicalSegment: - * - * Get the physical address of the buffer, relative to the current position. - * If the current position is at the end of the buffer, a zero is returned. - */ - virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset, - IOByteCount * length); +#if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT)) + /* DEPRECATED */ virtual void * getVirtualSegment(IOByteCount offset, + /* DEPRECATED */ IOByteCount * length); +#endif }; #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */