| 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 | ␊ |
| 23 | /*␊ |
| 24 | *␊ |
| 25 | *␉IOFWAddressSpace.h␊ |
| 26 | *␊ |
| 27 | * Classes which describe addresses in the local node which are accessable to other nodes␊ |
| 28 | * via firewire asynchronous read/write/lock requests.␊ |
| 29 | */␊ |
| 30 | ␊ |
| 31 | #ifndef _IOKIT_IOFWADDRESSSPACE_H␊ |
| 32 | #define _IOKIT_IOFWADDRESSSPACE_H␊ |
| 33 | ␊ |
| 34 | #include <IOKit/IOMemoryDescriptor.h>␊ |
| 35 | #include <IOKit/firewire/IOFireWireFamilyCommon.h>␊ |
| 36 | ␊ |
| 37 | class IOFireWireDevice;␊ |
| 38 | class IOFireWireBus;␊ |
| 39 | class IOFireWireController;␊ |
| 40 | ␊ |
| 41 | typedef void * IOFWRequestRefCon;␊ |
| 42 | ␊ |
| 43 | /*!␉@function␉FWWriteCallback␊ |
| 44 | ␉@abstract␉Callback called when a write request packet is received for␊ |
| 45 | ␉␉␉␉a 'virtual' firewire address.␊ |
| 46 | ␉@param␉␉device␉is the node originating the request␊ |
| 47 | ␉@param␉␉speed␉is the FireWire speed of the request, update it if you need to control␊ |
| 48 | ␉␉␉␉␉␉the speed of the reply, otherwise the response will be the same speed.␊ |
| 49 | ␉@param␉␉addr␉is the address the device is requesting to write to␊ |
| 50 | ␉@param␉␉len␉␉is the number of bytes to write␊ |
| 51 | ␉@param␉␉buf␉␉contains the packet data␊ |
| 52 | ␉@param␉␉requestRefcon␉refcon Can be queried for extra info about the request,␊ |
| 53 | ␉␉␉␉␉␉␉␉using IOFireWireController::isLockRequest(), isQuadRequest()␊ |
| 54 | ␉@result␉␉return:␊ |
| 55 | ␉␉␉␉kFWResponseComplete␉␉␉= 0,␉OK␊ |
| 56 | ␉␉␉␉kFWResponseConflictError␉= 4,␉Resource conflict, may retry␊ |
| 57 | ␉␉␉␉kFWResponseDataError␉␉= 5,␉Data not available␊ |
| 58 | ␉␉␉␉kFWResponseTypeError␉␉= 6,␉Operation not supported␊ |
| 59 | ␉␉␉␉kFWResponseAddressError␉␉= 7␉␉Address not valid in target device */␊ |
| 60 | typedef UInt32 (*FWWriteCallback)(void *refcon, UInt16 nodeID, IOFWSpeed &speed,␊ |
| 61 | FWAddress addr, UInt32 len, const void *buf, IOFWRequestRefCon requestRefcon);␊ |
| 62 | ␊ |
| 63 | /*!␉@function␉FWReadCallback␊ |
| 64 | ␉@abstract␉Callback called when a read request packet is received for␊ |
| 65 | ␉␉␉␉a 'virtual' firewire address.␊ |
| 66 | ␉@param␉␉ nodeID is the node originating the request␊ |
| 67 | ␉@param␉␉speed is the FireWire speed of the request, update it if you need to control␊ |
| 68 | ␉␉␉␉␉␉the speed of the reply, otherwise the response will be the same speed.␊ |
| 69 | ␉@param␉␉addr is the address the device is requesting to read from␊ |
| 70 | ␉@param␉␉len is the number of bytes to read␊ |
| 71 | ␉@param␉␉buf contains the packet data␊ |
| 72 | ␉@param␉␉offset on return points to the offset into *buf of the packet data␊ |
| 73 | ␉@param␉␉requestRefcon refcon to pass back if sending a delayed response. Also can be queried ␊ |
| 74 | ␉␉␉␉␉␉␉␉for extra info about the request␊ |
| 75 | ␉@result␉␉return:␊ |
| 76 | kFWResponsePending␉␉␉= -1,␉Pseudo response, real response sent later.␊ |
| 77 | ␉kFWResponseComplete␉␉␉= 0,␉OK!␊ |
| 78 | ␉kFWResponseConflictError␉= 4,␉Resource conflict, may retry␊ |
| 79 | ␉kFWResponseDataError␉␉= 5,␉Data not available␊ |
| 80 | ␉kFWResponseTypeError␉␉= 6,␉Operation not supported␊ |
| 81 | ␉kFWResponseAddressError␉␉= 7␉␉Address not valid in target device ␊ |
| 82 | ␊ |
| 83 | ␉A return of kFWResponsePending should be followed at some later time by a call to␊ |
| 84 | ␉IOFireWireController::asyncReadResponse␉*/ ␊ |
| 85 | typedef UInt32 (*FWReadCallback)(void *refcon, UInt16 nodeID, IOFWSpeed &speed,␊ |
| 86 | FWAddress addr, UInt32 len, IOMemoryDescriptor **buf,␊ |
| 87 | IOByteCount * offset, IOFWRequestRefCon requestRefcon);␊ |
| 88 | ␊ |
| 89 | class IOFWAddressSpace;␊ |
| 90 | ␊ |
| 91 | #pragma mark -␊ |
| 92 | ␊ |
| 93 | /*! @class IOFWAddressSpaceAux␊ |
| 94 | ␉@discussion An IOFWAddressSpaceAux is for internal use only. You should never subclass IOFWAddressSpaceAux ␊ |
| 95 | */␊ |
| 96 | ␊ |
| 97 | class IOFWAddressSpaceAux : public OSObject␊ |
| 98 | {␊ |
| 99 | OSDeclareDefaultStructors(IOFWAddressSpaceAux)␊ |
| 100 | ␊ |
| 101 | ␉friend class IOFWAddressSpace;␊ |
| 102 | ␉␊ |
| 103 | protected:␊ |
| 104 | ␉␊ |
| 105 | ␉IOFWAddressSpace * ␉␉fPrimary;␊ |
| 106 | ␉IOFireWireController *␉fControl;␊ |
| 107 | ␉␊ |
| 108 | ␉OSSet *␉␉␉␉␉fTrustedNodeSet;␊ |
| 109 | OSIterator *␉␉␉fTrustedNodeSetIterator;␊ |
| 110 | ␉␊ |
| 111 | ␉bool␉␉␉␉␉fExclusive;␊ |
| 112 | ␉␊ |
| 113 | ␉/*! ␊ |
| 114 | ␉␉@struct ExpansionData␊ |
| 115 | ␉␉@discussion This structure will be used to expand the capablilties of the class in the future.␊ |
| 116 | */ ␊ |
| 117 | ␉ ␊ |
| 118 | struct ExpansionData { };␊ |
| 119 | ␊ |
| 120 | ␉/*! ␊ |
| 121 | ␉␉@var reserved␊ |
| 122 | ␉␉Reserved for future use. (Internal use only) ␊ |
| 123 | ␉*/␊ |
| 124 | ␊ |
| 125 | ␉ExpansionData * reserved;␊ |
| 126 | ␊ |
| 127 | virtual bool init( IOFWAddressSpace * primary );␊ |
| 128 | ␉virtual␉void free();␊ |
| 129 | ␊ |
| 130 | ␉virtual bool isTrustedNode( UInt16 nodeID );␊ |
| 131 | ␉virtual void addTrustedNode( IOFireWireDevice * device );␊ |
| 132 | ␉virtual void removeTrustedNode( IOFireWireDevice * device );␊ |
| 133 | ␉virtual void removeAllTrustedNodes( void );␊ |
| 134 | ␊ |
| 135 | ␉bool isExclusive( void );␊ |
| 136 | ␉void setExclusive( bool exclusive );␊ |
| 137 | ␉␊ |
| 138 | ␉virtual bool intersects( IOFWAddressSpace * space );␊ |
| 139 | ␉␉␊ |
| 140 | private:␊ |
| 141 | OSMetaClassDeclareReservedUsed(IOFWAddressSpaceAux, 0);␊ |
| 142 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 1);␊ |
| 143 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 2);␊ |
| 144 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 3);␊ |
| 145 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 4);␊ |
| 146 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 5);␊ |
| 147 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 6);␊ |
| 148 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 7);␊ |
| 149 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 8);␊ |
| 150 | OSMetaClassDeclareReservedUnused(IOFWAddressSpaceAux, 9);␊ |
| 151 | ␉␊ |
| 152 | };␊ |
| 153 | ␊ |
| 154 | #pragma mark -␊ |
| 155 | ␊ |
| 156 | /*␊ |
| 157 | * Base class for FireWire address space objects␊ |
| 158 | */␊ |
| 159 | ␊ |
| 160 | /*! ␊ |
| 161 | ␉@class IOFWAddressSpace␊ |
| 162 | */␊ |
| 163 | ␊ |
| 164 | class IOFWAddressSpace : public OSObject␊ |
| 165 | {␊ |
| 166 | OSDeclareAbstractStructors(IOFWAddressSpace)␊ |
| 167 | ␊ |
| 168 | ␉friend class IOFWAddressSpaceAux;␊ |
| 169 | ␉␊ |
| 170 | protected:␊ |
| 171 | ␊ |
| 172 | ␉IOFireWireController *fControl;␊ |
| 173 | ␊ |
| 174 | ␉/*!␊ |
| 175 | ␉␉@struct ExpansionData␊ |
| 176 | ␉␉@discussion This structure will be used to expand the capablilties of the class in the future.␊ |
| 177 | */ ␊ |
| 178 | ␉ ␊ |
| 179 | struct ExpansionData ␊ |
| 180 | ␉{ ␊ |
| 181 | ␉␉IOFWAddressSpaceAux * fAuxiliary; ␊ |
| 182 | ␉};␊ |
| 183 | ␊ |
| 184 | ␉/*! ␊ |
| 185 | ␉␉@var reserved␊ |
| 186 | ␉␉Reserved for future use. (Internal use only) ␊ |
| 187 | ␉*/␊ |
| 188 | ␉␊ |
| 189 | ExpansionData * fIOFWAddressSpaceExpansion;␊ |
| 190 | ␊ |
| 191 | virtual bool init(IOFireWireBus *bus);␊ |
| 192 | ␉virtual␉void free();␊ |
| 193 | ␊ |
| 194 | public:␊ |
| 195 | ␊ |
| 196 | ␉/*!␉@function␉doRead␊ |
| 197 | ␉␉@abstract␉An abstract method for processing an address space read request␊ |
| 198 | ␉␉@param␉␉nodeID␉FireWire Read from nodeID.␊ |
| 199 | ␉␉@param␉␉speed␉at this 'speed'.␊ |
| 200 | ␉␉@param␉␉addr␉with FireWire address 'addr'.␊ |
| 201 | ␉␉@param␉␉len␉␉read 'len' bytes from nodeID.␊ |
| 202 | ␉␉@param␉␉buf␉␉points to a memory descriptor containing the packet data.␊ |
| 203 | ␉␉@param␉␉offset␉start from this 'offset' in 'buf'.␊ |
| 204 | ␉␉@param␉␉refcon Can be queried for extra info about the request.␊ |
| 205 | ␉␉@result␉␉UIn32␉returns kFWResponseComplete on success */␊ |
| 206 | ␉virtual UInt32 doRead(UInt16 nodeID, IOFWSpeed &speed, FWAddress addr, UInt32 len, ␊ |
| 207 | ␉␉␉␉␉IOMemoryDescriptor **buf, IOByteCount * offset,␊ |
| 208 | IOFWRequestRefCon refcon) = 0;␊ |
| 209 | ␉␉␉␉␉␉ ␊ |
| 210 | ␉/*!␉@function␉doWrite␊ |
| 211 | ␉␉@abstract␉An abstract method for processing an address space write request␊ |
| 212 | ␉␉@param␉␉nodeID␉FireWire Write to nodeID.␊ |
| 213 | ␉␉@param␉␉speed␉at this 'speed'.␊ |
| 214 | ␉␉@param␉␉addr␉with FireWire address 'addr'.␊ |
| 215 | ␉␉@param␉␉len␉␉write 'len' bytes to nodeID.␊ |
| 216 | ␉␉@param␉␉buf␉␉obtain bytes from location given by 'buf'.␊ |
| 217 | ␉␉@param␉␉refcon Can be queried for extra info about the request.␊ |
| 218 | ␉␉@result␉␉UIn32␉returns kFWResponseComplete on success */␊ |
| 219 | virtual UInt32 doWrite(UInt16 nodeID, IOFWSpeed &speed, FWAddress addr, UInt32 len,␊ |
| 220 | const void *buf, IOFWRequestRefCon refcon) = 0;␊ |
| 221 | ␊ |
| 222 | ␉/*!␉@function␉doLock␊ |
| 223 | ␉␉@abstract␉A method for processing a lock request.␊ |
| 224 | ␉␉@param␉␉nodeID␉FireWire Lock request for nodeID.␊ |
| 225 | ␉␉@param␉␉speed␉at this 'speed'.␊ |
| 226 | ␉␉@param␉␉addr␉with FireWire address 'addr'.␊ |
| 227 | ␉␉@param␉␉inlen␉'inlen' bytes to use.␊ |
| 228 | ␉␉@param␉␉newVal␉new value to write at 'addr' location .␊ |
| 229 | ␉␉@param␉␉outLen␉'outLen' bytes for result.␊ |
| 230 | ␉␉@param␉␉oldVal␉old value read from 'addr' location.␊ |
| 231 | ␉␉@param␉␉extType␉Type like kFWExtendedTCodeCompareSwap.␊ |
| 232 | ␉␉@param␉␉refcon Can be queried for extra info about the request.␊ |
| 233 | ␉␉@result␉␉UIn32␉returns kFWResponseComplete on success */␊ |
| 234 | virtual UInt32 doLock(UInt16 nodeID, IOFWSpeed &speed, FWAddress addr, UInt32 inlen,␊ |
| 235 | const UInt32 *newVal, UInt32 &outLen, UInt32 *oldVal,␊ |
| 236 | UInt32 extType, IOFWRequestRefCon refcon);␊ |
| 237 | ␊ |
| 238 | ␉/*!␉@function␉activate␊ |
| 239 | ␉␉@abstract␉Address space is ready for handling requests.␊ |
| 240 | ␉␉@result␉␉IOReturn␊ |
| 241 | ␉␉*/␊ |
| 242 | virtual IOReturn activate();␊ |
| 243 | ␉␊ |
| 244 | ␉/*!␉@function␉deactivate␊ |
| 245 | ␉␉@abstract␉Address space request handler is disabled.␊ |
| 246 | ␉␉@result␉␉none␊ |
| 247 | ␉␉*/␊ |
| 248 | virtual void deactivate();␊ |
| 249 | ␊ |
| 250 | ␉/*!␉@function␉contains␊ |
| 251 | ␉␉@abstract␉returns number of bytes starting at addr in this space␊ |
| 252 | ␉␉@result␉␉0 if it doesn't contain the address␊ |
| 253 | ␉␉*/␊ |
| 254 | virtual UInt32 contains(FWAddress addr);␊ |
| 255 | ␊ |
| 256 | ␉/*!␉@function␉isTrustedNode␊ |
| 257 | ␉␉@abstract␉returns true if the node is added as a trusted node␊ |
| 258 | ␉␉@param␉␉nodeID is the nodeID to verify whether its trusted.␊ |
| 259 | ␉␉@result␉␉false if nodeID is not trusted␊ |
| 260 | ␉␉*/␊ |
| 261 | ␉inline bool isTrustedNode( UInt16 nodeID ) ␊ |
| 262 | ␉␉␉␉{ return fIOFWAddressSpaceExpansion->fAuxiliary->isTrustedNode( nodeID ); }␊ |
| 263 | ␊ |
| 264 | ␉/*!␉@function␉addTrustedNode␊ |
| 265 | ␉␉@abstract␉Add a trusted node.␊ |
| 266 | ␉␉@param␉␉device object pointing to a FireWire node on the bus.␊ |
| 267 | ␉␉@result␉␉none␊ |
| 268 | ␉␉*/␊ |
| 269 | ␉inline void addTrustedNode( IOFireWireDevice * device )␊ |
| 270 | ␉␉␉␉{ fIOFWAddressSpaceExpansion->fAuxiliary->addTrustedNode( device ); }␊ |
| 271 | ␉␊ |
| 272 | ␉/*!␉@function␉removeTrustedNode␊ |
| 273 | ␉␉@abstract␉Remove a trusted node.␊ |
| 274 | ␉␉@param␉␉device object pointing to a FireWire node on the bus.␊ |
| 275 | ␉␉@result␉␉none␊ |
| 276 | ␉␉*/␊ |
| 277 | ␉inline void removeTrustedNode( IOFireWireDevice * device )␊ |
| 278 | ␉␉␉␉{ fIOFWAddressSpaceExpansion->fAuxiliary->removeTrustedNode( device ); }␊ |
| 279 | ␉␉␊ |
| 280 | ␉/*!␉@function␉removeAllTrustedNodes␊ |
| 281 | ␉␉@abstract␉Remove all trusted nodes.␊ |
| 282 | ␉␉@result␉␉none␊ |
| 283 | ␉␉*/␊ |
| 284 | ␉inline void removeAllTrustedNodes( void )␊ |
| 285 | ␉␉␉␉{ fIOFWAddressSpaceExpansion->fAuxiliary->removeAllTrustedNodes(); }␊ |
| 286 | ␊ |
| 287 | ␉/*!␉@function␉isExclusive␊ |
| 288 | ␉␉@abstract␉Checks if an address space wants exclusive control of its address range␊ |
| 289 | ␉␉@result␉␉True if the address space is marked exclusive false otherwise␊ |
| 290 | ␉␉*/␊ |
| 291 | ␊ |
| 292 | ␉inline bool isExclusive( void )␊ |
| 293 | ␉␉{ return fIOFWAddressSpaceExpansion->fAuxiliary->isExclusive(); }␊ |
| 294 | ␊ |
| 295 | ␉/*!␉@function␉setExclusive␊ |
| 296 | ␉␉@abstract␉Sets if this address space requires exclusive control of its address range. Exclusivity should be set before an address space is activated.␊ |
| 297 | ␉␉@param␉␉exclusive True if address space should be exclusive, false otherwise␊ |
| 298 | ␉␉@result␉␉none␊ |
| 299 | ␉*/␊ |
| 300 | ␉␉␊ |
| 301 | ␉inline void setExclusive( bool exclusive )␊ |
| 302 | ␉␉{ fIOFWAddressSpaceExpansion->fAuxiliary->setExclusive( exclusive ); }␊ |
| 303 | ␊ |
| 304 | ␉/*!␉@function␉intersects␊ |
| 305 | ␉␉@abstract␉Checks this address space intersects with the given address range. Currently only supports IOFWPsuedoAddressSpaces.␊ |
| 306 | ␉␉@param␉␉space An address space to compare against␊ |
| 307 | ␉␉@result␉␉True if the address spaces intersect false otherwise␊ |
| 308 | ␉*/␊ |
| 309 | ␉␉␊ |
| 310 | ␉inline bool intersects( IOFWAddressSpace * space )␊ |
| 311 | ␉␉{ return fIOFWAddressSpaceExpansion->fAuxiliary->intersects( space ); }␊ |
| 312 | ␊ |
| 313 | ␉␉␊ |
| 314 | protected:␊ |
| 315 | ␉␊ |
| 316 | ␉virtual IOFWAddressSpaceAux * createAuxiliary( void );␊ |
| 317 | ␊ |
| 318 | private:␊ |
| 319 | OSMetaClassDeclareReservedUsed(IOFWAddressSpace, 0);␊ |
| 320 | OSMetaClassDeclareReservedUsed(IOFWAddressSpace, 1);␊ |
| 321 | ␊ |
| 322 | };␊ |
| 323 | ␊ |
| 324 | // the physical and psuedo address space classes used to be defined here␊ |
| 325 | // for backwards compatibility, we pull them in now. the ifdefs surrounding␊ |
| 326 | // the content of the header files ensures we do not multiply include a header.␊ |
| 327 | ␊ |
| 328 | #include <IOKit/firewire/IOFWPseudoAddressSpace.h>␊ |
| 329 | #include <IOKit/firewire/IOFWPhysicalAddressSpace.h>␊ |
| 330 | ␊ |
| 331 | #endif /* _IOKIT_IOFWADDRESSSPACE */␊ |
| 332 | |
