/* * Copyright (c) 1998-2008 Apple Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * The contents of this file constitute Original Code as defined in and * are subject to the Apple Public Source License Version 1.1 (the * "License"). You may not use this file except in compliance with the * License. Please obtain a copy of the License at * http://www.apple.com/publicsource and read it before using this file. * * This Original Code and all software distributed under the License are * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the * License for the specific language governing rights and limitations * under the License. * * @APPLE_LICENSE_HEADER_END@ */ #ifndef _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H #define _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H #include <IOKit/IOMemoryCursor.h> /*! @class IOMbufMemoryCursor @abstract A mechanism to convert mbuf chains to physical addresses. @discussion The IOMbufMemoryCursor defines the super class that all specific mbuf cursors must inherit from, but a mbuf cursor can be created without a specific formal subclass by just providing a segment function to the initializers. This class performs the task of walking a given mbuf chain and creating a physical scatter/gather list appropriate for the target hardware. When necessary, this class may also coalesce mbuf chains when the generated scatter/gather list exceeds the specified hardware limit. However, this should be avoided since it exacts a performance cost. <br><br> A driver is expected to create a mbuf cursor and configure it to match the limitations of it's DMA hardware; for instance the mbuf cursor used by an Ethernet controller driver may have a maximum physical segment size of 1520, and allow for up to 6 physical segments. Thus it would create a mbuf cursor with a maxSegmentSize of 1520 and a maxNumSegments of 6. The driver may choose to supply an OutputSegmentFunc function to format the output of each scatter/gather segment to match the hardware descriptor format, or it may use a subclass of IOMbufMemoryCursor to generate IOPhysicalSegment segments with various byte orders. <br><br> A driver may also create more than one mbuf cursor, perhaps one dedicated for the transmit thread, and the other for the receive thread. This becomes a requirement when the driver is multi-threaded, since the mbuf cursor maintains state and does not support reentrancy. */ class IOMbufMemoryCursor : public IOMemoryCursor { OSDeclareDefaultStructors(IOMbufMemoryCursor) protected: UInt32 maxNumSegments; UInt32 coalesceCount; UInt32 packetTooBigErrors; struct ExpansionData { }; /*! @var reserved Reserved for future use. (Internal use only) */ ExpansionData *reserved; virtual bool initWithSpecification(OutputSegmentFunc outSeg, UInt32 maxSegmentSize, UInt32 maxTransferSize, UInt32 align); public: /*! @function initWithSpecification @abstract Primary initializer for the IOMbufMemoryCursor class. @param outSeg Function to call to output one physical segment. @param maxSegmentSize Maximum allowable size for one segment. @param maxNumSegments Maximum number of segments. @result Returns true if the inherited classes and this instance initialized successfully. */ virtual bool initWithSpecification(OutputSegmentFunc outSeg, UInt32 maxSegmentSize, UInt32 maxNumSegments); /*! @function genPhysicalSegments @abstract Generates a physical scatter/gather list given a mbuf packet. @discussion Generates a list of physical segments from the given mbuf. @param packet The mbuf packet. @param vector Void pointer to base of output physical scatter/gather list. Always passed directly onto the OutputSegmentFunc without interpretation by the cursor. @param maxSegs Maximum number of segments that can be written to segments array. @param doCoalesce Set to true to perform coalescing when the required number of segments exceeds the specified limit, otherwise abort and return 0. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ virtual UInt32 genPhysicalSegments(mbuf_t packet, void * vector, UInt32 maxSegs, bool doCoalesce); /*! @function getAndResetCoalesceCount @abstract Returns a count of the total number of mbuf chains coalesced by genPhysicalSegments(). @discussion This method returns a count of the total number of mbuf chains coalesced by genPhysicalSegments(). The counter is then reset to 0. @result Returns the coalesce count. */ UInt32 getAndResetCoalesceCount(); // Virtual function padding OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 0); OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 1); OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 2); OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 3); }; /*! @class IOMbufNaturalMemoryCursor @abstract An IOMbufMemoryCursor subclass that outputs a vector of IOPhysicalSegments in the natural byte orientation for the cpu. @discussion The IOMbufNaturalMemoryCursor would be used when it is too difficult to implement an OutputSegmentFunc that is more appropriate for your hardware. This cursor just outputs an array of IOPhysicalSegments. */ class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor { OSDeclareDefaultStructors(IOMbufNaturalMemoryCursor) public: /*! @function withSpecification @abstract Factory function that creates and initializes an IOMbufNaturalMemoryCursor in one operation. @discussion See also IOMbufMemoryCursor::initWithSpecification. @param maxSegmentSize Maximum allowable size for one segment. @param maxNumSegments Maximum number of segments. @result Returns a new mbuf cursor if successfully created and initialized, 0 otherwise. */ static IOMbufNaturalMemoryCursor * withSpecification(UInt32 maxSegmentSize, UInt32 maxNumSegments); /*! @function getPhysicalSegments @abstract Generates a cpu natural physical scatter/gather list from a given mbuf. @param packet The mbuf packet. @param vector Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list. @param numVectorSegments Maximum number of IOPhysicalSegments accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegments(mbuf_t packet, struct IOPhysicalSegment * vector, UInt32 numVectorSegments = 0); /*! @function getPhysicalSegmentsWithCoalesce @abstract Generates a cpu natural physical scatter/gather list from a given mbuf. @discussion Generate a cpu natural physical scatter/gather list from a given mbuf. Coalesce mbuf chain when the number of segments in the scatter/gather list exceeds numVectorSegments. @param packet The mbuf packet. @param vector Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list. @param numVectorSegments Maximum number of IOPhysicalSegments accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet, struct IOPhysicalSegment * vector, UInt32 numVectorSegments = 0); }; //=========================================================================== //=========================================================================== /*! @class IOMbufBigMemoryCursor @abstract An IOMbufMemoryCursor subclass that outputs a vector of IOPhysicalSegments in the big endian byte order. @discussion The IOMbufBigMemoryCursor would be used when the DMA hardware requires a big endian address and length pair. This cursor outputs an array of IOPhysicalSegments that are encoded in big-endian format. */ class IOMbufBigMemoryCursor : public IOMbufMemoryCursor { OSDeclareDefaultStructors(IOMbufBigMemoryCursor) public: /*! @function withSpecification @abstract Factory function that creates and initializes an IOMbufBigMemoryCursor in one operation. @discussion See also IOMbufMemoryCursor::initWithSpecification. @param maxSegmentSize Maximum allowable size for one segment. @param maxNumSegments Maximum number of segments. @result Returns a new mbuf cursor if successfully created and initialized, 0 otherwise. */ static IOMbufBigMemoryCursor * withSpecification(UInt32 maxSegmentSize, UInt32 maxNumSegments); /*! @function getPhysicalSegments @abstract Generates a big endian physical scatter/gather list from a given mbuf. @param packet The mbuf packet. @param vector Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list. @param numVectorSegments Maximum number of IOPhysicalSegments accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegments(mbuf_t packet, struct IOPhysicalSegment * vector, UInt32 numVectorSegments = 0); /*! @function getPhysicalSegmentsWithCoalesce @abstract Generates a big endian physical scatter/gather list from a given mbuf. @discussion Generate a big endian physical scatter/gather list from a given mbuf. Coalesce mbuf chain when the number of segments in the scatter/gather list exceeds numVectorSegments. @param packet The mbuf packet. @param vector Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list. @param numVectorSegments Maximum number of IOPhysicalSegments accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet, struct IOPhysicalSegment * vector, UInt32 numVectorSegments = 0); }; //=========================================================================== //=========================================================================== /*! @class IOMbufLittleMemoryCursor @abstract An IOMbufMemoryCursor subclass that outputs a vector of IOPhysicalSegments in the little endian byte order. @discussion The IOMbufLittleMemoryCursor would be used when the DMA hardware requires a little endian address and length pair. This cursor outputs an array of IOPhysicalSegments that are encoded in little endian format. */ class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor { OSDeclareDefaultStructors(IOMbufLittleMemoryCursor) public: /*! @function withSpecification @abstract Factory function that creates and initializes an IOMbufLittleMemoryCursor in one operation. @discussion See also IOMbufMemoryCursor::initWithSpecification. @param maxSegmentSize Maximum allowable size for one segment. @param maxNumSegments Maximum number of segments. @result Returns a new mbuf cursor if successfully created and initialized, 0 otherwise. */ static IOMbufLittleMemoryCursor * withSpecification(UInt32 maxSegmentSize, UInt32 maxNumSegments); /*! @function getPhysicalSegments @abstract Generates a little endian physical scatter/gather list from a given mbuf. @param packet The mbuf packet. @param vector Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list. @param numVectorSegments Maximum number of IOPhysicalSegments accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegments(mbuf_t packet, struct IOPhysicalSegment * vector, UInt32 numVectorSegments = 0); /*! @function getPhysicalSegmentsWithCoalesce @abstract Generates a little endian physical scatter/gather list from a given mbuf. @discussion Generate a little endian physical scatter/gather list from a given mbuf. Coalesce mbuf chain when the number of segments in the scatter/gather list exceeds numVectorSegments. @param packet The mbuf packet. @param vector Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list. @param numVectorSegments Maximum number of IOPhysicalSegments accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet, struct IOPhysicalSegment * vector, UInt32 numVectorSegments = 0); }; #ifdef __ppc__ struct IODBDMADescriptor; //=========================================================================== //=========================================================================== /*! @class IOMbufDBDMAMemoryCursor @abstract An IOMbufMemoryCursor subclass that outputs a vector of IODBDMADescriptors. */ class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor { OSDeclareDefaultStructors(IOMbufDBDMAMemoryCursor) public: /*! @function withSpecification @abstract Factory function that creates and initializes an IOMbufDBDMAMemoryCursor in one operation. @discussion See also IOMbufMemoryCursor::initWithSpecification. @param maxSegmentSize Maximum allowable size for one segment. @param maxNumSegments Maximum number of segments. @result Returns a new mbuf cursor if successfully created and initialized, 0 otherwise. */ static IOMbufDBDMAMemoryCursor * withSpecification(UInt32 maxSegmentSize, UInt32 maxNumSegments); /*! @function getPhysicalSegments @abstract Generates a DBDMA descriptor list from a given mbuf. @param packet The mbuf packet. @param vector Pointer to an array of IODBDMADescriptor for the output list. @param numVectorSegments Maximum number of IODBDMADescriptors accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegments(mbuf_t packet, struct IODBDMADescriptor *vector, UInt32 numVectorSegments = 0); /*! @function getPhysicalSegmentsWithCoalesce @abstract Generates a DBDMA descriptor list from a given mbuf. @discussion Generate a DBDMA descriptor list from a given mbuf. Coalesce mbuf chain when the number of elements in the list exceeds numVectorSegments. @param packet The mbuf packet. @param vector Pointer to an array of IODBDMADescriptor for the output list. @param numVectorSegments Maximum number of IODBDMADescriptors accepted. @result Returns the number of segments that were filled in, or 0 if an error occurred. */ UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet, struct IODBDMADescriptor * vector, UInt32 numVectorSegments = 0); }; #endif /* __ppc__ */ #endif /* !_IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H */