xnu-2422.110.17.tar.gz

[apple/xnu.git] / iokit / IOKit / IOBufferMemoryDescriptor.h

diff --git a/iokit/IOKit/IOBufferMemoryDescriptor.h b/iokit/IOKit/IOBufferMemoryDescriptor.h
index 733fa1dd10f01e49edd0e009497a56987f8ec506..fdb0a398cf89b8bfad55e08b838b3283d7934c48 100644 (file)
--- a/iokit/IOKit/IOBufferMemoryDescriptor.h
+++ b/iokit/IOKit/IOBufferMemoryDescriptor.h
@@ -1,23 +1,29 @@
 /*
  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
  *
 /*
  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
  *

- * @APPLE_LICENSE_HEADER_START@
+ * @APPLE_OSREFERENCE_LICENSE_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 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.

  * 
  * 

- * This Original Code and all software distributed under the License are
- * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * 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,
  * 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.
+ * 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_HEADER_END@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@

  */
 #ifndef _IOBUFFERMEMORYDESCRIPTOR_H
 #define _IOBUFFERMEMORYDESCRIPTOR_H
  */
 #ifndef _IOBUFFERMEMORYDESCRIPTOR_H
 #define _IOBUFFERMEMORYDESCRIPTOR_H


@@ -25,24 +31,41 @@
 #include <IOKit/IOMemoryDescriptor.h>
 
 enum {
 #include <IOKit/IOMemoryDescriptor.h>
 
 enum {

-    kIOMemoryDirectionMask             = 0x0000000f,

     kIOMemoryPhysicallyContiguous      = 0x00000010,
     kIOMemoryPageable                  = 0x00000020,
     kIOMemoryPhysicallyContiguous      = 0x00000010,
     kIOMemoryPageable                  = 0x00000020,

+    kIOMemoryPurgeable                 = 0x00000040,
+    kIOMemoryHostPhysicallyContiguous          = 0x00000080,

     kIOMemorySharingTypeMask           = 0x000f0000,
     kIOMemoryUnshared                  = 0x00000000,
     kIOMemoryKernelUserShared          = 0x00010000,
     kIOMemorySharingTypeMask           = 0x000f0000,
     kIOMemoryUnshared                  = 0x00000000,
     kIOMemoryKernelUserShared          = 0x00010000,

+    // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor:
+    kIOBufferDescriptorMemoryFlags     = kIOMemoryDirectionMask 
+#ifdef XNU_KERNEL_PRIVATE
+                                       | kIOMemoryAutoPrepare
+#endif
+                                       | kIOMemoryThreadSafe
+                                       | kIOMemoryClearEncrypt
+                                       | kIOMemoryMapperNone

 };
 
 };
 

+#define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_           1
+#define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_    1
+/*!
+    @class IOBufferMemoryDescriptor
+    @abstract Provides a simple memory descriptor that allocates its own buffer memory.
+*/

 
 class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
 {
     OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
 
 
 class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
 {
     OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
 

-protected:
+private:

 /*! @struct ExpansionData
     @discussion This structure will be used to expand the capablilties of this class in the future.
     */    
 /*! @struct ExpansionData
     @discussion This structure will be used to expand the capablilties of this class in the future.
     */    

-    struct ExpansionData { };
+    struct ExpansionData {
+       IOMemoryMap *   map;
+    };

 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */
 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */


@@ -53,12 +76,34 @@ protected:
     vm_size_t            _capacity;
     vm_offset_t                 _alignment;
     IOOptionBits        _options;
     vm_size_t            _capacity;
     vm_offset_t                 _alignment;
     IOOptionBits        _options;

-    IOPhysicalAddress *  _physAddrs;
-    unsigned             _physSegCount;
+private:
+    uintptr_t           _internalReserved;
+    unsigned             _internalFlags;

 
 private:
 
 private:

+#ifndef __LP64__
+    virtual bool initWithOptions(
+                               IOOptionBits options,
+                               vm_size_t    capacity,
+                               vm_offset_t  alignment,
+                              task_t       inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */
+#endif /* !__LP64__ */
+
+public:
+    virtual bool initWithPhysicalMask(
+                               task_t            inTask,
+                               IOOptionBits      options,
+                               mach_vm_size_t    capacity,
+                               mach_vm_address_t alignment,
+                               mach_vm_address_t physicalMask);
+
+#ifdef __LP64__

     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);

+#else /* !__LP64__ */
+    OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);
+    OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1);
+#endif /* !__LP64__ */

     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);
     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);


@@ -77,38 +122,6 @@ private:
 protected:
     virtual void free();
 
 protected:
     virtual void free();
 

-    virtual bool initWithAddress( void *      address,       /* not supported */
-                                  IOByteCount withLength,
-                                  IODirection withDirection );
-
-    virtual bool initWithAddress( vm_address_t address,      /* not supported */
-                                  IOByteCount  withLength,
-                                  IODirection  withDirection,
-                                  task_t       withTask );
-
-    virtual bool initWithPhysicalAddress( 
-                                  IOPhysicalAddress address, /* not supported */
-                                  IOByteCount       withLength,
-                                  IODirection       withDirection );
-
-    virtual bool initWithPhysicalRanges( 
-                                  IOPhysicalRange * ranges,  /* not supported */
-                                  UInt32            withCount,
-                                  IODirection       withDirection,
-                                  bool              asReference = false );
-
-    virtual bool initWithRanges(  IOVirtualRange * ranges,   /* not supported */
-                                  UInt32           withCount,
-                                  IODirection      withDirection,
-                                  task_t           withTask,
-                                  bool             asReference = false );
-
-    IOGeneralMemoryDescriptor::withAddress;                  /* not supported */
-    IOGeneralMemoryDescriptor::withPhysicalAddress;          /* not supported */
-    IOGeneralMemoryDescriptor::withPhysicalRanges;           /* not supported */
-    IOGeneralMemoryDescriptor::withRanges;                   /* not supported */
-    IOGeneralMemoryDescriptor::withSubRange;                 /* not supported */
-

 public:
 
     /*
 public:
 
     /*


@@ -118,14 +131,62 @@ public:
      * hold capacity bytes.  The descriptor's length is initially set to the
      * capacity.
      */
      * hold capacity bytes.  The descriptor's length is initially set to the
      * capacity.
      */

+#ifndef __LP64__

     virtual bool initWithOptions(   IOOptionBits options,
                                     vm_size_t    capacity,
     virtual bool initWithOptions(   IOOptionBits options,
                                     vm_size_t    capacity,

-                                    vm_offset_t  alignment);
+                                    vm_offset_t  alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */
+#endif /* !__LP64__ */

 
     static IOBufferMemoryDescriptor * withOptions(  IOOptionBits options,
                                                     vm_size_t    capacity,
                                                     vm_offset_t  alignment = 1);
 
 
     static IOBufferMemoryDescriptor * withOptions(  IOOptionBits options,
                                                     vm_size_t    capacity,
                                                     vm_offset_t  alignment = 1);
 

+/*! @function inTaskWithOptions
+    @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:<br>
+    kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
+    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.<br>
+    kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br>
+    kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br>
+    kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br>
+    kIOMapInhibitCache - allocate memory with inhibited cache setting. <br>            
+    kIOMapWriteThruCache - allocate memory with writethru cache setting. <br>          
+    kIOMapCopybackCache - allocate memory with copyback cache setting. <br>            
+    kIOMapWriteCombineCache - allocate memory with writecombined cache setting.
+    @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 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,
+                                            IOOptionBits options,
+                                            vm_size_t    capacity,
+                                            vm_offset_t  alignment = 1);
+
+/*! @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:<br>
+    kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
+    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.<br>
+    kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br>
+    kIOMapInhibitCache - allocate memory with inhibited cache setting. <br>            
+    kIOMapWriteThruCache - allocate memory with writethru cache setting. <br>          
+    kIOMapCopybackCache - allocate memory with copyback cache setting. <br>            
+    kIOMapWriteCombineCache - allocate memory with writecombined cache setting.
+    @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);
+

     /*
      * withCapacity:
      *
     /*
      * withCapacity:
      *


@@ -137,16 +198,12 @@ public:
                                      vm_size_t    capacity,
                                      IODirection  withDirection,
                                      bool         withContiguousMemory = false);
                                      vm_size_t    capacity,
                                      IODirection  withDirection,
                                      bool         withContiguousMemory = false);

-    /*
-     * initWithBytes:
-     *
-     * Initialize a new IOBufferMemoryDescriptor preloaded with bytes (copied).
-     * The descriptor's length and capacity are set to the input buffer's size.
-     */
+#ifndef __LP64__

     virtual bool initWithBytes(const void * bytes,
                                vm_size_t    withLength,
                                IODirection  withDirection,
     virtual bool initWithBytes(const void * bytes,
                                vm_size_t    withLength,
                                IODirection  withDirection,

-                               bool         withContiguousMemory = false);
+                               bool         withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */
+#endif /* !__LP64__ */

 
     /*
      * withBytes:
 
     /*
      * withBytes:


@@ -211,14 +268,10 @@ public:
      */
     virtual bool appendBytes(const void *bytes, vm_size_t withLength);
 
      */
     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);    
+#ifndef __LP64__
+    virtual void * getVirtualSegment(IOByteCount offset,
+                                       IOByteCount * length) APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */
+#endif /* !__LP64__ */

 };
 
 #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */
 };
 
 #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */