Return to IOMBufMemoryCursor.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / network

Annotation of XNU/iokit/IOKit/network/IOMBufMemoryCursor.h, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
        !             3:  *
        !             4:  * @APPLE_LICENSE_HEADER_START@
        !             5:  * 
        !             6:  * The contents of this file constitute Original Code as defined in and
        !             7:  * are subject to the Apple Public Source License Version 1.1 (the
        !             8:  * "License").  You may not use this file except in compliance with the
        !             9:  * License.  Please obtain a copy of the License at
        !            10:  * http://www.apple.com/publicsource and read it before using this file.
        !            11:  * 
        !            12:  * This Original Code and all software distributed under the License are
        !            13:  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
        !            14:  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
        !            15:  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
        !            16:  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
        !            17:  * License for the specific language governing rights and limitations
        !            18:  * under the License.
        !            19:  * 
        !            20:  * @APPLE_LICENSE_HEADER_END@
        !            21:  */
        !            22: /*
        !            23:  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved. 
        !            24:  *
        !            25:  * IOMBufMemoryCursor.h created by gvdl on 1999-1-20
        !            26:  *
        !            27:  */
        !            28: 
        !            29: #ifndef _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H
        !            30: #define _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H
        !            31: 
        !            32: #include <IOKit/IOMemoryCursor.h>
        !            33: 
        !            34: struct mbuf;
        !            35: 
        !            36: /*! @class IOMBufMemoryCursor : public IOMemoryCursor
        !            37:     @abstract A mechanism to convert mbuf chains to physical addresses.
        !            38:     @discussion The IOMBufMemoryCursor defines the super class that all
        !            39:     specific mbuf cursors must inherit from, but a mbuf cursor can be created   
        !            40:     without a specific formal subclass by just providing a segment function to
        !            41:     the initializers. This class performs the task of walking a given
        !            42:     mbuf chain and creating a physical scatter/gather list appropriate for
        !            43:     the target hardware. When necessary, this class may also coalesce
        !            44:     mbuf chains when the generated scatter/gather list exceeds the specified 
        !            45:     hardware limit. However, this should be avoided since it exacts a 
        !            46:     performance cost.
        !            47:     <br><br>
        !            48:     A driver is expected to create a mbuf cursor and configure it to match the
        !            49:     limitations of it's DMA hardware; for instance the mbuf cursor used by
        !            50:     an Ethernet controller driver may have a maximum physical segment size
        !            51:     of 1520, and allow for up to 6 physical segments. Thus it would create a 
        !            52:     mbuf cursor with a maxSegmentSize of 1520 and a maxNumSegments of 6.
        !            53:     The driver may choose to supply an OutputSegmentFunc function to
        !            54:     format the output of each scatter/gather segment to match the
        !            55:     hardware descriptor format, or it may use a subclass of 
        !            56:     IOMBufMemoryCursor to generate IOPhysicalSegment segments with 
        !            57:     various byte orders.
        !            58:     <br><br>
        !            59:     A driver may also create more than one mbuf cursor, perhaps one
        !            60:     dedicated for the transmit thread, and the other for the receive thread.
        !            61:     This becomes a requirement when the driver is multi-threaded, since the 
        !            62:     mbuf cursor maintains state and does not support reentrancy. */
        !            63: 
        !            64: class IOMBufMemoryCursor : public IOMemoryCursor
        !            65: {
        !            66:     OSDeclareAbstractStructors(IOMBufMemoryCursor)
        !            67: 
        !            68: private:
        !            69:     virtual bool initWithSpecification(OutputSegmentFunc outSeg,
        !            70:                                        UInt maxSegmentSize,
        !            71:                                        UInt maxTransferSize,
        !            72:                                        UInt align);
        !            73: 
        !            74: protected:
        !            75:     UInt maxNumSegments;
        !            76:     UInt coalesceCount;
        !            77:     UInt packetTooBigErrors;
        !            78: 
        !            79: /*! @function initWithSpecification
        !            80:     @abstract Primary initializer for the IOMBufMemoryCursor class.
        !            81:     @param outSeg Function to call to output one physical segment.
        !            82:     @param maxSegmentSize Maximum allowable size for one segment.
        !            83:     @param maxNumSegments Maximum number of segments.
        !            84:     @result true if the inherited classes and this instance initialized
        !            85:     successfully. */
        !            86: 
        !            87:     virtual bool initWithSpecification(OutputSegmentFunc outSeg,
        !            88:                                        UInt maxSegmentSize,
        !            89:                                        UInt maxNumSegments);
        !            90: 
        !            91: /*! @function genPhysicalSegments
        !            92:     @abstract Generate a physical scatter/gather list given a mbuf packet.
        !            93:     @discussion Generates a list of physical segments from the given mbuf.
        !            94:     @param packet The mbuf packet.
        !            95:     @param vector Void pointer to base of output physical scatter/gather list.
        !            96:     Always passed directly onto the OutputSegmentFunc without interpretation
        !            97:     by the cursor. 
        !            98:     @param maxSegs Maximum number of segments that can be written to segments
        !            99:     array.
        !           100:     @param doCoalesce Set to true to perform coalescing when the required 
        !           101:     number of segments exceeds the specified limit, otherwise abort and
        !           102:     return 0.
        !           103:     @result The number of segments that were filled in is returned, or
        !           104:     0 if an error occurred. */
        !           105: 
        !           106:     virtual UInt genPhysicalSegments(struct mbuf * packet, void * vector,
        !           107:                                      UInt maxSegs, bool doCoalesce);
        !           108: 
        !           109: public:
        !           110: 
        !           111: /*! @function genPhysicalSegments
        !           112:     @abstract Returns a count of the total number of mbuf chains coalesced
        !           113:     by genPhysicalSegments(). The counter is then reset to 0.
        !           114:     @result The coalesce count. */
        !           115: 
        !           116:     UInt getAndResetCoalesceCount();
        !           117: };
        !           118: 
        !           119: 
        !           120: /*! @class IOMBufNaturalMemoryCursor : public IOMBufMemoryCursor
        !           121:     @abstract A IOMBufMemoryCursor subclass that outputs a vector of
        !           122:     IOPhysicalSegments in the natural byte orientation for the cpu.  
        !           123:     @discussion The IOMBufNaturalMemoryCursor would be used when it is too
        !           124:     difficult to implement an OutputSegmentFunc that is more appropriate for
        !           125:     your hardware.  This cursor just outputs an array of IOPhysicalSegments. */
        !           126: 
        !           127: class IOMBufNaturalMemoryCursor : public IOMBufMemoryCursor
        !           128: {
        !           129:     OSDeclareDefaultStructors(IOMBufNaturalMemoryCursor)
        !           130: 
        !           131: public:
        !           132: 
        !           133: /*! @function withSpecification
        !           134:     @abstract Factory function to create and initialize an 
        !           135:     IOMBufNaturalMemoryCursor in one operation, see
        !           136:     IOMBufMemoryCursor::initWithSpecification.
        !           137:     @param maxSegmentSize Maximum allowable size for one segment.
        !           138:     @param maxNumSegments Maximum number of segments.
        !           139:     @result A new mbuf cursor if successfully created and initialized,
        !           140:     0 otherwise. */
        !           141: 
        !           142:     static IOMBufNaturalMemoryCursor * withSpecification(UInt maxSegmentSize, 
        !           143:                                                          UInt maxNumSegments);
        !           144: 
        !           145: /*! @function getPhysicalSegments
        !           146:     @abstract Generate a cpu natural physical scatter/gather list from a given
        !           147:     mbuf.
        !           148:     @param packet The mbuf packet.
        !           149:     @param vector Pointer to an array of IOPhysicalSegments for the output 
        !           150:     physical scatter/gather list.
        !           151:     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
        !           152:     @result The number of segments that were filled in is returned, or
        !           153:     0 if an error occurred. */
        !           154: 
        !           155:     UInt getPhysicalSegments(struct mbuf * packet,
        !           156:                              struct IOPhysicalSegment * vector,
        !           157:                              UInt numVectorSegments = 0);
        !           158: 
        !           159: /*! @function getPhysicalSegmentsWithCoalesce
        !           160:     @abstract Generate a cpu natural physical scatter/gather list from a given
        !           161:     mbuf.
        !           162:     @discussion Generate a cpu natural physical scatter/gather list from a 
        !           163:     given mbuf. Coalesce mbuf chain when the number of segments in the 
        !           164:     scatter/gather list exceeds numVectorSegments.
        !           165:     @param packet The mbuf packet.
        !           166:     @param vector Pointer to an array of IOPhysicalSegments for the output 
        !           167:     physical scatter/gather list.
        !           168:     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
        !           169:     @result The number of segments that were filled in is returned, or
        !           170:     0 if an error occurred. */
        !           171: 
        !           172:     UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
        !           173:                                          struct IOPhysicalSegment * vector,
        !           174:                                          UInt numVectorSegments = 0);
        !           175: };
        !           176: 
        !           177: //===========================================================================
        !           178: //===========================================================================
        !           179: 
        !           180: /*! @class IOMBufBigMemoryCursor : public IOMBufMemoryCursor
        !           181:     @abstract A IOMBufMemoryCursor subclass that outputs a vector of 
        !           182:     IOPhysicalSegments in the big endian byte order.  
        !           183:     @discussion The IOMBufBigMemoryCursor would be used when the DMA hardware 
        !           184:     requires a big endian address and length pair.  This cursor outputs an 
        !           185:     array of IOPhysicalSegments that are encoded in big-endian format. */
        !           186: 
        !           187: class IOMBufBigMemoryCursor : public IOMBufMemoryCursor
        !           188: {
        !           189:     OSDeclareDefaultStructors(IOMBufBigMemoryCursor)
        !           190: 
        !           191: public:
        !           192: 
        !           193: /*! @function withSpecification
        !           194:     @abstract Factory function to create and initialize an 
        !           195:     IOMBufBigMemoryCursor in one operation, see
        !           196:     IOMBufMemoryCursor::initWithSpecification.
        !           197:     @param maxSegmentSize Maximum allowable size for one segment.
        !           198:     @param maxNumSegments Maximum number of segments.
        !           199:     @result A new mbuf cursor if successfully created and initialized,
        !           200:     0 otherwise. */
        !           201: 
        !           202:     static IOMBufBigMemoryCursor * withSpecification(UInt maxSegmentSize,
        !           203:                                                      UInt maxNumSegments);
        !           204: 
        !           205: /*! @function getPhysicalSegments
        !           206:     @abstract Generate a big endian physical scatter/gather list from a given
        !           207:     mbuf.
        !           208:     @param packet The mbuf packet.
        !           209:     @param vector Pointer to an array of IOPhysicalSegments for the output 
        !           210:     physical scatter/gather list.
        !           211:     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
        !           212:     @result The number of segments that were filled in is returned, or
        !           213:     0 if an error occurred. */
        !           214: 
        !           215:     UInt getPhysicalSegments(struct mbuf * packet,
        !           216:                              struct IOPhysicalSegment * vector,
        !           217:                              UInt numVectorSegments = 0);
        !           218: 
        !           219: /*! @function getPhysicalSegmentsWithCoalesce
        !           220:     @abstract Generate a big endian physical scatter/gather list from a given
        !           221:     mbuf.
        !           222:     @discussion Generate a big endian physical scatter/gather list from a 
        !           223:     given mbuf. Coalesce mbuf chain when the number of segments in the 
        !           224:     scatter/gather list exceeds numVectorSegments.
        !           225:     @param packet The mbuf packet.
        !           226:     @param vector Pointer to an array of IOPhysicalSegments for the output 
        !           227:     physical scatter/gather list.
        !           228:     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
        !           229:     @result The number of segments that were filled in is returned, or
        !           230:     0 if an error occurred. */
        !           231: 
        !           232:     UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
        !           233:                                          struct IOPhysicalSegment * vector,
        !           234:                                          UInt numVectorSegments = 0);
        !           235: };
        !           236: 
        !           237: //===========================================================================
        !           238: //===========================================================================
        !           239: 
        !           240: /*! @class IOMBufLittleMemoryCursor : public IOMBufMemoryCursor
        !           241:     @abstract A IOMBufMemoryCursor subclass that outputs a vector of 
        !           242:     IOPhysicalSegments in the little endian byte order.  
        !           243:     @discussion The IOMBufLittleMemoryCursor would be used when the DMA 
        !           244:     hardware requires a little endian address and length pair.  This cursor 
        !           245:     outputs an array of IOPhysicalSegments that are encoded in little endian 
        !           246:     format. */
        !           247: 
        !           248: class IOMBufLittleMemoryCursor : public IOMBufMemoryCursor
        !           249: {
        !           250:     OSDeclareDefaultStructors(IOMBufLittleMemoryCursor)
        !           251: 
        !           252: public:
        !           253: 
        !           254: /*! @function withSpecification
        !           255:     @abstract Factory function to create and initialize an 
        !           256:     IOMBufLittleMemoryCursor in one operation, see
        !           257:     IOMBufMemoryCursor::initWithSpecification.
        !           258:     @param maxSegmentSize Maximum allowable size for one segment.
        !           259:     @param maxNumSegments Maximum number of segments.
        !           260:     @result A new mbuf cursor if successfully created and initialized,
        !           261:     0 otherwise. */
        !           262: 
        !           263:     static IOMBufLittleMemoryCursor * withSpecification(UInt maxSegmentSize, 
        !           264:                                                         UInt maxNumSegments);
        !           265: 
        !           266: /*! @function getPhysicalSegments
        !           267:     @abstract Generate a little endian physical scatter/gather list from a 
        !           268:     given mbuf.
        !           269:     @param packet The mbuf packet.
        !           270:     @param vector Pointer to an array of IOPhysicalSegments for the output 
        !           271:     physical scatter/gather list.
        !           272:     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
        !           273:     @result The number of segments that were filled in is returned, or
        !           274:     0 if an error occurred. */
        !           275: 
        !           276:     UInt getPhysicalSegments(struct mbuf * packet,
        !           277:                              struct IOPhysicalSegment * vector,
        !           278:                              UInt numVectorSegments = 0);
        !           279: 
        !           280: /*! @function getPhysicalSegmentsWithCoalesce
        !           281:     @abstract Generate a little endian physical scatter/gather list from a 
        !           282:     given mbuf.
        !           283:     @discussion Generate a little endian physical scatter/gather list from a 
        !           284:     given mbuf. Coalesce mbuf chain when the number of segments in the 
        !           285:     scatter/gather list exceeds numVectorSegments.
        !           286:     @param packet The mbuf packet.
        !           287:     @param vector Pointer to an array of IOPhysicalSegments for the output 
        !           288:     physical scatter/gather list.
        !           289:     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
        !           290:     @result The number of segments that were filled in is returned, or
        !           291:     0 if an error occurred. */
        !           292: 
        !           293:     UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
        !           294:                                          struct IOPhysicalSegment * vector,
        !           295:                                          UInt numVectorSegments = 0);
        !           296: };
        !           297: 
        !           298: #ifdef __ppc__
        !           299: 
        !           300: struct IODBDMADescriptor;
        !           301: 
        !           302: //===========================================================================
        !           303: //===========================================================================
        !           304: 
        !           305: /*! @class IOMBufDBDMAMemoryCursor : public IOMBufMemoryCursor
        !           306:     @abstract A IOMBufMemoryCursor subclass that outputs a vector of 
        !           307:     IODBDMADescriptors. */
        !           308: 
        !           309: class IOMBufDBDMAMemoryCursor : public IOMBufMemoryCursor
        !           310: {
        !           311:     OSDeclareDefaultStructors(IOMBufDBDMAMemoryCursor)
        !           312: 
        !           313: public:
        !           314: 
        !           315: /*! @function withSpecification
        !           316:     @abstract Factory function to create and initialize an 
        !           317:     IOMBufDBDMAMemoryCursor in one operation, see
        !           318:     IOMBufMemoryCursor::initWithSpecification.
        !           319:     @param maxSegmentSize Maximum allowable size for one segment.
        !           320:     @param maxNumSegments Maximum number of segments.
        !           321:     @result A new mbuf cursor if successfully created and initialized,
        !           322:     0 otherwise. */
        !           323: 
        !           324:     static IOMBufDBDMAMemoryCursor * withSpecification(UInt maxSegmentSize, 
        !           325:                                                        UInt maxNumSegments);
        !           326: 
        !           327: /*! @function getPhysicalSegments
        !           328:     @abstract Generate a DBDMA descriptor list from a given mbuf.
        !           329:     @param packet The mbuf packet.
        !           330:     @param vector Pointer to an array of IODBDMADescriptor for the output list.
        !           331:     @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
        !           332:     @result The number of segments that were filled in is returned, or
        !           333:     0 if an error occurred. */
        !           334: 
        !           335:     UInt getPhysicalSegments(struct mbuf * packet,
        !           336:                              struct IODBDMADescriptor *vector,
        !           337:                              UInt numVectorSegments = 0);
        !           338: 
        !           339: /*! @function getPhysicalSegmentsWithCoalesce
        !           340:     @abstract Generate a DBDMA descriptor list from a given mbuf.
        !           341:     @discussion Generate a DBDMA descriptor list from a given mbuf.
        !           342:     Coalesce mbuf chain when the number of elements in the list exceeds
        !           343:     numVectorSegments.
        !           344:     @param packet The mbuf packet.
        !           345:     @param vector Pointer to an array of IODBDMADescriptor for the output list.
        !           346:     @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
        !           347:     @result The number of segments that were filled in is returned, or
        !           348:     0 if an error occurred. */
        !           349: 
        !           350:     UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
        !           351:                                          struct IODBDMADescriptor * vector,
        !           352:                                          UInt numVectorSegments = 0);
        !           353: };
        !           354: 
        !           355: #endif /* __ppc__ */
        !           356: 
        !           357: inline UInt IOMBufMemoryCursor::getAndResetCoalesceCount()
        !           358: {
        !           359:     UInt cnt = coalesceCount; coalesceCount = 0; return cnt;
        !           360: }
        !           361: 
        !           362: inline UInt
        !           363: IOMBufNaturalMemoryCursor::getPhysicalSegments(struct mbuf *packet,
        !           364:                        struct IOPhysicalSegment *vector,
        !           365:                        UInt numVectorSegments = 0)
        !           366: {
        !           367:     return genPhysicalSegments(packet, vector, numVectorSegments, false);
        !           368: }
        !           369: 
        !           370: inline UInt
        !           371: IOMBufNaturalMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
        !           372:                                    struct IOPhysicalSegment *vector,
        !           373:                                    UInt numVectorSegments = 0)
        !           374: {
        !           375:     return genPhysicalSegments(packet, vector, numVectorSegments, true);
        !           376: }
        !           377: 
        !           378: inline UInt
        !           379: IOMBufBigMemoryCursor::getPhysicalSegments(struct mbuf *packet,
        !           380:                        struct IOPhysicalSegment *vector,
        !           381:                        UInt numVectorSegments = 0)
        !           382: {
        !           383:     return genPhysicalSegments(packet, vector, numVectorSegments, false);
        !           384: }
        !           385: 
        !           386: inline UInt
        !           387: IOMBufBigMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
        !           388:                                    struct IOPhysicalSegment *vector,
        !           389:                                    UInt numVectorSegments = 0)
        !           390: {
        !           391:     return genPhysicalSegments(packet, vector, numVectorSegments, true);
        !           392: }
        !           393: 
        !           394: inline UInt
        !           395: IOMBufLittleMemoryCursor::getPhysicalSegments(struct mbuf *packet,
        !           396:                        struct IOPhysicalSegment *vector,
        !           397:                        UInt numVectorSegments = 0)
        !           398: {
        !           399:     return genPhysicalSegments(packet, vector, numVectorSegments, false);
        !           400: }
        !           401: 
        !           402: inline UInt
        !           403: IOMBufLittleMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
        !           404:                                    struct IOPhysicalSegment *vector,
        !           405:                                    UInt numVectorSegments = 0)
        !           406: {
        !           407:     return genPhysicalSegments(packet, vector, numVectorSegments, true);
        !           408: }
        !           409: 
        !           410: #ifdef __ppc__
        !           411: inline UInt
        !           412: IOMBufDBDMAMemoryCursor::getPhysicalSegments(struct mbuf *packet,
        !           413:                                    struct IODBDMADescriptor *vector,
        !           414:                                    UInt numVectorSegments = 0)
        !           415: {
        !           416:     return genPhysicalSegments(packet, vector, numVectorSegments, false);
        !           417: }
        !           418: 
        !           419: inline UInt
        !           420: IOMBufDBDMAMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
        !           421:                                    struct IODBDMADescriptor *vector,
        !           422:                                    UInt numVectorSegments = 0)
        !           423: {
        !           424:     return genPhysicalSegments(packet, vector, numVectorSegments, true);
        !           425: }
        !           426: #endif /* __ppc__ */
        !           427: 
        !           428: #endif /* !_IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H */
        !           429: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.