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

---

IOMemoryCursor

Overview

A mechanism to convert memory references to physical addresses.

Discussion

IOMemoryCursor declares the super class that all specific memory cursors must inherit from, but a memory cursor can be created without a specific format subclass by just providing a segment function to the initializers. This class does the difficult stuff of dividing a memory descriptor into a physical scatter/gather list appropriate for the target hardware.

A driver is expected to create a memory cursor and configure it to the limitations of its DMA hardware; for instance the memory cursor used by the FireWire SBP-2 protocol has a maximum physical segment size of 2^16 - 1 but the actual transfer size is unlimited. Thus it would create a cursor with a maxSegmentSize of 65535 and a maxTransfer size of UINT_MAX. It would also provide a SegmentFunction that can output a pagelist entry.

Below is the simplest example of a SegmentFunction:

void IONaturalMemoryCursor::outputSegment(PhysicalSegment segment,
					  void *	  outSegments,
					  UInt32	  outSegmentIndex)
{
    ((PhysicalSegment *) outSegments)[outSegmentIndex] = segment;
}

---

Functions

genPhysicalSegments

Generates a physical scatter/gather list given a memory descriptor.

initWithSpecification

Primary initializer for the IOMemoryCursor class.

withSpecification

Creates and initializes an IOMemoryCursor in one operation.

---

genPhysicalSegments

---

Generates a physical scatter/gather list given a memory descriptor.

public

virtual UInt32 genPhysicalSegments( 
    IOMemoryDescriptor *descriptor, 
    IOByteCount fromPosition, 
    void *segments, 
    UInt32 maxSegments, 
    UInt32 maxTransferSize = 0, 
    IOByteCount *transferSize = 0); 

Parameters

descriptor

IOMemoryDescriptor that describes the data associated with an I/O request.

fromPosition

Starting location of the I/O within a memory descriptor.

segments

Void pointer to base of output physical scatter/gather list. Always passed directly onto the SegmentFunction without interpretation by the cursor.

maxSegments

Maximum number of segments that can be written to segments array.

maxTransferSize

Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.

transferSize

Pointer to an IOByteCount variable that can contain the total size of the transfer being described. Defaults to 0 indicating that no transfer size need be returned.

Return Value

If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.

Discussion

Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.

---

initWithSpecification

---

Primary initializer for the IOMemoryCursor class.

public

virtual bool initWithSpecification(
    SegmentFunction outSegFunc, 
    IOPhysicalLength maxSegmentSize = 0, 
    IOPhysicalLength maxTransferSize = 0, 
    IOPhysicalLength alignment = 1); 

Parameters

outSegFunc

SegmentFunction to call to output one physical segment.

maxSegmentSize

Maximum allowable size for one segment. Defaults to 0.

maxTransferSize

Maximum size of an entire transfer. Defaults to 0 indicating no maximum.

alignment

Alignment restrictions on output physical addresses. Not currently implemented. Defaults to single byte alignment.

Return Value

Returns true if the inherited classes and this instance initialize successfully.

---

withSpecification

---

Creates and initializes an IOMemoryCursor in one operation.

public

static IOMemoryCursor * withSpecification(
    SegmentFunction outSegFunc, 
    IOPhysicalLength maxSegmentSize = 0, 
    IOPhysicalLength maxTransferSize = 0, 
    IOPhysicalLength alignment = 1); 

Parameters

outSegFunc

SegmentFunction to call to output one physical segment.

maxSegmentSize

Maximum allowable size for one segment. Defaults to 0.

maxTransferSize

Maximum size of an entire transfer. Defaults to 0 indicating no maximum.

alignment

Alignment restrictions on output physical addresses. Not currently implemented. Defaults to single byte alignment.

Return Value

Returns a new memory cursor if successfully created and initialized, 0 otherwise.

Discussion

Factory function to create and initialize an IOMemoryCursor in one operation. For more information, see initWithSpecification.

Typedefs

---

SegmentFunction

---

public

typedef void ( *SegmentFunction)(
    PhysicalSegment segment, 
    void *segments, 
    UInt32 segmentIndex); 

Fields

segment

The physical address and length that is next to be output.

segments

Base of the output vector of DMA address length pairs.

segmentIndex

Index to output 'segment' in the 'segments' array.

Discussion

Pointer to a C function that outputs a single physical segment to an element in the array as defined by the segments and segmentIndex parameters.

Structs and Unions

---

PhysicalSegment

---

public

struct PhysicalSegment { 
    IOPhysicalAddress location; 
    IOPhysicalLength length; 
}; 

Discussion

A physical address/length pair.

Member Data

---

alignMask

---

protected

IOPhysicalLength alignMask; 

Discussion

Currently unused. Reserved for automated aligment restriction code.

---

maxSegmentSize

---

protected

IOPhysicalLength maxSegmentSize; 

Discussion

Maximum size of one segment in a scatter/gather list.

---

maxTransferSize

---

protected

IOPhysicalLength maxTransferSize; 

Discussion

Maximum size of a transfer that this memory cursor is allowed to generate.

---

outSeg

---

protected

SegmentFunction outSeg; 

Discussion

The action method called when an event has been delivered.

#defines

---

IOPhysicalSegment

---

#define IOPhysicalSegment IOMemoryCursor::PhysicalSegment 

Discussion

Backward compatibility define for the old non-class scoped type definition. See PhysicalSegment.

---

OutputSegmentFunc

---

#define OutputSegmentFunc IOMemoryCursor::SegmentFunction 

Discussion

Backward compatibility define for the old non-class scoped type definition. See SegmentFunction.

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