The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/iokit/IOKit/IOBufferMemoryDescriptor.h

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    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 #ifndef _IOBUFFERMEMORYDESCRIPTOR_H
   29 #define _IOBUFFERMEMORYDESCRIPTOR_H
   30 
   31 #include <IOKit/IOMemoryDescriptor.h>
   32 
   33 enum {
   34     kIOMemoryPhysicallyContiguous       = 0x00000010,
   35     kIOMemoryPageable                   = 0x00000020,
   36     kIOMemoryPurgeable                  = 0x00000040,
   37     kIOMemorySharingTypeMask            = 0x000f0000,
   38     kIOMemoryUnshared                   = 0x00000000,
   39     kIOMemoryKernelUserShared           = 0x00010000
   40 };
   41 
   42 #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_    1
   43 /*!
   44     @class IOBufferMemoryDescriptor
   45     @abstract Provides a simple memory descriptor that allocates its own buffer memory.
   46 */
   47 
   48 class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
   49 {
   50     OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
   51 
   52 private:
   53 /*! @struct ExpansionData
   54     @discussion This structure will be used to expand the capablilties of this class in the future.
   55     */    
   56     struct ExpansionData {
   57         IOMemoryMap *   map;
   58     };
   59 
   60 /*! @var reserved
   61     Reserved for future use.  (Internal use only)  */
   62     ExpansionData * reserved;
   63 
   64 protected:
   65     void *               _buffer;
   66     vm_size_t            _capacity;
   67     vm_offset_t          _alignment;
   68     IOOptionBits         _options;
   69     IOPhysicalAddress *  _physAddrs;
   70     unsigned             _physSegCount;
   71 
   72 private:
   73     virtual bool initWithOptions(
   74                                IOOptionBits options,
   75                                vm_size_t    capacity,
   76                                vm_offset_t  alignment,
   77                                task_t       inTask);
   78 
   79     virtual bool initWithPhysicalMask(
   80                                 task_t            inTask,
   81                                 IOOptionBits      options,
   82                                 mach_vm_size_t    capacity,
   83                                 mach_vm_address_t alignment,
   84                                 mach_vm_address_t physicalMask);
   85 
   86     OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);
   87     OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1);
   88     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);
   89     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);
   90     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);
   91     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5);
   92     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6);
   93     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7);
   94     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8);
   95     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9);
   96     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10);
   97     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11);
   98     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12);
   99     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13);
  100     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14);
  101     OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15);
  102 
  103 protected:
  104     virtual void free();
  105 
  106     virtual bool initWithAddress( void *      address,       /* not supported */
  107                                   IOByteCount withLength,
  108                                   IODirection withDirection );
  109 
  110     virtual bool initWithAddress( vm_address_t address,      /* not supported */
  111                                   IOByteCount  withLength,
  112                                   IODirection  withDirection,
  113                                   task_t       withTask );
  114 
  115     virtual bool initWithPhysicalAddress( 
  116                                   IOPhysicalAddress address, /* not supported */
  117                                   IOByteCount       withLength,
  118                                   IODirection       withDirection );
  119 
  120     virtual bool initWithPhysicalRanges( 
  121                                   IOPhysicalRange * ranges,  /* not supported */
  122                                   UInt32            withCount,
  123                                   IODirection       withDirection,
  124                                   bool              asReference = false );
  125 
  126     virtual bool initWithRanges(  IOVirtualRange * ranges,   /* not supported */
  127                                   UInt32           withCount,
  128                                   IODirection      withDirection,
  129                                   task_t           withTask,
  130                                   bool             asReference = false );
  131 
  132     IOGeneralMemoryDescriptor::withAddress;                  /* not supported */
  133     IOGeneralMemoryDescriptor::withPhysicalAddress;          /* not supported */
  134     IOGeneralMemoryDescriptor::withPhysicalRanges;           /* not supported */
  135     IOGeneralMemoryDescriptor::withRanges;                   /* not supported */
  136     IOGeneralMemoryDescriptor::withSubRange;                 /* not supported */
  137 
  138 public:
  139 
  140     /*
  141      * withOptions:
  142      *
  143      * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
  144      * hold capacity bytes.  The descriptor's length is initially set to the
  145      * capacity.
  146      */
  147     virtual bool initWithOptions(   IOOptionBits options,
  148                                     vm_size_t    capacity,
  149                                     vm_offset_t  alignment);
  150 
  151     static IOBufferMemoryDescriptor * withOptions(  IOOptionBits options,
  152                                                     vm_size_t    capacity,
  153                                                     vm_offset_t  alignment = 1);
  154 
  155 /*! @function inTaskWithOptions
  156     @abstract Creates a memory buffer with memory descriptor for that buffer. 
  157     @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.
  158     @param inTask The task the buffer will be allocated in.
  159     @param options Options for the allocation:<br>
  160     kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
  161     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>
  162     kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br>
  163     kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br>
  164     kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
  165     @param capacity The number of bytes to allocate.
  166     @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.
  167     @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */
  168 
  169     static IOBufferMemoryDescriptor * inTaskWithOptions(
  170                                             task_t       inTask,
  171                                             IOOptionBits options,
  172                                             vm_size_t    capacity,
  173                                             vm_offset_t  alignment = 1);
  174 
  175 /*! @function inTaskWithPhysicalMask
  176     @abstract Creates a memory buffer with memory descriptor for that buffer. 
  177     @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.
  178     @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).
  179     @param options Options for the allocation:<br>
  180     kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
  181     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>
  182     kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
  183     @param capacity The number of bytes to allocate.
  184     @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.
  185     @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */
  186 
  187     static IOBufferMemoryDescriptor * inTaskWithPhysicalMask(
  188                                             task_t            inTask,
  189                                             IOOptionBits      options,
  190                                             mach_vm_size_t    capacity,
  191                                             mach_vm_address_t physicalMask);
  192 
  193     /*
  194      * withCapacity:
  195      *
  196      * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
  197      * hold capacity bytes.  The descriptor's length is initially set to the
  198      * capacity.
  199      */
  200     static IOBufferMemoryDescriptor * withCapacity(
  201                                      vm_size_t    capacity,
  202                                      IODirection  withDirection,
  203                                      bool         withContiguousMemory = false);
  204     /*
  205      * initWithBytes:
  206      *
  207      * Initialize a new IOBufferMemoryDescriptor preloaded with bytes (copied).
  208      * The descriptor's length and capacity are set to the input buffer's size.
  209      */
  210     virtual bool initWithBytes(const void * bytes,
  211                                vm_size_t    withLength,
  212                                IODirection  withDirection,
  213                                bool         withContiguousMemory = false);
  214 
  215     /*
  216      * withBytes:
  217      *
  218      * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).
  219      * The descriptor's length and capacity are set to the input buffer's size.
  220      */
  221     static IOBufferMemoryDescriptor * withBytes(
  222                                      const void * bytes,
  223                                      vm_size_t    withLength,
  224                                      IODirection  withDirection,
  225                                      bool         withContiguousMemory = false);
  226 
  227     /*
  228      * setLength:
  229      *
  230      * Change the buffer length of the memory descriptor.  When a new buffer
  231      * is created, the initial length of the buffer is set to be the same as
  232      * the capacity.  The length can be adjusted via setLength for a shorter
  233      * transfer (there is no need to create more buffer descriptors when you
  234      * can reuse an existing one, even for different transfer sizes).   Note
  235      * that the specified length must not exceed the capacity of the buffer.
  236      */
  237     virtual void setLength(vm_size_t length);
  238 
  239     /*
  240      * setDirection:
  241      *
  242      * Change the direction of the transfer.  This method allows one to redirect
  243      * the descriptor's transfer direction.  This eliminates the need to destroy
  244      * and create new buffers when different transfer directions are needed.
  245      */
  246     virtual void setDirection(IODirection direction);
  247 
  248     /*
  249      * getCapacity:
  250      *
  251      * Get the buffer capacity
  252      */
  253     virtual vm_size_t getCapacity() const;
  254 
  255     /*
  256      * getBytesNoCopy:
  257      *
  258      * Return the virtual address of the beginning of the buffer
  259      */
  260     virtual void *getBytesNoCopy();
  261 
  262     /*
  263      * getBytesNoCopy:
  264      *
  265      * Return the virtual address of an offset from the beginning of the buffer
  266      */
  267     virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);
  268 
  269     /*
  270      * appendBytes:
  271      *
  272      * Add some data to the end of the buffer.  This method automatically
  273      * maintains the memory descriptor buffer length.  Note that appendBytes
  274      * will not copy past the end of the memory descriptor's current capacity.
  275      */
  276     virtual bool appendBytes(const void *bytes, vm_size_t withLength);
  277 
  278     /* DEPRECATED */ virtual void * getVirtualSegment(IOByteCount offset,
  279     /* DEPRECATED */                                    IOByteCount * length);
  280 };
  281 
  282 #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */

Cache object: 6e32d38e0d32f78e3e56d049e80469ad


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.