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