iokit/IOKit/network/IOMbufMemoryCursor.h

   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 protected:
  69     UInt32 maxNumSegments;
  70     UInt32 coalesceCount;
  71     UInt32 packetTooBigErrors;
  72
  73     struct ExpansionData { };
  74     /*! @var reserved
  75         Reserved for future use.  (Internal use only)  */
  76     ExpansionData *reserved;
  77
  78     virtual bool initWithSpecification(OutputSegmentFunc outSeg,
  79                                        UInt32 maxSegmentSize,
  80                                        UInt32 maxTransferSize,
  81                                        UInt32 align);
  82
  83 public:
  84 /*! @function initWithSpecification
  85     @abstract Primary initializer for the IOMbufMemoryCursor class.
  86     @param outSeg Function to call to output one physical segment.
  87     @param maxSegmentSize Maximum allowable size for one segment.
  88     @param maxNumSegments Maximum number of segments.
  89     @result true if the inherited classes and this instance initialized
  90     successfully. */
  91
  92     virtual bool initWithSpecification(OutputSegmentFunc outSeg,
  93                                        UInt32 maxSegmentSize,
  94                                        UInt32 maxNumSegments);
  95
  96 /*! @function genPhysicalSegments
  97     @abstract Generate a physical scatter/gather list given a mbuf packet.
  98     @discussion Generates a list of physical segments from the given mbuf.
  99     @param packet The mbuf packet.
 100     @param vector Void pointer to base of output physical scatter/gather list.
 101     Always passed directly onto the OutputSegmentFunc without interpretation
 102     by the cursor.
 103     @param maxSegs Maximum number of segments that can be written to segments
 104     array.
 105     @param doCoalesce Set to true to perform coalescing when the required
 106     number of segments exceeds the specified limit, otherwise abort and
 107     return 0.
 108     @result The number of segments that were filled in is returned, or
 109     0 if an error occurred. */
 110
 111     virtual UInt32 genPhysicalSegments(struct mbuf * packet, void * vector,
 112                                        UInt32 maxSegs, bool doCoalesce);
 113
 114 /*! @function getAndResetCoalesceCount
 115     @abstract Returns a count of the total number of mbuf chains coalesced
 116     by genPhysicalSegments(). The counter is then reset to 0.
 117     @result The coalesce count. */
 118
 119     UInt32 getAndResetCoalesceCount();
 120
 121     // Virtual function padding
 122     OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  0);
 123     OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  1);
 124     OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  2);
 125     OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  3);
 126 };
 127
 128
 129 /*! @class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor
 130     @abstract A IOMbufMemoryCursor subclass that outputs a vector of
 131     IOPhysicalSegments in the natural byte orientation for the cpu.
 132     @discussion The IOMbufNaturalMemoryCursor would be used when it is too
 133     difficult to implement an OutputSegmentFunc that is more appropriate for
 134     your hardware.  This cursor just outputs an array of IOPhysicalSegments. */
 135
 136 class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor
 137 {
 138     OSDeclareDefaultStructors(IOMbufNaturalMemoryCursor)
 139
 140 public:
 141
 142 /*! @function withSpecification
 143     @abstract Factory function to create and initialize an
 144     IOMbufNaturalMemoryCursor in one operation, see
 145     IOMbufMemoryCursor::initWithSpecification.
 146     @param maxSegmentSize Maximum allowable size for one segment.
 147     @param maxNumSegments Maximum number of segments.
 148     @result A new mbuf cursor if successfully created and initialized,
 149     0 otherwise. */
 150
 151     static IOMbufNaturalMemoryCursor * withSpecification(UInt32 maxSegmentSize,
 152                                                          UInt32 maxNumSegments);
 153
 154 /*! @function getPhysicalSegments
 155     @abstract Generate a cpu natural physical scatter/gather list from a given
 156     mbuf.
 157     @param packet The mbuf packet.
 158     @param vector Pointer to an array of IOPhysicalSegments for the output
 159     physical scatter/gather list.
 160     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
 161     @result The number of segments that were filled in is returned, or
 162     0 if an error occurred. */
 163
 164     UInt32 getPhysicalSegments(struct mbuf * packet,
 165                                struct IOPhysicalSegment * vector,
 166                                UInt32 numVectorSegments = 0);
 167
 168 /*! @function getPhysicalSegmentsWithCoalesce
 169     @abstract Generate a cpu natural physical scatter/gather list from a given
 170     mbuf.
 171     @discussion Generate a cpu natural physical scatter/gather list from a
 172     given mbuf. Coalesce mbuf chain when the number of segments in the
 173     scatter/gather list exceeds numVectorSegments.
 174     @param packet The mbuf packet.
 175     @param vector Pointer to an array of IOPhysicalSegments for the output
 176     physical scatter/gather list.
 177     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
 178     @result The number of segments that were filled in is returned, or
 179     0 if an error occurred. */
 180
 181     UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
 182                                            struct IOPhysicalSegment * vector,
 183                                            UInt32 numVectorSegments = 0);
 184 };
 185
 186 //===========================================================================
 187 //===========================================================================
 188
 189 /*! @class IOMbufBigMemoryCursor : public IOMbufMemoryCursor
 190     @abstract A IOMbufMemoryCursor subclass that outputs a vector of
 191     IOPhysicalSegments in the big endian byte order.
 192     @discussion The IOMbufBigMemoryCursor would be used when the DMA hardware
 193     requires a big endian address and length pair.  This cursor outputs an
 194     array of IOPhysicalSegments that are encoded in big-endian format. */
 195
 196 class IOMbufBigMemoryCursor : public IOMbufMemoryCursor
 197 {
 198     OSDeclareDefaultStructors(IOMbufBigMemoryCursor)
 199
 200 public:
 201
 202 /*! @function withSpecification
 203     @abstract Factory function to create and initialize an
 204     IOMbufBigMemoryCursor in one operation, see
 205     IOMbufMemoryCursor::initWithSpecification.
 206     @param maxSegmentSize Maximum allowable size for one segment.
 207     @param maxNumSegments Maximum number of segments.
 208     @result A new mbuf cursor if successfully created and initialized,
 209     0 otherwise. */
 210
 211     static IOMbufBigMemoryCursor * withSpecification(UInt32 maxSegmentSize,
 212                                                      UInt32 maxNumSegments);
 213
 214 /*! @function getPhysicalSegments
 215     @abstract Generate a big endian physical scatter/gather list from a given
 216     mbuf.
 217     @param packet The mbuf packet.
 218     @param vector Pointer to an array of IOPhysicalSegments for the output
 219     physical scatter/gather list.
 220     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
 221     @result The number of segments that were filled in is returned, or
 222     0 if an error occurred. */
 223
 224     UInt32 getPhysicalSegments(struct mbuf * packet,
 225                                struct IOPhysicalSegment * vector,
 226                                UInt32 numVectorSegments = 0);
 227
 228 /*! @function getPhysicalSegmentsWithCoalesce
 229     @abstract Generate a big endian physical scatter/gather list from a given
 230     mbuf.
 231     @discussion Generate a big endian physical scatter/gather list from a
 232     given mbuf. Coalesce mbuf chain when the number of segments in the
 233     scatter/gather list exceeds numVectorSegments.
 234     @param packet The mbuf packet.
 235     @param vector Pointer to an array of IOPhysicalSegments for the output
 236     physical scatter/gather list.
 237     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
 238     @result The number of segments that were filled in is returned, or
 239     0 if an error occurred. */
 240
 241     UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
 242                                            struct IOPhysicalSegment * vector,
 243                                            UInt32 numVectorSegments = 0);
 244 };
 245
 246 //===========================================================================
 247 //===========================================================================
 248
 249 /*! @class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor
 250     @abstract A IOMbufMemoryCursor subclass that outputs a vector of
 251     IOPhysicalSegments in the little endian byte order.
 252     @discussion The IOMbufLittleMemoryCursor would be used when the DMA
 253     hardware requires a little endian address and length pair.  This cursor
 254     outputs an array of IOPhysicalSegments that are encoded in little endian
 255     format. */
 256
 257 class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor
 258 {
 259     OSDeclareDefaultStructors(IOMbufLittleMemoryCursor)
 260
 261 public:
 262
 263 /*! @function withSpecification
 264     @abstract Factory function to create and initialize an
 265     IOMbufLittleMemoryCursor in one operation, see
 266     IOMbufMemoryCursor::initWithSpecification.
 267     @param maxSegmentSize Maximum allowable size for one segment.
 268     @param maxNumSegments Maximum number of segments.
 269     @result A new mbuf cursor if successfully created and initialized,
 270     0 otherwise. */
 271
 272     static IOMbufLittleMemoryCursor * withSpecification(UInt32 maxSegmentSize,
 273                                                         UInt32 maxNumSegments);
 274
 275 /*! @function getPhysicalSegments
 276     @abstract Generate a little endian physical scatter/gather list from a
 277     given mbuf.
 278     @param packet The mbuf packet.
 279     @param vector Pointer to an array of IOPhysicalSegments for the output
 280     physical scatter/gather list.
 281     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
 282     @result The number of segments that were filled in is returned, or
 283     0 if an error occurred. */
 284
 285     UInt32 getPhysicalSegments(struct mbuf * packet,
 286                                struct IOPhysicalSegment * vector,
 287                                UInt32 numVectorSegments = 0);
 288
 289 /*! @function getPhysicalSegmentsWithCoalesce
 290     @abstract Generate a little endian physical scatter/gather list from a
 291     given mbuf.
 292     @discussion Generate a little endian physical scatter/gather list from a
 293     given mbuf. Coalesce mbuf chain when the number of segments in the
 294     scatter/gather list exceeds numVectorSegments.
 295     @param packet The mbuf packet.
 296     @param vector Pointer to an array of IOPhysicalSegments for the output
 297     physical scatter/gather list.
 298     @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
 299     @result The number of segments that were filled in is returned, or
 300     0 if an error occurred. */
 301
 302     UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
 303                                            struct IOPhysicalSegment * vector,
 304                                            UInt32 numVectorSegments = 0);
 305 };
 306
 307 #ifdef __ppc__
 308
 309 struct IODBDMADescriptor;
 310
 311 //===========================================================================
 312 //===========================================================================
 313
 314 /*! @class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor
 315     @abstract A IOMbufMemoryCursor subclass that outputs a vector of
 316     IODBDMADescriptors. */
 317
 318 class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor
 319 {
 320     OSDeclareDefaultStructors(IOMbufDBDMAMemoryCursor)
 321
 322 public:
 323
 324 /*! @function withSpecification
 325     @abstract Factory function to create and initialize an
 326     IOMbufDBDMAMemoryCursor in one operation, see
 327     IOMbufMemoryCursor::initWithSpecification.
 328     @param maxSegmentSize Maximum allowable size for one segment.
 329     @param maxNumSegments Maximum number of segments.
 330     @result A new mbuf cursor if successfully created and initialized,
 331     0 otherwise. */
 332
 333     static IOMbufDBDMAMemoryCursor * withSpecification(UInt32 maxSegmentSize,
 334                                                        UInt32 maxNumSegments);
 335
 336 /*! @function getPhysicalSegments
 337     @abstract Generate a DBDMA descriptor list from a given mbuf.
 338     @param packet The mbuf packet.
 339     @param vector Pointer to an array of IODBDMADescriptor for the output list.
 340     @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
 341     @result The number of segments that were filled in is returned, or
 342     0 if an error occurred. */
 343
 344     UInt32 getPhysicalSegments(struct mbuf * packet,
 345                                struct IODBDMADescriptor *vector,
 346                                UInt32 numVectorSegments = 0);
 347
 348 /*! @function getPhysicalSegmentsWithCoalesce
 349     @abstract Generate a DBDMA descriptor list from a given mbuf.
 350     @discussion Generate a DBDMA descriptor list from a given mbuf.
 351     Coalesce mbuf chain when the number of elements in the list exceeds
 352     numVectorSegments.
 353     @param packet The mbuf packet.
 354     @param vector Pointer to an array of IODBDMADescriptor for the output list.
 355     @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
 356     @result The number of segments that were filled in is returned, or
 357     0 if an error occurred. */
 358
 359     UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
 360                                            struct IODBDMADescriptor * vector,
 361                                            UInt32 numVectorSegments = 0);
 362 };
 363
 364 #endif /* __ppc__ */
 365
 366 inline UInt32 IOMbufMemoryCursor::getAndResetCoalesceCount()
 367 {
 368     UInt32 cnt = coalesceCount; coalesceCount = 0; return cnt;
 369 }
 370
 371 inline UInt32
 372 IOMbufNaturalMemoryCursor::getPhysicalSegments(struct mbuf *packet,
 373                        struct IOPhysicalSegment *vector,
 374                        UInt32 numVectorSegments = 0)
 375 {
 376     return genPhysicalSegments(packet, vector, numVectorSegments, false);
 377 }
 378
 379 inline UInt32
 380 IOMbufNaturalMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
 381                                    struct IOPhysicalSegment *vector,
 382                                    UInt32 numVectorSegments = 0)
 383 {
 384     return genPhysicalSegments(packet, vector, numVectorSegments, true);
 385 }
 386
 387 inline UInt32
 388 IOMbufBigMemoryCursor::getPhysicalSegments(struct mbuf *packet,
 389                        struct IOPhysicalSegment *vector,
 390                        UInt32 numVectorSegments = 0)
 391 {
 392     return genPhysicalSegments(packet, vector, numVectorSegments, false);
 393 }
 394
 395 inline UInt32
 396 IOMbufBigMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
 397                                    struct IOPhysicalSegment *vector,
 398                                    UInt32 numVectorSegments = 0)
 399 {
 400     return genPhysicalSegments(packet, vector, numVectorSegments, true);
 401 }
 402
 403 inline UInt32
 404 IOMbufLittleMemoryCursor::getPhysicalSegments(struct mbuf *packet,
 405                        struct IOPhysicalSegment *vector,
 406                        UInt32 numVectorSegments = 0)
 407 {
 408     return genPhysicalSegments(packet, vector, numVectorSegments, false);
 409 }
 410
 411 inline UInt32
 412 IOMbufLittleMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
 413                                    struct IOPhysicalSegment *vector,
 414                                    UInt32 numVectorSegments = 0)
 415 {
 416     return genPhysicalSegments(packet, vector, numVectorSegments, true);
 417 }
 418
 419 #ifdef __ppc__
 420 inline UInt32
 421 IOMbufDBDMAMemoryCursor::getPhysicalSegments(struct mbuf *packet,
 422                                    struct IODBDMADescriptor *vector,
 423                                    UInt32 numVectorSegments = 0)
 424 {
 425     return genPhysicalSegments(packet, vector, numVectorSegments, false);
 426 }
 427
 428 inline UInt32
 429 IOMbufDBDMAMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
 430                                    struct IODBDMADescriptor *vector,
 431                                    UInt32 numVectorSegments = 0)
 432 {
 433     return genPhysicalSegments(packet, vector, numVectorSegments, true);
 434 }
 435 #endif /* __ppc__ */
 436
 437 #endif /* !_IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H */
 438