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 44class IOGatedOutputQueue : public IOBasicOutputQueue 45{ 46 OSDeclareDefaultStructors( IOGatedOutputQueue ) 47 48private: 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 58protected: 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 87public: 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 UInt32 priorities = 1); 106 107/*! @function withTarget 108 @abstract Factory method that constructs and initializes an 109 IOGatedOutputQueue object. 110 @param target An IONetworkController object that will handle packets 111 removed from the queue. 112 @param workloop A workloop object. An IOCommandGate object is created 113 and added to this workloop as an event source. 114 @param capacity The initial capacity of the output queue. 115 @result Returns an IOGatedOutputQueue object on success, or 0 otherwise. 116*/ 117 118 static IOGatedOutputQueue * withTarget(IONetworkController * target, 119 IOWorkLoop * workloop, 120 UInt32 capacity = 0); 121 122 /*! @function withTarget 123 @abstract Factory method that constructs and initializes an 124 IOGatedOutputQueue object. 125 @param target An IONetworkController object that will handle packets 126 removed from the queue. 127 @param workloop A workloop object. An IOCommandGate object is created 128 and added to this workloop as an event source. 129 @param capacity The initial capacity of the output queue. 130 @param priorities The number of traffic priorities supported 131 @result Returns an IOGatedOutputQueue object on success, or 0 otherwise. 132 */ 133 134 static IOGatedOutputQueue * withTarget(IONetworkController * target, 135 IOWorkLoop * workloop, 136 UInt32 capacity, 137 UInt32 priorities); 138 139/*! @function withTarget 140 @abstract Factory method that constructs and initializes an 141 IOGatedOutputQueue object. 142 @param target The object that will handle packets removed from the 143 queue. 144 @param action The function that will handle packets removed from the 145 queue. 146 @param workloop A workloop object. An IOCommandGate object is created 147 and added to this workloop as an event source. 148 @param capacity The initial capacity of the output queue. 149 @result Returns an IOGatedOutputQueue object on success, or 0 otherwise. 150*/ 151 152 static IOGatedOutputQueue * withTarget(OSObject * target, 153 IOOutputAction action, 154 IOWorkLoop * workloop, 155 UInt32 capacity = 0); 156 157 /*! @function withTarget 158 @abstract Factory method that constructs and initializes an 159 IOGatedOutputQueue object. 160 @param target The object that will handle packets removed from the 161 queue. 162 @param action The function that will handle packets removed from the 163 queue. 164 @param workloop A workloop object. An IOCommandGate object is created 165 and added to this workloop as an event source. 166 @param capacity The initial capacity of the output queue. 167 @param priorities The number of traffic priorities supported 168 @result Returns an IOGatedOutputQueue object on success, or 0 otherwise. 169 */ 170 171 static IOGatedOutputQueue * withTarget(OSObject * target, 172 IOOutputAction action, 173 IOWorkLoop * workloop, 174 UInt32 capacity, 175 UInt32 priorities); 176}; 177 178#endif /* !_IOGATEDOUTPUTQUEUE_H */ 179