Return to IOCommandGate.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit

Annotation of XNU/iokit/IOKit/IOCommandGate.h, revision 1.1

1.1     ! root        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:     1999-8-10  Godfrey van der Linden(gvdl)
        !            24:        Created.
        !            25: ]*/
        !            26: /*! @language embedded-c++ */
        !            27: 
        !            28: #ifndef _IOKIT_IOCOMMANDGATE_H
        !            29: #define _IOKIT_IOCOMMANDGATE_H
        !            30: 
        !            31: #include <IOKit/IOEventSource.h>
        !            32: 
        !            33: /*!
        !            34:     @class IOCommandGate : public IOEventSource
        !            35:     @abstract Single-threaded work-loop client request mechanism.
        !            36:     @discussion An IOCommandGate instance is an extremely light way mechanism
        !            37: that executes an action on the driver's work-loop.  'On the work-loop' is
        !            38: actually a lie but the work-loop single threaded semantic is maintained for this
        !            39: event source.  Using the work-loop gate rather than execution by the workloop.
        !            40: The command gate tests for a potential self dead lock by checking if the
        !            41: runCommand request is made from the work-loop's thread, it doens't check for a
        !            42: mutual dead lock though where a pair of work loop's dead lock each other.
        !            43: <br><br>
        !            44:        The IOCommandGate is a lighter weight version of the IOCommandQueue and
        !            45: should be used in preference.  Generally use a command queue whenever you need a
        !            46: client to submit a request to a work loop.  A typical command gate action would
        !            47: check if the hardware is active, if so it will add the request to a pending
        !            48: queue internal to the device or the device's family.  Otherwise if the hardware
        !            49: is inactive then this request can be acted upon immediately.
        !            50: <br><br>
        !            51:        CAUTION: The runAction and runCommand functions can not be called from an interrupt context.
        !            52: 
        !            53: */
        !            54: class IOCommandGate : public IOEventSource
        !            55: {
        !            56:     OSDeclareDefaultStructors(IOCommandGate)
        !            57: 
        !            58: public:
        !            59: /*!
        !            60:     @typedef Action
        !            61:     @discussion Type and arguments of callout C function that is used when
        !            62: a runCommand is executed by a client.  Cast to this type when you want a C++
        !            63: member function to be used.  Note the arg1 - arg3 parameters are straight pass
        !            64: through from the runCommand to the action callout.
        !            65:     @param owner
        !            66:        Target of the function, can be used as a refcon.  The owner is set
        !            67: during initialisation of the IOCommandGate instance.    Note if a C++ function
        !            68: was specified this parameter is implicitly the first paramter in the target
        !            69: member function's parameter list.
        !            70:     @param arg0 Argument to action from run operation.
        !            71:     @param arg1 Argument to action from run operation.
        !            72:     @param arg2 Argument to action from run operation.
        !            73:     @param arg3 Argument to action from run operation.
        !            74: */
        !            75:     typedef IOReturn (*Action)(OSObject *owner,
        !            76:                               void *arg0, void *arg1,
        !            77:                               void *arg2, void *arg3);
        !            78: 
        !            79: protected:
        !            80: /*!
        !            81:     @function checkForWork
        !            82:     @abstract Not used, $link IOEventSource::checkForWork(). */
        !            83:     virtual bool checkForWork();
        !            84: 
        !            85: public:
        !            86: /*! @function commandGate
        !            87:     @abstract Factory method to create and initialise an IOCommandGate, See $link init.
        !            88:     @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
        !            89:     static IOCommandGate *commandGate(OSObject *owner, Action action = 0);
        !            90: 
        !            91: /*! @function init
        !            92:     @abstract Class initialiser.
        !            93:     @discussion Initialiser for IOCommandGate operates only on newly 'newed'
        !            94: objects.  Shouldn't be used to re-init an existing instance.
        !            95:     @param owner       Owner of this, newly created, instance of the IOCommandGate.  This argument will be used as the first parameter in the action callout.
        !            96:     @param action
        !            97:        Pointer to a C function that is called whenever a client of the
        !            98: IOCommandGate calls runCommand.         NB Can be a C++ member function but caller
        !            99: must cast the member function to $link IOCommandGate::Action and they will get a
        !           100: compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
        !           101:     @result True if inherited classes initialise successfully. */
        !           102:     virtual bool init(OSObject *owner, Action action = 0);
        !           103: 
        !           104: /*! @function runCommand
        !           105:     @abstract Single thread a command with the target work-loop.
        !           106:     @discussion Client function that causes the current action to be called in
        !           107: a single threaded manner.  Beware the work-loop's gate is recursive and command
        !           108: gates can cause direct or indirect re-entrancy.         When the executing on a
        !           109: client's thread runCommand will sleep until the work-loop's gate opens for
        !           110: execution of client actions, the action is single threaded against all other
        !           111: work-loop event sources.
        !           112:     @param arg0 Parameter for action of command gate, defaults to 0.
        !           113:     @param arg1 Parameter for action of command gate, defaults to 0.
        !           114:     @param arg2 Parameter for action of command gate, defaults to 0.
        !           115:     @param arg3 Parameter for action of command gate, defaults to 0.
        !           116:     @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this
        !           117: event source is currently disabled, kIOReturnNoResources if no action available.
        !           118: */
        !           119:     virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
        !           120:                                void *arg2 = 0, void *arg3 = 0);
        !           121: 
        !           122: /*! @function runAction
        !           123:     @abstract Single thread a call to an action with the target work-loop.
        !           124:     @discussion Client function that causes the given action to be called in
        !           125: a single threaded manner.  Beware the work-loop's gate is recursive and command
        !           126: gates can cause direct or indirect re-entrancy.         When the executing on a
        !           127: client's thread runCommand will sleep until the work-loop's gate opens for
        !           128: execution of client actions, the action is single threaded against all other
        !           129: work-loop event sources.
        !           130:     @param action Pointer to function to be executed in work-loop context.
        !           131:     @param arg0 Parameter for action of command gate, defaults to 0.
        !           132:     @param arg1 Parameter for action of command gate, defaults to 0.
        !           133:     @param arg2 Parameter for action of command gate, defaults to 0.
        !           134:     @param arg3 Parameter for action of command gate, defaults to 0.
        !           135:     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNoResources if no action available.
        !           136: */
        !           137:     virtual IOReturn runAction(Action action,
        !           138:                               void *arg0 = 0, void *arg1 = 0,
        !           139:                               void *arg2 = 0, void *arg3 = 0);
        !           140: };
        !           141: 
        !           142: #endif /* !_IOKIT_IOCOMMANDGATE_H */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.