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