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#ifndef _IOKIT_IOFWPSEUDOADDRESSSPACE_H 24#define _IOKIT_IOFWPSEUDOADDRESSSPACE_H 25 26#include <IOKit/firewire/IOFWAddressSpace.h> 27 28/* 29 * If installed, this callback is invoked for drivers which 30 * would like to coalesce incoming writes and do batch processing 31 * of incoming block write packets. 32 * This callback can be installed by calling setARxReqIntCompleteHandler 33 * method in IOFWPseudoAddressSpace object. 34 */ 35typedef void (*IOFWARxReqIntCompleteHandler)( void * refcon ); 36 37/* 38 * Pseudo firewire addresses usually represent emulated registers of some kind. 39 * Accesses to these addresses will result in the owner being notified. 40 * 41 * Virtual addresses should not have zero as the top 16 bits of the 48 bit local address, 42 * since that may look like a physical address to hardware (eg. OHCI). 43 * if reader is NULL then reads will not be allowed. 44 * if writer is NULL then writes will not be allowed. 45 * if either is NULL then lock requests will not be allowed. 46 * refcon is passed back as the first argument of read and write callbacks. 47 */ 48 49class IOFWPseudoAddressSpace; 50 51#pragma mark - 52 53/*! 54 @class IOFWPseudoAddressSpaceAux 55*/ 56 57class IOFWPseudoAddressSpaceAux : public IOFWAddressSpaceAux 58{ 59 OSDeclareDefaultStructors(IOFWPseudoAddressSpaceAux) 60 61 friend class IOFWAddressSpace; 62 friend class IOFWPseudoAddressSpace; 63 friend class IOFireWireController; 64 65protected: 66 67 struct MemberVariables 68 { 69 IOFWARxReqIntCompleteHandler fARxReqIntCompleteHandler; 70 void * fARxReqIntCompleteHandlerRefcon; 71 }; 72 73 MemberVariables * fMembers; 74 75public: 76 77 virtual bool init( IOFWAddressSpace * primary ); 78 virtual void free(); 79 80protected: 81 82 bool createMemberVariables( void ); 83 void destroyMemberVariables( void ); 84 85 virtual void handleARxReqIntComplete(); 86 87public: 88 89/*! @function setARxReqIntCompleteHandler 90 @abstract Installs a callback to receive notification, when FWIM has completed 91 ARxReqInt processing and no incoming packets are left in the queue. 92 @param refcon Client's callback object. 93 @param handler Client callback to be invoked, at the end of interrupt processing. 94 @result none. */ 95 virtual void setARxReqIntCompleteHandler( void * refcon, IOFWARxReqIntCompleteHandler handler ); 96 97 virtual bool intersects( IOFWAddressSpace * space ); 98 99private: 100 101 OSMetaClassDeclareReservedUsed(IOFWPseudoAddressSpaceAux, 0); 102 OSMetaClassDeclareReservedUsed(IOFWPseudoAddressSpaceAux, 1); 103 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 2); 104 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 3); 105 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 4); 106 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 5); 107 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 6); 108 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 7); 109 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 8); 110 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 9); 111 112}; 113 114/*! 115 @class IOFWPseudoAddressSpace 116*/ 117 118class IOFWPseudoAddressSpace : public IOFWAddressSpace 119{ 120 OSDeclareDefaultStructors(IOFWPseudoAddressSpace) 121 122 friend class IOFWPseudoAddressSpaceAux; 123 friend class IOFireWireController; 124 125protected: 126 127 IOMemoryDescriptor* fDesc; 128 void * fRefCon; 129 FWReadCallback fReader; 130 FWWriteCallback fWriter; 131 FWAddress fBase; 132 UInt32 fLen; 133 134/*! @struct ExpansionData 135 @discussion This structure will be used to expand the capablilties of the class in the future. 136 */ 137 struct ExpansionData { }; 138 139/*! @var reserved 140 Reserved for future use. (Internal use only) */ 141 ExpansionData *reserved; 142 143 static OSData * allocatedAddresses; // unused 144 145 virtual void free(); 146 147public: 148 149/*! @function simpleReader 150 @abstract A method for processing an address space read request 151 @param refcon Client's callback object. 152 @param nodeID FireWire Read from nodeID. 153 @param speed at this 'speed'. 154 @param addr with FireWire address 'addr'. 155 @param len read 'len' bytes from nodeID. 156 @param buf points to a memory descriptor containing the packet data. 157 @param offset start from this 'offset' in 'buf'. 158 @param reqrefcon Can be queried for extra info about the request. 159 @result UIn32 returns kFWResponseComplete on success */ 160 static UInt32 simpleReader( 161 void* refcon, 162 UInt16 nodeID, 163 IOFWSpeed & speed, 164 FWAddress addr, 165 UInt32 len, 166 IOMemoryDescriptor** buf, 167 IOByteCount* offset, 168 IOFWRequestRefCon reqrefcon); 169 170/*! @function simpleWriter 171 @abstract A method for processing an address space write request 172 @param refcon Client's callback object. 173 @param nodeID FireWire Write to nodeID. 174 @param speed at this 'speed'. 175 @param addr with FireWire address 'addr'. 176 @param len write 'len' bytes to nodeID. 177 @param buf obtain bytes from location given by 'buf'. 178 @param reqrefcon Can be queried for extra info about the request. 179 @result UIn32 returns kFWResponseComplete on success */ 180 static UInt32 simpleWriter( 181 void* refcon, 182 UInt16 nodeID, 183 IOFWSpeed& speed, 184 FWAddress addr, 185 UInt32 len, 186 const void* buf, 187 IOFWRequestRefCon reqrefcon); 188protected: 189 190 // Get a unique address range 191 IOReturn allocateAddress( 192 FWAddress* addr, 193 UInt32 len); 194 // free address 195 void freeAddress( 196 FWAddress addr, 197 UInt32 len); 198 199public: 200 201 static IOFWPseudoAddressSpace* readWrite( 202 FWAddress addr, 203 UInt32 len, 204 FWReadCallback reader, 205 FWWriteCallback writer, 206 void* refcon); 207 208/*! @function simpleRead 209 @abstract Create an address space object to handle read-only memory (eg. the local ROM) 210 handles everything itself 211 @param bus Points to IOFireWireBus object. 212 @param addr Points to starting address for the Pseudo Address Space. 213 @param len Length of the Pseudo Address Space. 214 @param data The virtual address of the first byte in the memory. 215 @result returns valid IOFWPseudoAddressSpace on success, null on failure */ 216 static IOFWPseudoAddressSpace* simpleRead( 217 IOFireWireBus* bus, 218 FWAddress* addr, 219 UInt32 len, 220 const void* data); 221 222/*! @function simpleReadFixed 223 @abstract Create an address space object to handle fixed read-only memory (eg. the local ROM) 224 handles everything itself 225 @param bus Points to IOFireWireBus object. 226 @param addr Points to starting address for the Pseudo Address Space. 227 @param len Length of the Pseudo Address Space. 228 @param data The virtual address of the first byte in the memory. 229 @result returns valid IOFWPseudoAddressSpace on success, null on failure */ 230 static IOFWPseudoAddressSpace* simpleReadFixed( 231 IOFireWireBus* bus, 232 FWAddress addr, 233 UInt32 len, 234 const void* data); 235 236/*! @function simpleRW 237 @abstract Create an address space object to handle r/w memory 238 handles everything itself 239 @param bus Points to IOFireWireBus object. 240 @param addr Points to starting address for the Pseudo Address Space. 241 @param len Length of the Pseudo Address Space. 242 @param data The virtual address of the first byte in the memory. 243 @result returns valid IOFWPseudoAddressSpace on success, null on failure */ 244 static IOFWPseudoAddressSpace* simpleRW( 245 IOFireWireBus* bus, 246 FWAddress* addr, 247 UInt32 len, 248 void * data); 249 250/*! @function simpleRW 251 @abstract Create an address space object to handle r/w memory 252 handles everything itself 253 @param bus Points to IOFireWireBus object. 254 @param addr Points to starting address for the Pseudo Address Space. 255 @param data The virtual address of the first byte in the memory. 256 @result returns valid IOFWPseudoAddressSpace on success, null on failure */ 257 static IOFWPseudoAddressSpace* simpleRW( 258 IOFireWireBus* bus, 259 FWAddress* addr, 260 IOMemoryDescriptor * data); 261 262/*! @function initAll 263 @abstract Initialize an address space object to handle r/w memory 264 @param bus Points to IOFireWireBus object. 265 @param addr Points to starting address for the Pseudo Address Space. 266 @param len Length of the Pseudo Address Space. 267 @param reader Callback handler for incoming Read. 268 @param writer Callback handler for incoming Write. 269 @param refcon Client's callback object. 270 @result returns true on success, false on failure */ 271 virtual bool initAll( 272 IOFireWireBus* bus, 273 FWAddress* addr, 274 UInt32 len, 275 FWReadCallback reader, 276 FWWriteCallback writer, 277 void* refcon); 278 279/*! @function initFixed 280 @abstract Initialize a fixed address space at top of kCSRRegisterSpaceBaseAddressHi 281 @param bus Points to IOFireWireBus object. 282 @param addr Points to starting address for the Pseudo Address Space. 283 @param reader Callback handler for incoming Read. 284 @param writer Callback handler for incoming Write. 285 @param refcon Client's callback object. 286 @result returns true on success, false on failure */ 287 virtual bool initFixed( 288 IOFireWireBus* bus, 289 FWAddress addr, 290 UInt32 len, 291 FWReadCallback reader, 292 FWWriteCallback writer, 293 void* refcon); 294 295/*! @function doRead 296 @abstract A method for processing an address space read request 297 @param nodeID FireWire Read from nodeID. 298 @param speed at this 'speed'. 299 @param addr with FireWire address 'addr'. 300 @param len read 'len' bytes from nodeID. 301 @param buf points to a memory descriptor containing the packet data. 302 @param offset start from this 'offset' in 'buf'. 303 @param reqrefcon Can be queried for extra info about the request. 304 @result UIn32 returns kFWResponseComplete on success */ 305 virtual UInt32 doRead( 306 UInt16 nodeID, 307 IOFWSpeed & speed, 308 FWAddress addr, 309 UInt32 len, 310 IOMemoryDescriptor ** buf, 311 IOByteCount * offset, 312 IOFWRequestRefCon reqrefcon); 313/*! @function doWrite 314 @abstract A method for processing an address space write request 315 @param nodeID FireWire Write to nodeID. 316 @param speed at this 'speed'. 317 @param addr with FireWire address 'addr'. 318 @param len write 'len' bytes to nodeID. 319 @param buf obtain bytes from location given by 'buf'. 320 @param reqrefcon Can be queried for extra info about the request. 321 @result UIn32 returns kFWResponseComplete on success */ 322 virtual UInt32 doWrite( 323 UInt16 nodeID, 324 IOFWSpeed& speed, 325 FWAddress addr, 326 UInt32 len, 327 const void* buf, 328 IOFWRequestRefCon reqrefcon); 329 330/*! @function contains 331 @abstract returns number of bytes starting at addr in this space 332 @result 0 if it doesn't contain the address 333 */ 334 virtual UInt32 contains(FWAddress addr); 335 336/*! @function simpleRWFixed 337 @abstract Create a Read/Write fixed address space at top of kCSRRegisterSpaceBaseAddressHi. 338 @param control Points to IOFireWireBus object. 339 @param addr Points to starting address for the Pseudo Address Space. 340 @param len Length of the address range. 341 @param data The virtual address of the first byte in the memory. 342 @result returns valid IOFWPseudoAddressSpace on success, null on failure */ 343 static IOFWPseudoAddressSpace * simpleRWFixed( IOFireWireBus *control, FWAddress addr, UInt32 len, const void *data ); 344 345protected: 346 347 virtual IOFWAddressSpaceAux * createAuxiliary( void ); 348 349protected: 350 inline void handleARxReqIntComplete( void ) 351 { ((IOFWPseudoAddressSpaceAux*)fIOFWAddressSpaceExpansion->fAuxiliary)->handleARxReqIntComplete(); } 352 353public: 354/*! @function setARxReqIntCompleteHandler 355 @abstract Installs a callback to receive notification, when FWIM has completed 356 ARxReqInt processing and no incoming packets are left in the queue. 357 @param refcon Client's callback object. 358 @param handler Client callback to be invoked, at the end of interrupt processing. 359 @result none. */ 360 inline void setARxReqIntCompleteHandler( void * refcon, IOFWARxReqIntCompleteHandler handler ) 361 { ((IOFWPseudoAddressSpaceAux*)fIOFWAddressSpaceExpansion->fAuxiliary)->setARxReqIntCompleteHandler( refcon, handler ); } 362 363private: 364 365 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpace, 0); 366 OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpace, 1); 367 368}; 369 370#endif 371