1/* 2 * Copyright (c) 1998-2002 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 /*! @header 23 This header contains the definition of the <code>IOFireWireDevice</code> and <code>IOFireWireDeviceAux</code> classes. 24 An <code>IOFireWireDevice</code> object represents a FireWire device in the I/O Registry. 25 It is strongly recommended that you write applications that access FireWire devices rather than in-kernel device drivers. 26 For more information on how to do this, see {@linkdoc //apple_ref/doc/uid/TP40000969 FireWire Device Interface Guide}. 27 @indexgroup FireWire 28 */ 29#ifndef _IOKIT_IOFIREWIREDEVICE_H 30#define _IOKIT_IOFIREWIREDEVICE_H 31 32#include <IOKit/firewire/IOFireWireNub.h> 33 34class IOFireWireROMCache; 35 36struct IOFWNodeScan; 37struct RomScan; 38 39class IOFireWireDevice; 40 41#pragma mark - 42 43/*! @class IOFireWireDeviceAux 44 @discussion An IOFireWireDeviceAux is for internal use only. You should never subclass IOFireWireDeviceAux 45*/ 46 47class IOFireWireDeviceAux : public IOFireWireNubAux 48{ 49 OSDeclareDefaultStructors(IOFireWireDeviceAux) 50 51 friend class IOFireWireDevice; 52 53protected: 54 55 UInt32 fUnitCount; 56 IOFWSpeed fMaxSpeed; 57 OSSet * fOpenUnitSet; 58 AbsoluteTime fResumeTime; 59 60 /*! 61 @struct ExpansionData 62 @discussion This structure will be used to expand the capablilties of the class in the future. 63 */ 64 65 struct ExpansionData { }; 66 67 /*! 68 @var reserved 69 Reserved for future use. (Internal use only) 70 */ 71 72 ExpansionData * reserved; 73 74 virtual bool init( IOFireWireDevice * primary ); 75 76 virtual void free(); 77 78 virtual bool isTerminated( void ); 79 80 virtual void setTerminationState( TerminationState state ); 81 82 void setMaxSpeed( IOFWSpeed speed ); 83 84 void setUnitCount( UInt32 count ); 85 86 UInt32 getUnitCount( void ); 87 88 bool isPhysicalAccessEnabled( void ); 89 90 virtual IOFWSimpleContiguousPhysicalAddressSpace * createSimpleContiguousPhysicalAddressSpace( vm_size_t size, IODirection direction ); 91 92 virtual IOFWSimplePhysicalAddressSpace * createSimplePhysicalAddressSpace( vm_size_t size, IODirection direction ); 93 94 OSSet * getOpenUnitSet() const; 95 96 void latchResumeTime( void ); 97 98 AbsoluteTime getResumeTime( void ); 99 100private: 101 OSMetaClassDeclareReservedUnused(IOFireWireDeviceAux, 0); 102 OSMetaClassDeclareReservedUnused(IOFireWireDeviceAux, 1); 103 OSMetaClassDeclareReservedUnused(IOFireWireDeviceAux, 2); 104 OSMetaClassDeclareReservedUnused(IOFireWireDeviceAux, 3); 105}; 106 107#pragma mark - 108/*! @class IOFireWireDevice 109 @abstract Represents a FireWire device. 110 @discussion The FireWire family tries to read the configuration ROM of each device on the FireWire bus. For each device that responds with 111 its bus information block, the FireWire family publishes an <code>IOFireWireDevice</code> object in the I/O Registry. An 112 <code>IOFireWireDevice</code> object keeps track of the device's node ID, copies config ROM properties into the object's property 113 list, and scans the config ROM for unit directories, publishing an <code>IOFireWireUnit</code> object for each unit directory it finds. 114*/ 115 116class IOFireWireDevice : public IOFireWireNub 117{ 118 OSDeclareDefaultStructors(IOFireWireDevice) 119 120 friend class IOFireWireController; 121 friend class IOFireWireDeviceAux; 122 123protected: 124 125 enum RegistrationState 126 { 127 kDeviceRegistered, 128 kDeviceNeedsRegisterService, 129 kDeviceNotRegistered 130 }; 131 132 IOFireWireROMCache *fDeviceROM; 133 bool fOpenFromDevice; 134 UInt32 fOpenFromUnitCount; 135 UInt32 fROMGeneration; 136 IORecursiveLock *fROMLock; 137 RegistrationState fRegistrationState; 138 UInt32 fROMReadRetry; 139 140/*! @struct ExpansionData 141 @discussion This structure will be used to expand the capablilties of the class in the future. 142 */ 143 struct ExpansionData { }; 144 145/*! @var reserved 146 Reserved for future use. (Internal use only) */ 147 ExpansionData *reserved; 148 149 static void readROMDirGlue(void *refcon, IOReturn status, 150 IOFireWireNub *device, IOFWCommand *fwCmd); 151 static void readROMThreadFunc(void *arg); 152 153 static void terminateDevice(void *arg); 154 155 void processROM(RomScan *romScan); 156 157 virtual void free(); 158 159public: 160 virtual IOReturn message( UInt32 type, IOService * provider, void * argument ); 161 162 virtual bool handleOpen( IOService * forClient, IOOptionBits options, void * arg ); 163 164 virtual void handleClose( IOService * forClient, IOOptionBits options ); 165 166 virtual bool handleIsOpen( const IOService * forClient ) const; 167 168protected: 169 virtual IOReturn cacheROM(OSData *rom, UInt32 offset, const UInt32 *&romBase); 170 171 virtual const UInt32 * getROMBase(); 172 173 virtual void setNodeROM(UInt32 generation, UInt16 localNodeID, const IOFWNodeScan *info); 174 175public: 176 virtual bool matchPropertyTable(OSDictionary * table); 177 178 /*! @function init 179 @abstract Initializes the nub. 180 @param propTable Property table passed to the standard nub initialization. 181 @param scan Pointer to the node scan structure. 182 @result Returns <code>true</code> if initialization was successful; <code>false</code> otherwise. 183 */ 184 virtual bool init(OSDictionary * propTable, const IOFWNodeScan *scan); 185 186 virtual bool attach(IOService * provider ); 187 188 virtual bool finalize( IOOptionBits options ); 189 190 /*! @function setNodeFlags 191 @abstract Sets the node's characteristics. 192 @param flags Refer to "node flags" in IOFireWireFamilyCommon.h. 193 */ 194 virtual void setNodeFlags( UInt32 flags ); 195 196 /*! @function clearNodeFlags 197 @abstract Resets the node's characteristics. 198 @param flags Refer to "node flags" in IOFireWireFamilyCommon.h. 199 */ 200 virtual void clearNodeFlags( UInt32 flags ); 201 202 /*! @function getNodeFlags 203 @abstract Retrieves the node's characteristics. 204 @param flags Refer to "node flags" in IOFireWireFamilyCommon.h. 205 @result UInt32 The flags set for a particular node. 206 */ 207 virtual UInt32 getNodeFlags( void ); 208 209protected: 210 virtual IOReturn configureNode( void ); 211 212public: 213 /*! @function createPhysicalAddressSpace 214 @abstract Creates local physical FireWire address spaces for the device to access. 215 @param mem Memory area allocated to back the physical access by Link hardware. 216 @result A valid <code>IOFWPhysicalAddressSpace</code> object on success; NULL on failure. 217 */ 218 virtual IOFWPhysicalAddressSpace *createPhysicalAddressSpace(IOMemoryDescriptor *mem); 219 220 /*! @function createPseudoAddressSpace 221 @abstract Creates local pseudo FireWire address spaces for the device to access. 222 @param addr The FireWire address that is mapped to the pseudo address access. 223 @param len Size of the address space to allocate. 224 @param reader Read callback, when the device reads from this address space. 225 @param writer Write callback, when the device writes to this address space. 226 @param refcon Client's callback object returned during reader/writer callbacks. 227 @result A valid <code>IOFWPseudoAddressSpace</code> object on success; NULL on failure. 228 */ 229 virtual IOFWPseudoAddressSpace *createPseudoAddressSpace(FWAddress *addr, UInt32 len, 230 FWReadCallback reader, FWWriteCallback writer, void *refcon); 231 232protected: 233 virtual IOReturn readRootDirectory( IOConfigDirectory * directory, OSDictionary * propTable ); 234 235 virtual IOReturn processRootDirectory( OSDictionary * propTable ); 236 237 virtual IOReturn readUnitDirectories( IOConfigDirectory * directory, OSSet * unitInfo ); 238 239 virtual IOReturn processUnitDirectories( OSSet * unitSet ); 240 241 virtual void setRegistrationState( RegistrationState fRegistrationState ); 242 243 virtual void preprocessDirectories( OSDictionary * rootPropTable, OSSet * unitSet ); 244 245 virtual void configurePhysicalFilter( void ); 246 247protected: 248 virtual IOFireWireNubAux * createAuxiliary( void ); 249 250public: 251 inline bool isTerminated( void ) 252 { return ((IOFireWireDeviceAux*)fAuxiliary)->isTerminated(); } 253 254 /*! @function setMaxSpeed 255 @abstract Sets the maximum speed for this node. 256 @param speed Maximum speed. Refer to "bus speed numbers" in IOFireWireFamilyCommon.h. 257 */ 258 inline void setMaxSpeed( IOFWSpeed speed ) 259 { ((IOFireWireDeviceAux*)fAuxiliary)->setMaxSpeed( speed ); } 260 261protected: 262 inline void setUnitCount( UInt32 count ) 263 { ((IOFireWireDeviceAux*)fAuxiliary)->setUnitCount( count ); } 264 265 inline OSSet * getOpenUnitSet( void ) const 266 { return ((IOFireWireDeviceAux*)fAuxiliary)->getOpenUnitSet(); } 267 268public: 269 /*! @function getUnitCount 270 @abstract Returns number of units attached to this device. 271 @result UInt32 The number of units attached to this device. 272 */ 273 inline UInt32 getUnitCount( void ) 274 { return ((IOFireWireDeviceAux*)fAuxiliary)->getUnitCount(); } 275 276protected: 277 inline AbsoluteTime getResumeTime( void ) 278 { return ((IOFireWireDeviceAux*)fAuxiliary)->getResumeTime(); } 279 280 inline void latchResumeTime( void ) 281 { ((IOFireWireDeviceAux*)fAuxiliary)->latchResumeTime(); } 282 283private: 284 OSMetaClassDeclareReservedUnused(IOFireWireDevice, 0); 285 OSMetaClassDeclareReservedUnused(IOFireWireDevice, 1); 286 287}; 288 289#endif /* ! _IOKIT_IOFIREWIREDEVICE_H */ 290