- @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>
- 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.
- @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);
-
- /*
- * withCapacity:
- *
- * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
- * hold capacity bytes. The descriptor's length is initially set to the
- * capacity.
- */
- static IOBufferMemoryDescriptor * withCapacity(
- 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.
- */
- virtual bool initWithBytes(const void * bytes,
- vm_size_t withLength,
- IODirection withDirection,
- bool withContiguousMemory = false);
-
- /*
- * withBytes:
- *
- * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).
- * The descriptor's length and capacity are set to the input buffer's size.
- */
- static IOBufferMemoryDescriptor * withBytes(
- const void * bytes,
- vm_size_t withLength,
- IODirection withDirection,
- bool withContiguousMemory = false);
-
- /*
- * setLength:
- *
- * Change the buffer length of the memory descriptor. When a new buffer
- * is created, the initial length of the buffer is set to be the same as
- * the capacity. The length can be adjusted via setLength for a shorter
- * transfer (there is no need to create more buffer descriptors when you
- * can reuse an existing one, even for different transfer sizes). Note
- * that the specified length must not exceed the capacity of the buffer.
- */
- virtual void setLength(vm_size_t length);
-
- /*
- * setDirection:
- *
- * Change the direction of the transfer. This method allows one to redirect
- * the descriptor's transfer direction. This eliminates the need to destroy
- * and create new buffers when different transfer directions are needed.
- */
- virtual void setDirection(IODirection direction);
-
- /*
- * getCapacity:
- *
- * Get the buffer capacity
- */
- virtual vm_size_t getCapacity() const;
-
- /*
- * getBytesNoCopy:
- *
- * Return the virtual address of the beginning of the buffer
- */
- virtual void *getBytesNoCopy();
-
- /*
- * getBytesNoCopy:
- *
- * Return the virtual address of an offset from the beginning of the buffer
- */
- virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);
-
- /*
- * appendBytes:
- *
- * Add some data to the end of the buffer. This method automatically
- * maintains the memory descriptor buffer length. Note that appendBytes
- * will not copy past the end of the memory descriptor's current capacity.
- */
- virtual bool appendBytes(const void *bytes, vm_size_t withLength);
+ * @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 OSPtr<IOBufferMemoryDescriptor> inTaskWithOptions(
+ task_t inTask,
+ 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.
+ * @param kernTag The kernel memory tag
+ * @param userTag The user memory tag
+ * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */
+
+ static OSPtr<IOBufferMemoryDescriptor> inTaskWithOptions(
+ task_t inTask,
+ IOOptionBits options,
+ vm_size_t capacity,
+ vm_offset_t alignment,
+ uint32_t kernTag,
+ uint32_t userTag);
+
+/*! @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 physicalMask 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 OSPtr<IOBufferMemoryDescriptor> inTaskWithPhysicalMask(
+ task_t inTask,
+ IOOptionBits options,
+ mach_vm_size_t capacity,
+ mach_vm_address_t physicalMask);
+
+/*
+ * withCapacity:
+ *
+ * Returns a new IOBufferMemoryDescriptor with a buffer large enough to
+ * hold capacity bytes. The descriptor's length is initially set to the
+ * capacity.
+ */
+ static OSPtr<IOBufferMemoryDescriptor> withCapacity(
+ vm_size_t capacity,
+ IODirection withDirection,
+ bool withContiguousMemory = false);
+#ifndef __LP64__
+ virtual bool initWithBytes(const void * bytes,
+ vm_size_t withLength,
+ IODirection withDirection,
+ bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */
+#endif /* !__LP64__ */
+
+/*
+ * withBytes:
+ *
+ * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).
+ * The descriptor's length and capacity are set to the input buffer's size.
+ */
+ static OSPtr<IOBufferMemoryDescriptor> withBytes(
+ const void * bytes,
+ vm_size_t withLength,
+ IODirection withDirection,
+ bool withContiguousMemory = false);
+
+/*
+ * setLength:
+ *
+ * Change the buffer length of the memory descriptor. When a new buffer
+ * is created, the initial length of the buffer is set to be the same as
+ * the capacity. The length can be adjusted via setLength for a shorter
+ * transfer (there is no need to create more buffer descriptors when you
+ * can reuse an existing one, even for different transfer sizes). Note
+ * that the specified length must not exceed the capacity of the buffer.
+ */
+ virtual void setLength(vm_size_t length);
+
+/*
+ * setDirection:
+ *
+ * Change the direction of the transfer. This method allows one to redirect
+ * the descriptor's transfer direction. This eliminates the need to destroy
+ * and create new buffers when different transfer directions are needed.
+ */
+ virtual void setDirection(IODirection direction);
+
+/*
+ * getCapacity:
+ *
+ * Get the buffer capacity
+ */
+ virtual vm_size_t getCapacity() const;
+
+/*
+ * getBytesNoCopy:
+ *
+ * Return the virtual address of the beginning of the buffer
+ */
+ virtual void *getBytesNoCopy();
+
+/*
+ * getBytesNoCopy:
+ *
+ * Return the virtual address of an offset from the beginning of the buffer
+ */
+ virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);
+
+/*
+ * appendBytes:
+ *
+ * Add some data to the end of the buffer. This method automatically
+ * maintains the memory descriptor buffer length. Note that appendBytes
+ * will not copy past the end of the memory descriptor's current capacity.
+ */
+ virtual bool appendBytes(const void *bytes, vm_size_t withLength);
+
+#ifndef __LP64__
+ virtual void * getVirtualSegment(IOByteCount offset,
+ IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */
+#endif /* !__LP64__ */
projects / apple / xnu.git / blobdiff