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/*! 24 @header IOFireWireSBP2LUN 25 Contains the class definition for IOFireWireSBP2LUN. 26*/ 27 28#ifndef _IOKIT_IOFIREWIRESBP2LUN_H 29#define _IOKIT_IOFIREWIRESBP2LUN_H 30 31#include <IOKit/IOService.h> 32#include <IOKit/IOCommandGate.h> 33 34#include <IOKit/firewire/IOFireWireUnit.h> 35 36#include <IOKit/sbp2/IOFireWireSBP2Login.h> 37#include <IOKit/sbp2/IOFireWireSBP2ManagementORB.h> 38 39class IOFireWireSBP2Target; 40 41/*! 42 @class IOFireWireSBP2LUN 43 @abstract Provider for most drivers. 44 @discussion IOFireWireSBP2LUN objects are created by IOFireWireSBP2Target objects. Each target may have zero or more IOFireWireSBP2LUN children. The LUN object serves as the matching nub for most drivers and therefore will be the provider for most drivers. It supplies the methods that control the operation of the LUN as a whole. Methods that control the behavior and execution of an SBP2 login session are supplied in a separate IOFireWireSBP2Login object. The LUN can be used to create one of these login objects. 45 The LUN can also create IOFireWireSBP2ManagementORBs for configuring and appending non-login related management functions. Login related management functions (ie. Login, Logout, Reconnect) are supplied by the IOFireWireSBP2Login. 46 Finally the LUN can supply a reference to the IOFireWireUnit. This can be useful if a driver wishes to access the standard FireWire APIs. 47*/ 48 49class IOFireWireSBP2LUN : public IOService 50{ 51 OSDeclareDefaultStructors( IOFireWireSBP2LUN ); 52 53 friend class IOFireWireSBP2ManagementORB; 54 friend class IOFireWireSBP2Login; 55 friend class IOFireWireSBP2UserClient; 56 57protected: 58 59 // reserved for future use 60 struct ExpansionData { }; 61 ExpansionData *reserved; 62 63 //////////////////////////////////////////// 64 // methods called by friend classes 65 66 // IOFireWireSBP2Login methods 67 virtual void removeLogin( IOFireWireSBP2Login * login ); 68 virtual IOFireWireSBP2Target * getTarget( void ); 69 70 // IOFireWireSBP2ManagementORB methods 71 virtual void clearAllTasksInSet( void ); // assumes caller is on workloop 72 virtual void removeManagementORB( IOFireWireSBP2ManagementORB * orb ); 73 74 // IOFireWireSBP2UserClient methods 75 virtual void flushAllManagementORBs( void ); 76 77public: 78 79 //////////////////////////////////////////// 80 // IOService overrides 81 82 /*! @function attach 83 @abstract Attaches an IOService client to a provider in the registry. 84 @discussion See IOService for discussion. 85 @param provider The IOService object which will serve as this objects provider. 86 @result false if the provider is inactive or on a resource failure, otherwise true. 87 */ 88 89 virtual bool attach( IOService *provider ); 90 91 /*! @function handleOpen 92 @abstract Overrideable method to control the open / close behaviour of an IOService. 93 @discussion See IOService for discussion. 94 @param forClient Designates the client of the provider requesting the open. 95 @param options Options for the open, may be interpreted by the implementor of handleOpen. 96 @result Return true if the open was successful, false otherwise. */ 97 98 virtual bool handleOpen( IOService * forClient, 99 IOOptionBits options, 100 void * arg ); 101 /*! 102 @function handleClose 103 @abstract Overrideable method to control the open / close behaviour of an IOService. 104 @discussion See IOService for discussion. 105 @param forClient Designates the client of the provider requesting the close. 106 @param options Options for the close, may be interpreted by the implementor of handleOpen. 107 */ 108 109 virtual void handleClose( IOService * forClient, 110 IOOptionBits options ); 111 112 /*! 113 @function matchPropertyTable 114 @abstract Implements SBP2 specific matching. 115 @discussion See IOService for discussion. 116 @param table The dictionary of properties to be matched against. 117 @result Returns false if the family considers the matching dictionary does not match in properties it understands, true otherwise. 118 */ 119 120 virtual bool matchPropertyTable(OSDictionary * table); 121 122protected: 123 124 //////////////////////////////////////////// 125 // private fields 126 127 IOFireWireSBP2Target * fProviderTarget; 128 UInt32 fLUNumber; 129 OSSet * fLoginSet; 130 OSIterator * fLoginSetIterator; 131 IOCommandGate * fGate; 132 OSSet * fORBSet; 133 OSIterator * fORBSetIterator; 134 OSObject * fDiagnostics; 135 136 //////////////////////////////////////////// 137 // private methods 138 139 // IOService methods 140 virtual void free( void ); 141 virtual IOReturn message( UInt32 type, IOService * provider, void * argument = 0 ); 142 143 // create management orb internals 144 static IOReturn staticCreateManagementORBAction( OSObject *self, 145 void * refCon, 146 void * completion, 147 void * orb, 148 void * ); 149 virtual IOReturn createManagementORBAction( void * refCon, 150 FWSBP2ManagementCallback completion, 151 IOFireWireSBP2ManagementORB ** orb ); 152 153 // remove management orb internals 154 static IOReturn staticRemoveManagementORBAction( OSObject * self, void * orb, 155 void *, void *, void * ); 156 virtual IOReturn removeManagementORBAction( IOFireWireSBP2ManagementORB * orb ); 157 158 // flush all management orb internals 159 static IOReturn staticExecuteFlushAllMgmtORBs( OSObject * self, void *, 160 void *, void *, void * ); 161 virtual IOReturn executeFlushAllMgmtORBs( void ); 162 163 // IOFireWireSBP2ManagementORB friend class wrappers 164 virtual bool initMgmtORBWithLUN( IOFireWireSBP2ManagementORB * orb, IOFireWireSBP2LUN * lun, 165 void * refCon, 166 FWSBP2ManagementCallback completion ); 167 168 // IOFireWireSBP2Login friend class wrappers 169 virtual bool initLoginWithLUN( IOFireWireSBP2Login * login, IOFireWireSBP2LUN * lun ); 170 virtual void suspendedNotify( void ); 171 virtual void resumeNotify( void ); 172 173private: 174 175 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 0); 176 177public: 178 179 //////////////////////////////////////////// 180 // client methods 181 182 // getters 183 184 /*! 185 @function getFireWireUnit 186 @abstract Returns an IOFireWireUnit object. 187 @discussion An IOFireWireUnit is the provider of an IOFireWireSBP2Target. In order to 188 use the base FireWire services you will need a reference to the unit. This method 189 returns that reference. 190 @result Returns a pointer to an IOFireWireUnit. 191 */ 192 193 virtual IOFireWireUnit * getFireWireUnit( void ); 194 195 /*! 196 @function getLUNumber 197 @abstract Returns the LUNs number. 198 @discussion Each LUN has a number to uniquely identify it on a device. This method returns 199 this value in a UInt32. 200 @result Returns a UInt32 containing the Logical Unit Number. 201 */ 202 203 virtual UInt32 getLUNumber( void ); 204 205 // factory methods 206 207 /*! 208 @function createLogin 209 @abstract Creates a new IOFireWireSBP2Login object. 210 @discussion Creates a new IOFireWireSBP2Login object for the LUN. Login objects supply most 211 of the SBP2 APIs related to login maintenance and Normal Command ORB execution. 212 @result Returns a pointer to a new IOFireWireSBP2Login. 213 */ 214 215 virtual IOFireWireSBP2Login *createLogin( void ); 216 217 /*! 218 @function createManagementORB 219 @abstract Creates a new IOFireWireSBP2ManagementORB object. 220 @discussion Creates a new IOFireWireSBP2ManagementORB object. Management objects let you 221 execute commands like QueryLogins, LogicalUnitReset, and AbortTask. These commands are 222 configured after they are created here. When they are done executing (after a call to submit) 223 the supplied completion routine will be called with the supplied refcon. Usually this refCon 224 is the "this" pointer of completion method's object. 225 @param refCon The refcon passed to the completion routine. 226 @param completion The completion routine. Called when the ORB finishes execution. 227 @result Returns a pointer to a new IOFireWireSBP2Login. 228 */ 229 230 virtual IOFireWireSBP2ManagementORB * createManagementORB( void * refCon, FWSBP2ManagementCallback completion ); 231 232protected: 233 234 static IOReturn staticCreateLogin( OSObject *self, void * login, void *, void *, void * ); 235 virtual IOReturn createLoginAction( IOFireWireSBP2Login ** login ); 236 237 static IOReturn staticRemoveLoginAction( OSObject *self, void * login, void *, void *, void * ); 238 virtual IOReturn removeLoginAction( IOFireWireSBP2Login * login ); 239 240public: 241 242 /*! 243 @function getDiagnostics 244 @abstract Debug-only method. 245 @discussion Returns a reference to the internal diagnostics object when the services are built 246 in debug mode. Should be a no-op in release builds. 247 @result Returns a pointer to the diagnostics object (if any). 248 */ 249 250 virtual OSObject * getDiagnostics( void ); 251 252 virtual bool finalize( IOOptionBits options ); 253 254protected: 255 256 void terminateNotify( void ); 257 258private: 259 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 1); 260 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 2); 261 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 3); 262 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 4); 263 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 5); 264 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 6); 265 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 7); 266 OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 8); 267 268}; 269 270#endif