| 1 | /*␊ |
| 2 | * Copyright (c) 1998-2008 Apple 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 | #ifndef _IOGATEDOUTPUTQUEUE_H␊ |
| 24 | #define _IOGATEDOUTPUTQUEUE_H␊ |
| 25 | ␊ |
| 26 | #include <IOKit/IOWorkLoop.h>␊ |
| 27 | #include <IOKit/IOCommandGate.h>␊ |
| 28 | #include <IOKit/IOInterruptEventSource.h>␊ |
| 29 | #include <IOKit/network/IOBasicOutputQueue.h>␊ |
| 30 | ␊ |
| 31 | /*! @class IOGatedOutputQueue␊ |
| 32 | @abstract An extension of an IOBasicOutputQueue. ␊ |
| 33 | @discussion An IOCommandGate␊ |
| 34 | object is created by this queue and added to a work loop as an␊ |
| 35 | event source. All calls to the target by the consumer thread must␊ |
| 36 | occur with the gate closed. Therefore, all calls to the target of␊ |
| 37 | this type of queue will be serialized with any other thread that␊ |
| 38 | runs on the same work loop context. This is useful for network␊ |
| 39 | drivers that have a tight hardware coupling between the transmit␊ |
| 40 | and receive engines, and a single-threaded hardware access model␊ |
| 41 | is desirable. ␊ |
| 42 | */␊ |
| 43 | ␊ |
| 44 | class IOGatedOutputQueue : public IOBasicOutputQueue␊ |
| 45 | {␊ |
| 46 | OSDeclareDefaultStructors( IOGatedOutputQueue )␊ |
| 47 | ␊ |
| 48 | private:␊ |
| 49 | static void gatedOutput(OSObject * owner,␊ |
| 50 | IOGatedOutputQueue * self,␊ |
| 51 | IOMbufQueue * queue,␊ |
| 52 | UInt32 * state);␊ |
| 53 | ␊ |
| 54 | static void restartDeferredOutput(OSObject * owner,␊ |
| 55 | IOInterruptEventSource * sender,␊ |
| 56 | int count);␊ |
| 57 | ␊ |
| 58 | protected:␊ |
| 59 | IOCommandGate * _gate;␊ |
| 60 | IOInterruptEventSource * _interruptSrc;␊ |
| 61 | ␊ |
| 62 | /*! @function output␊ |
| 63 | @abstract Transfers all packets in the mbuf queue to the target.␊ |
| 64 | @param queue A queue of output packets.␊ |
| 65 | @param state Return a state bit defined by IOBasicOutputQueue that␊ |
| 66 | declares the new state of the queue following this method call.␊ |
| 67 | A kStateStalled is returned if the queue should stall, otherwise 0␊ |
| 68 | is returned. ␊ |
| 69 | */␊ |
| 70 | ␊ |
| 71 | virtual void output(IOMbufQueue * queue, UInt32 * state);␊ |
| 72 | ␊ |
| 73 | /*! @function free␊ |
| 74 | @abstract Frees the IOGatedOutputQueue object.␊ |
| 75 | @discussion Release allocated resources, then call super::free(). */␊ |
| 76 | ␊ |
| 77 | virtual void free();␊ |
| 78 | ␊ |
| 79 | /*! @function output␊ |
| 80 | @abstract Overrides the method inherited from IOOutputQueue.␊ |
| 81 | @result Returns true if a thread was successfully scheduled to service␊ |
| 82 | the queue. ␊ |
| 83 | */␊ |
| 84 | ␊ |
| 85 | virtual bool scheduleServiceThread(void * param);␊ |
| 86 | ␊ |
| 87 | public:␊ |
| 88 | ␊ |
| 89 | /*! @function init␊ |
| 90 | @abstract Initializes an IOGatedOutputQueue object.␊ |
| 91 | @param target The object that will handle packets removed from the␊ |
| 92 | queue, and is usually a subclass of IONetworkController.␊ |
| 93 | @param action The function that will handle packets removed from the␊ |
| 94 | queue.␊ |
| 95 | @param workloop A workloop object. An IOCommandGate object is created␊ |
| 96 | and added to this workloop as an event source.␊ |
| 97 | @param capacity The initial capacity of the output queue.␊ |
| 98 | @result Returns true if initialized successfully, false otherwise. ␊ |
| 99 | */␊ |
| 100 | ␊ |
| 101 | virtual bool init(OSObject * target,␊ |
| 102 | IOOutputAction action,␊ |
| 103 | IOWorkLoop * workloop,␊ |
| 104 | UInt32 capacity = 0);␊ |
| 105 | ␊ |
| 106 | /*! @function withTarget␊ |
| 107 | @abstract Factory method that constructs and initializes an␊ |
| 108 | IOGatedOutputQueue object.␊ |
| 109 | @param target An IONetworkController object that will handle packets␊ |
| 110 | removed from the queue.␊ |
| 111 | @param workloop A workloop object. An IOCommandGate object is created␊ |
| 112 | and added to this workloop as an event source.␊ |
| 113 | @param capacity The initial capacity of the output queue.␊ |
| 114 | @result Returns an IOGatedOutputQueue object on success, or 0 otherwise. ␊ |
| 115 | */␊ |
| 116 | ␊ |
| 117 | static IOGatedOutputQueue * withTarget(IONetworkController * target,␊ |
| 118 | IOWorkLoop * workloop,␊ |
| 119 | UInt32 capacity = 0);␊ |
| 120 | ␊ |
| 121 | /*! @function withTarget␊ |
| 122 | @abstract Factory method that constructs and initializes an␊ |
| 123 | IOGatedOutputQueue object.␊ |
| 124 | @param target The object that will handle packets removed from the␊ |
| 125 | queue.␊ |
| 126 | @param action The function that will handle packets removed from the␊ |
| 127 | queue.␊ |
| 128 | @param workloop A workloop object. An IOCommandGate object is created␊ |
| 129 | and added to this workloop as an event source.␊ |
| 130 | @param capacity The initial capacity of the output queue.␊ |
| 131 | @result Returns an IOGatedOutputQueue object on success, or 0 otherwise. ␊ |
| 132 | */␊ |
| 133 | ␊ |
| 134 | static IOGatedOutputQueue * withTarget(OSObject * target,␊ |
| 135 | IOOutputAction action,␊ |
| 136 | IOWorkLoop * workloop,␊ |
| 137 | UInt32 capacity = 0);␊ |
| 138 | };␊ |
| 139 | ␊ |
| 140 | #endif /* !_IOGATEDOUTPUTQUEUE_H */␊ |
| 141 | |
