ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOBufferMemoryDescriptor

Inherits from:	IOGeneralMemoryDescriptor
Declared In:	IOBufferMemoryDescriptor.h

Overview

Provides a simple memory descriptor that allocates its own buffer memory.

Discussion

Beginning in Mac OS X v10.2, IOBufferMemoryDescriptor allows a buffer to be allocated in any task for I/O or sharing through mapping. In particular, it is recommended that you use the IOBufferMemoryDescriptor functions to allocate buffers for use with I/O requested by non-kernel clients. In this way, the kernel controls the allocation method, which ensures that the buffer is allocated in accordance with internal guidelines dictated by the virtual memory system.

For software running in Mac OS X v10.2 and later, Apple recommends that

User tasks do not use malloc or other user-level library functions to allocate I/O buffers in their own address space.
User clients use IOBufferMemoryDescriptor objects to represent kernel-allocated buffer instead of the IOMemoryDescriptor objects that represented user task-allocated buffers.

Functions

appendBytes: Copies the specified data to the end of the buffer.
getBytesNoCopy(): Gets the virtual address of the beginning of the buffer.
getBytesNoCopy(vm_size_t, vm_size_t): Gets the virtual address of an offset from the beginning of the buffer and with the specified length.
getCapacity: Gets the memory descriptor's capacity.
initWithBytes: Initializes a memory descriptor with the provided bytes.
initWithOptions: Initializes a memory descriptor with the specified options.
inTaskWithOptions: Creates a memory buffer with memory descriptor for that buffer.
inTaskWithPhysicalMask: Creates a memory buffer with memory descriptor for that buffer.
setDirection: Changes the transfer direction of the memory descriptor.
setLength: Changes the buffer length of the memory descriptor.
withBytes: Creates a memory descriptor preloaded (copied) with the provided bytes.
withCapacity: Creates a memory descriptor with a buffer of the specified size.
withOptions: Creates a memory descriptor with the specified options and with a buffer of the specified size.

appendBytes

Copies the specified data to the end of the buffer.

public

virtual bool appendBytes(
    const void *bytes,
    vm_size_t withLength);

Parameters

bytes: The data to copy.
withLength: The size of the data to copy, in bytes.

Return Value

true if the copy was successful; false if the buffer's current length is not valid.

Discussion

This function automatically maintains the memory descriptor buffer length. Note that appendBytes will not copy past the end of the memory descriptor's current capacity.

getBytesNoCopy()

Gets the virtual address of the beginning of the buffer.

public

virtual void *getBytesNoCopy();

Return Value

The virtual address of the beginning of the buffer.

getBytesNoCopy(vm_size_t, vm_size_t)

Gets the virtual address of an offset from the beginning of the buffer and with the specified length.

public

virtual void *getBytesNoCopy(
    vm_size_t start,
    vm_size_t withLength);

Parameters

start: The offset into the buffer.
withLength: The length of the data.

Return Value

The virtual address of the specified offset from the beginning of the buffer or 0 if the offset or length are not valid.

Discussion

This function will fail if the offset is equal to or greater than the current length of the buffer or if the range represented by the offset plus the specified length is greater than the current length of the buffer.

getCapacity

Gets the memory descriptor's capacity.

public

virtual vm_size_t getCapacity() const;

Return Value

The size of the memory descriptor's capacity, in bytes.

initWithBytes

Initializes a memory descriptor with the provided bytes.

public

virtual bool initWithBytes(
    const void * bytes, 
    vm_size_t withLength, 
    IODirection withDirection, 
    bool withContiguousMemory = false);

Parameters

bytes: The data to copy into the buffer.
withLength: The size of the data to copy into the buffer, in bytes.
withDirection: An I/O direction to be associated with the descriptor, which may affect the operation of the IOMemoryDescriptor::prepare and IOMemoryDescriptor::complete methods on some architectures.
withContiguousMemory: If true, the buffer is initialized with a minimum required alignment of the buffer taken from the value of the capacity parameter; if false, the buffer is initialized with no required alignment.

Return Value

true if the initialization was successful; false otherwise.

initWithOptions

Initializes a memory descriptor with the specified options.

public

virtual bool initWithOptions(
    IOOptionBits options, 
    vm_size_t capacity, 
    vm_offset_t alignment);

Parameters

options: See inTaskWithOptions for possible values.
capacity: The number of bytes to allocate.
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.

Return Value

true if the initialization was successful; false otherwise.

inTaskWithOptions

Creates a memory buffer with memory descriptor for that buffer.

public

static IOBufferMemoryDescriptor * inTaskWithOptions( 
    task_t inTask, 
    IOOptionBits options, 
    vm_size_t capacity, 
    vm_offset_t alignment = 1);

Parameters

inTask

The task the buffer will be allocated in.

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.

capacity

The number of bytes to allocate.

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.

Return Value

An instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory descriptor and associated buffer.

Discussion

This function allocates a memory buffer with a given size and alignment in the task's specified address space, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created using IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated. For example, pageability 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.

Availability: Mac OS X v10.2 and above

inTaskWithPhysicalMask

Creates a memory buffer with memory descriptor for that buffer.

public

static IOBufferMemoryDescriptor * inTaskWithPhysicalMask( 
    task_t inTask, 
    IOOptionBits options, 
    mach_vm_size_t capacity, 
    mach_vm_address_t physicalMask);

Parameters

inTask

The task the buffer will be mapped in. Pass NULL to create memory unmapped in any task (for example, for use as a DMA buffer).

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.

capacity

The number of bytes to allocate.

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.

Return Value

An instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer.

Discussion

This method allocates a memory buffer with a given size and alignment in the task's specified address space, 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. For example, 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.

Availability: Available on PowerPC-based Macs running Mac OS X Server only and on all Intel-based Macs running Mac OS X 10.4.8 and above.

setDirection

Changes the transfer direction of the memory descriptor.

public

virtual void setDirection(
    IODirection direction);

Parameters

direction: The new I/O direction to set the descriptor's transfer direction to.

Discussion

This function allows you to redirect the descriptor's transfer direction. This eliminates the need to destroy and create new buffers when different transfer directions are needed.

setLength

Changes the buffer length of the memory descriptor.

public

virtual void setLength(
    vm_size_t length);

Parameters

length: The new length to set the buffer length to.

Discussion

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 with this function 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.

withBytes

Creates a memory descriptor preloaded (copied) with the provided bytes.

public

static IOBufferMemoryDescriptor * withBytes( 
    const void * bytes, 
    vm_size_t withLength, 
    IODirection withDirection, 
    bool withContiguousMemory = false);

Parameters

bytes: The data to copy into the buffer.
withLength: The size of the data to copy into the buffer, in bytes.
withDirection: An I/O direction to be associated with the descriptor, which may affect the operation of the IOMemoryDescriptor::prepare and IOMemoryDescriptor::complete methods on some architectures.
withContiguousMemory: If true, the buffer is initialized with a minimum required alignment of the buffer taken from the value of the capacity parameter; if false, the buffer is initialized with no required alignment.

Return Value

An instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory descriptor and associated buffer.

Discussion

The descriptor's length and capacity are set to the input buffer's size.

withCapacity

Creates a memory descriptor with a buffer of the specified size.

public

static IOBufferMemoryDescriptor * withCapacity( 
    vm_size_t capacity, 
    IODirection withDirection, 
    bool withContiguousMemory = false);

Parameters

capacity: The number of bytes to allocate.
withDirection: An I/O direction to be associated with the descriptor, which may affect the operation of the IOMemoryDescriptor::prepare and IOMemoryDescriptor::complete methods on some architectures.
withContiguousMemory: If true, the buffer is created with a minimum required alignment of the buffer taken from the value of the capacity parameter; if false, the buffer is created with no required alignment.

Return Value

An instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory descriptor and associated buffer.

Discussion

The descriptor's length is initially set to the size specified in capacity.

withOptions

Creates a memory descriptor with the specified options and with a buffer of the specified size.

public

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

Parameters

options: See inTaskWithOptions for possible values.
capacity: The number of bytes to allocate.
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.

Return Value

An instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory descriptor and associated buffer.

Discussion

The descriptor's length is initially set to the size specified in capacity.

Structs and Unions

ExpansionData

private

struct ExpansionData { 
    IOMemoryMap *map; 
};

Discussion

This structure will be used to expand the capabilities of this class in the future.

Member Data

reserved

private

ExpansionData * reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19