| 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 | ␊ |
| 34 | class IOFireWireROMCache;␊ |
| 35 | ␊ |
| 36 | struct IOFWNodeScan;␊ |
| 37 | struct RomScan;␊ |
| 38 | ␊ |
| 39 | class 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 | ␊ |
| 47 | class IOFireWireDeviceAux : public IOFireWireNubAux␊ |
| 48 | {␊ |
| 49 | OSDeclareDefaultStructors(IOFireWireDeviceAux)␊ |
| 50 | ␊ |
| 51 | ␉friend class IOFireWireDevice;␊ |
| 52 | ␉␊ |
| 53 | protected:␊ |
| 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 | ␉␊ |
| 100 | private:␊ |
| 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 | ␊ |
| 116 | class IOFireWireDevice : public IOFireWireNub␊ |
| 117 | {␊ |
| 118 | OSDeclareDefaultStructors(IOFireWireDevice)␊ |
| 119 | ␊ |
| 120 | friend class IOFireWireController;␊ |
| 121 | ␉friend class IOFireWireDeviceAux;␊ |
| 122 | ␊ |
| 123 | protected:␊ |
| 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 | ␊ |
| 159 | public:␊ |
| 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 | ␊ |
| 168 | protected: ␊ |
| 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 | ␊ |
| 175 | public:␊ |
| 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 | ␊ |
| 209 | protected:␊ |
| 210 | ␉virtual IOReturn configureNode( void );␊ |
| 211 | ␊ |
| 212 | public:␊ |
| 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 | ␊ |
| 232 | protected:␊ |
| 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 | ␊ |
| 247 | protected:␊ |
| 248 | ␉virtual IOFireWireNubAux * createAuxiliary( void );␊ |
| 249 | ␊ |
| 250 | public:␊ |
| 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 | ␊ |
| 261 | protected:␊ |
| 262 | ␉inline void setUnitCount( UInt32 count )␊ |
| 263 | ␉␉{ ((IOFireWireDeviceAux*)fAuxiliary)->setUnitCount( count ); }␉␉␊ |
| 264 | ␊ |
| 265 | ␉inline OSSet * getOpenUnitSet( void ) const␊ |
| 266 | ␉␉{ return ((IOFireWireDeviceAux*)fAuxiliary)->getOpenUnitSet(); }␊ |
| 267 | ␉␉␉␊ |
| 268 | public:␊ |
| 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 | ␊ |
| 276 | protected:␊ |
| 277 | ␉inline AbsoluteTime getResumeTime( void )␊ |
| 278 | ␉␉{ return ((IOFireWireDeviceAux*)fAuxiliary)->getResumeTime(); }␉␉␊ |
| 279 | ␊ |
| 280 | ␉inline void latchResumeTime( void )␊ |
| 281 | ␉␉{ ((IOFireWireDeviceAux*)fAuxiliary)->latchResumeTime(); }␉␉␊ |
| 282 | ␉␉␊ |
| 283 | private:␊ |
| 284 | OSMetaClassDeclareReservedUnused(IOFireWireDevice, 0);␊ |
| 285 | OSMetaClassDeclareReservedUnused(IOFireWireDevice, 1);␊ |
| 286 | ␊ |
| 287 | };␊ |
| 288 | ␊ |
| 289 | #endif /* ! _IOKIT_IOFIREWIREDEVICE_H */␊ |
| 290 | |
