iokit/IOKit/network/IOOutputQueue.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  * IOOutputQueue.h
  26  *
  27  * HISTORY
  28  * 2-Feb-1999       Joe Liu (jliu) created.
  29  *
  30  */
  31
  32 #ifndef _IOOUTPUTQUEUE_H
  33 #define _IOOUTPUTQUEUE_H
  34
  35 #include <IOKit/network/IONetworkInterface.h>
  36
  37 // Forward declarations.
  38 //
  39 struct mbuf;
  40 class  IONetworkData;
  41
  42 // FIXME - We do not want the enqueue/dequeue macros defined in queue.h.
  43 //
  44 #undef enqueue(queue,elt)
  45 #undef dequeue(queue)
  46
  47 // FIXME - Belongs in IOBasicOutputQueue.h
  48 //
  49 /*! @enum The status of the packet sent to the target.
  50     @constant kIOOutputStatusMask Define the status field in the return code.
  51     @constant kIOOutputStatusAccept Packet was accepted by the target.
  52     @constant kIOOutputStatusDropped Packet accepted, but was also dropped.
  53     @constant kIOOutputStatusRetry Target ran out of resources, and is unable
  54     to accept the packet. The ownership of the packet reverts back to the
  55     queue. */
  56
  57 enum {
  58     kIOOutputStatusMask     = 0x00ff,
  59     kIOOutputStatusAccepted = 0x0000,
  60     kIOOutputStatusDropped  = 0x0001,
  61     kIOOutputStatusRetry    = 0x0002
  62 };
  63
  64 /*! @enum A command requested by the target.
  65     @constant kIOOutputCommandMask Define the command field in the return code.
  66     @constant kIOOutputCommandNone No command.
  67     @constant kIOOutputCommandStall A command to stall the queue. */
  68
  69 enum {
  70     kIOOutputCommandMask    = 0xff00,
  71     kIOOutputCommandNone    = 0x0000,
  72     kIOOutputCommandStall   = 0x0100
  73 };
  74
  75 /*! @enum Definition of common return codes returned by the target's
  76           output handler.
  77     @constant kIOReturnOutputSuccess Packet was accepted.
  78     @constant kIOReturnOutputDropped Packet was dropped.
  79     @constant kIOReturnOutputStall   Stall the queue and retry the same packet
  80               when the queue is restarted. */
  81
  82 enum {
  83     kIOReturnOutputSuccess = (kIOOutputStatusAccepted | kIOOutputCommandNone),
  84     kIOReturnOutputDropped = (kIOOutputStatusDropped  | kIOOutputCommandNone),
  85     kIOReturnOutputStall   = (kIOOutputStatusRetry    | kIOOutputCommandStall)
  86 };
  87
  88 /*! @class IOOutputQueue : public OSObject
  89     @abstract A packet queue that supports multiple producers, and a single
  90     consumer. Each producer, or a client thread, will deliver a chain of packets
  91     to the queue. A single consumer will remove packets from the queue one at a
  92     time and forward it to the registered target/action. This object may be used
  93     by an IONetworkController on the output (transmit) side to handle the output
  94     packet flow downstream from an IONetworkInterface, and then call the driver's
  95     output function. IOOutputQueue is an abstract class that provides an interface
  96     for its subclasses. Concrete subclasses will complete the implementation, and
  97     specify the context that the target is called for packets removed from
  98     the queue. */
  99
 100 class IOOutputQueue : public OSObject
 101 {
 102     OSDeclareAbstractStructors( IOOutputQueue )
 103
 104 private:
 105
 106     static void runServiceThread(thread_call_param_t, thread_call_param_t);
 107
 108 protected:
 109
 110     thread_call_t  _callEntry;  // callout entry structure.
 111
 112     struct ExpansionData { };
 113     /*! @var reserved
 114         Reserved for future use.  (Internal use only)  */
 115     ExpansionData *_reserved;
 116
 117
 118 /*! @function init
 119     @abstract Initialize an IOOutputQueue object.
 120     @result true if initialized successfully, false otherwise. */
 121
 122     virtual bool init();
 123
 124 /*! @function free
 125     @abstract Free the IOOutputQueue object.
 126     @discussion Release allocated resources, then call super::free(). */
 127
 128     virtual void free();
 129
 130 /*! @function scheduleServiceThread
 131     @abstract Schedule a service thread callout.
 132     @discussion This method can be called by service() to schedule
 133     a thread that will call serviceThread() when it starts running.
 134     @param param A parameter to pass to the serviceThread() method.
 135     @result true if a thread callout was scheduled, false otherwise. */
 136
 137     virtual bool scheduleServiceThread(void * param);
 138
 139 /*! @function cancelServiceThread
 140     @abstract Cancel any pending service thread callout.
 141     @result true if a previously scheduled thread callout was canceled,
 142     false otherwise. */
 143
 144     virtual bool cancelServiceThread();
 145
 146 /*! @function serviceThread
 147     @abstract Method called by the scheduled service thread when it
 148     starts to run.
 149     @discussion Must be implemented by a subclass that calls
 150     scheduleServiceThread(). The default implementation does nothing.
 151     @param param A parameter that was given to scheduleServiceThread()
 152     when the service thread was scheduled. */
 153
 154     virtual void serviceThread(void * param);
 155
 156 public:
 157
 158 /*! @function start
 159     @abstract Start up the queue.
 160     @discussion Called by the target to start the queue. This will allow
 161     packets to be removed from the queue, then delivered to the target.
 162     @result true if the queue was started successfully, false otherwise. */
 163
 164     virtual bool start() = 0;
 165
 166 /*! @function stop
 167     @abstract Stop the queue.
 168     @discussion Stop the queue and prevent it from sending packets to its
 169     target.
 170     @result Returns the previous running state of the queue,
 171     true if the queue was running, false if the queue was already stopped. */
 172
 173     virtual bool stop() = 0;
 174
 175 /*! @function service
 176     @abstract Service the queue.
 177     @discussion Manage the queue after it has been started.
 178     @param options Options for the service request.
 179     @result A return value to indicate the service result. */
 180
 181     virtual bool service(IOOptionBits options = 0) = 0;
 182
 183 /*! @function flush
 184     @abstract Drop and free all packets currently held by the queue.
 185     @result The number of packets that were dropped and freed. */
 186
 187     virtual UInt32 flush() = 0;
 188
 189 /*! @function setCapacity
 190     @abstract Change the number of packets that the queue can hold
 191     before it begins to drop excess packets.
 192     @param capacity The new desired capacity.
 193     @result true if the new capacity was accepted, false otherwise. */
 194
 195     virtual bool setCapacity(UInt32 capacity) = 0;
 196
 197 /*! @function getCapacity
 198     @abstract Get the number of packets that the queue can hold.
 199     @discussion The queue will begin to drop incoming packets when the
 200     size of queue reaches its capacity.
 201     @result The current queue capacity. */
 202
 203     virtual UInt32 getCapacity() const = 0;
 204
 205 /*! @function getSize
 206     @abstract Get the number of packets currently held in the queue.
 207     @result The size of the queue. */
 208
 209     virtual UInt32 getSize() const = 0;
 210
 211 /*! @function enqueue
 212     @abstract Called by a client to add a packet, or a chain of packets,
 213     to the queue.
 214     @discussion A packet is described by a mbuf chain, while a chain
 215     of packets is constructed by linking multiple mbuf chains via the
 216     m_nextpkt field.
 217     @param m A single packet, or a chain of packets.
 218     @param param A parameter provided by the caller.
 219     @result A return code. */
 220
 221     virtual UInt32 enqueue(struct mbuf * m, void * param) = 0;
 222
 223 /*! @function getOutputHandler
 224     @abstract Return the address of a function that is designated to handle
 225     incoming packets sent to the queue object.
 226     @result The address of the enqueue() method is returned. */
 227
 228     virtual IOOutputAction getOutputHandler() const;
 229
 230 /*! @function getStatisticsData
 231     @abstract Return an IONetworkData object containing statistics counters
 232     updated by the queue.
 233     @result An IONetworkData object. This implementation will always return
 234     0. */
 235
 236     virtual IONetworkData * getStatisticsData() const;
 237
 238     // Virtual function padding
 239     OSMetaClassDeclareReservedUnused( IOOutputQueue,  0);
 240     OSMetaClassDeclareReservedUnused( IOOutputQueue,  1);
 241     OSMetaClassDeclareReservedUnused( IOOutputQueue,  2);
 242     OSMetaClassDeclareReservedUnused( IOOutputQueue,  3);
 243     OSMetaClassDeclareReservedUnused( IOOutputQueue,  4);
 244     OSMetaClassDeclareReservedUnused( IOOutputQueue,  5);
 245     OSMetaClassDeclareReservedUnused( IOOutputQueue,  6);
 246     OSMetaClassDeclareReservedUnused( IOOutputQueue,  7);
 247     OSMetaClassDeclareReservedUnused( IOOutputQueue,  8);
 248     OSMetaClassDeclareReservedUnused( IOOutputQueue,  9);
 249     OSMetaClassDeclareReservedUnused( IOOutputQueue, 10);
 250     OSMetaClassDeclareReservedUnused( IOOutputQueue, 11);
 251     OSMetaClassDeclareReservedUnused( IOOutputQueue, 12);
 252     OSMetaClassDeclareReservedUnused( IOOutputQueue, 13);
 253     OSMetaClassDeclareReservedUnused( IOOutputQueue, 14);
 254     OSMetaClassDeclareReservedUnused( IOOutputQueue, 15);
 255 };
 256
 257 #endif /* !_IOOUTPUTQUEUE_H */