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 * IOFireWireLib.h 24 * IOFireWireLib 25 * 26 * Created on Thu Apr 27 2000. 27 * Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved. 28 * 29 */ 30 31/*! @header IOFireWireLib.h 32IOFireWireLib is the software used by user space software to communicate with FireWire 33devices and control the FireWire bus. IOFireWireLib is the lowest-level FireWire interface available 34in user space. 35 36To communicate with a device on the FireWire bus, an instance of IOFireWireDeviceInterface (a struct 37which is defined below) is created. The methods of IOFireWireDeviceInterface allow you 38to communicate with the device and create instances of other interfaces which provide extended 39functionality (for example, creation of unit directories on the local machine). 40 41References to interfaces should be kept using the interface reference typedefs defined herein. 42For example, you should use IOFireWireLibDeviceRef to refer to instances of IOFireWireDeviceInterface, 43IOFireWireLibCommandRef to refer to instances of IOFireWireCommandInterface, and so on. 44 45To obtain an IOFireWireDeviceInterface for a device on the FireWire bus, use the function 46IOCreatePlugInInterfaceForService() defined in IOKit/IOCFPlugIn.h. (Note the "i" in "PlugIn" is 47always upper-case.) Quick usage reference:<br> 48<ul> 49 <li>'service' is a reference to the IOKit registry entry of the kernel object 50 (usually of type IOFireWireDevice) representing the device 51 of interest. This reference can be obtained using the functions defined in 52 IOKit/IOKitLib.h.</li> 53 <li>'plugInType' should be CFUUIDGetUUIDBytes(kIOCFPlugInInterfaceID)</li> 54 <li>'interfaceType' should be CFUUIDGetUUIDBytes(kIOFireWireLibTypeID) when using IOFireWireLib</li> 55</ul> 56The interface returned by IOCreatePlugInInterfaceForService() should be deallocated using 57IODestroyPlugInInterface(). Do not call Release() on it. 58 59*/ 60/* 61 $Log: IOFireWireLib.h,v $ 62 Revision 1.78 2010/05/20 22:49:43 calderon 63 Fixes issues with offset argument of pseudo address space read handler being wrong. 64 65 Revision 1.77 2009/10/29 22:28:28 calderon 66 <rdar://7308574> IOFireWireLib.h and IOFireWireLibIsoch.h headerdoc markup patch 67 68 Revision 1.76 2008/12/12 04:43:57 collin 69 user space compare swap command fixes 70 71 Revision 1.75 2008/09/12 23:44:05 calderon 72 <rdar://5971979/> PseudoAddressSpace skips/mangles packets 73 <rdar://5708169/> FireWire synchronous commands' headerdoc missing callback info 74 75 Revision 1.74 2007/11/09 01:39:04 arulchan 76 fix for rdar://5555060 77 78 Revision 1.73 2007/10/16 16:50:21 ayanowit 79 Removed existing "work-in-progress" support for buffer-fill isoch. 80 81 Revision 1.72 2007/06/21 04:08:45 collin 82 *** empty log message *** 83 84 Revision 1.71 2007/05/12 01:10:45 arulchan 85 Asyncstream transmit command interface 86 87 Revision 1.70 2007/05/03 01:21:29 arulchan 88 Asyncstream transmit APIs 89 90 Revision 1.69 2007/04/28 02:54:23 collin 91 *** empty log message *** 92 93 Revision 1.68 2007/04/28 01:42:35 collin 94 *** empty log message *** 95 96 Revision 1.67 2007/04/11 03:37:41 collin 97 *** empty log message *** 98 99 Revision 1.66 2007/04/05 22:32:09 collin 100 *** empty log message *** 101 102 Revision 1.65 2007/03/23 01:47:17 collin 103 *** empty log message *** 104 105 Revision 1.64 2007/03/22 00:30:00 collin 106 *** empty log message *** 107 108 Revision 1.63 2007/03/14 02:29:35 collin 109 *** empty log message *** 110 111 Revision 1.62 2007/03/06 06:30:05 collin 112 *** empty log message *** 113 114 Revision 1.61 2007/03/06 04:50:21 collin 115 *** empty log message *** 116 117 Revision 1.60 2007/03/03 05:52:20 collin 118 *** empty log message *** 119 120 Revision 1.59 2007/03/03 04:47:15 collin 121 *** empty log message *** 122 123 Revision 1.58 2007/02/16 19:09:15 arulchan 124 *** empty log message *** 125 126 Revision 1.57 2007/02/16 17:41:00 ayanowit 127 More Leopard changes. 128 129 Revision 1.56 2007/02/15 22:02:38 ayanowit 130 More fixes for new IRMAllocation stuff. 131 132 Revision 1.55 2007/02/14 22:43:34 collin 133 *** empty log message *** 134 135 Revision 1.54 2007/02/10 02:40:58 collin 136 *** empty log message *** 137 138 Revision 1.53 2007/02/09 20:36:46 ayanowit 139 More Leopard IRMAllocation changes. 140 141 Revision 1.52 2007/01/17 23:22:40 collin 142 *** empty log message *** 143 144 Revision 1.51 2007/01/17 03:46:27 collin 145 *** empty log message *** 146 147 Revision 1.50 2007/01/11 04:34:18 collin 148 *** empty log message *** 149 150 Revision 1.49 2007/01/04 04:07:25 collin 151 *** empty log message *** 152 153 Revision 1.48 2006/12/22 05:15:13 collin 154 *** empty log message *** 155 156 Revision 1.47 2006/12/22 03:50:40 collin 157 *** empty log message *** 158 159 Revision 1.46 2006/12/06 00:01:10 arulchan 160 Isoch Channel 31 Generic Receiver 161 162 Revision 1.45 2006/10/26 00:39:16 calderon 163 Changed headerdoc to specify release() need on GetConfigDirectory 164 165 Revision 1.44 2006/09/28 23:50:05 collin 166 *** empty log message *** 167 168 Revision 1.43 2006/09/28 22:47:06 ayanowit 169 Another tweak to new APIs. 170 171 Revision 1.42 2006/09/28 22:31:31 arulchan 172 New Feature rdar::3413505 173 174 Revision 1.41 2006/09/27 22:42:12 ayanowit 175 Merged in Leopard changes for new IRMAllocation API. 176 177 Revision 1.40 2006/09/22 06:45:19 collin 178 *** empty log message *** 179 180 Revision 1.39 2004/06/10 20:57:37 niels 181 *** empty log message *** 182 183 Revision 1.38 2004/05/04 22:52:20 niels 184 *** empty log message *** 185 186 Revision 1.37 2004/04/19 21:51:49 niels 187 Revision 1.36 2004/03/25 00:00:24 niels 188 fix panic allocating large physical address spaces 189 190 Revision 1.35 2004/02/27 21:02:20 calderon 191 Changed headerdoc abstract of function "GetSpeedBetweenNodes" from "Get 192 maximum transfer speed to device to which this interface is attached." to 193 "Get the maximum transfer speed between nodes 'srcNodeID' and 'destNodeID'." 194 195 Revision 1.34 2003/11/20 19:14:08 niels 196 Revision 1.33 2003/11/07 21:24:28 niels 197 Revision 1.32 2003/11/07 21:01:19 niels 198 Revision 1.31 2003/09/10 23:01:48 collin 199 Revision 1.30 2003/09/06 01:37:24 collin 200 Revision 1.29 2003/08/25 08:39:17 niels 201 Revision 1.28 2003/08/08 21:03:47 gecko1 202 Merge max-rec clipping code into TOT 203 204 Revision 1.27 2003/07/21 06:53:10 niels 205 merge isoch to TOT 206 207 Revision 1.26.14.2 2003/07/18 00:17:47 niels 208 Revision 1.26.14.1 2003/07/01 20:54:23 niels 209 isoch merge 210 211 Revision 1.26 2002/11/06 23:44:21 wgulland 212 Update header doc for CreateLocalIsochPort 213 214 Revision 1.25 2002/09/25 00:27:33 niels 215 flip your world upside-down 216 217 Revision 1.24 2002/09/12 22:41:55 niels 218 add GetIRMNodeID() to user client 219 220*/ 221 222#ifndef __IOFireWireLib_H__ 223#define __IOFireWireLib_H__ 224 225#ifndef KERNEL 226#include <CoreFoundation/CoreFoundation.h> 227#include <IOKit/IOCFPlugIn.h> 228#include <IOKit/firewire/IOFireWireFamilyCommon.h> 229 230// ============================================================ 231// plugin loading 232// ============================================================ 233 234#pragma mark IOFIREWIRELIB TYPE UUID 235// uuid string: CDCFCA94-F197-11D4-87E6-000502072F80 236#define kIOFireWireLibTypeID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 237 0xCD, 0xCF, 0xCA, 0x94, 0xF1, 0x97, 0x11, 0xD4,\ 238 0x87, 0xE6, 0x00, 0x05, 0x02, 0x07, 0x2F, 0x80) 239 240#pragma mark - 241#pragma mark DEVICE/UNIT/NUB INTERFACE UUIDs 242// ============================================================ 243// device/unit/nub interfaces (newest first) 244// ============================================================ 245 246// 247// version 9 // 10.5 Leopard 248// 249// kIOFireWireDeviceInterface_v9 250// uuid: EE0A94D7-29B4-4D76-A857-57CA477C73B1 251#define kIOFireWireDeviceInterfaceID_v9 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 252 0xEE, 0x0A, 0x94, 0xD7, 0x29, 0xB4, 0x4D, 0x76, \ 253 0xA8, 0x57, 0x57, 0xCA, 0x47, 0x7C, 0x73, 0xB1 ) 254 255// 256// version 8 257// 258// kIOFireWireDeviceInterface_v8 259// uuid: 22A258BB-A859-11D8-AA56-000A95992A78 260#define kIOFireWireDeviceInterfaceID_v8 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 261 0x22, 0xA2, 0x58, 0xBB, 0xA8, 0x59, 0x11, 0xD8, \ 262 0xAA, 0x56, 0x00, 0x0A, 0x95, 0x99, 0x2A, 0x78 ) 263 264// 265// version 7 266// 267// kIOFireWireDeviceInterface_v7 268// uuid: 188517DE-10B4-11D8-B5CC-000393CFACEA 269#define kIOFireWireDeviceInterfaceID_v7 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 270 0x18, 0x85, 0x17, 0xDE, 0x10, 0xB4, 0x11, 0xD8,\ 271 0xB5, 0xCC, 0x00, 0x03, 0x93, 0xCF, 0xAC, 0xEA ) 272 273// 274// version 6 (obsolete) 275// 276 277// kIOFireWireDeviceInterface_v6 278// uuid: C2AB2F11-45E2-11D7-815C-000393470256 279#define kIOFireWireDeviceInterfaceID_v6 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 280 0xC2, 0xAB, 0x2F, 0x11, 0x45, 0xE2, 0x11, 0xD7,\ 281 0x81, 0x5C, 0x00, 0x03, 0x93, 0x47, 0x02, 0x56 ) 282 283// 284// version 5 interfaces (obsolete) 285// 286// 287// kIOFireWireNubInterface_v5 288// uuid string: D4900C5A-C69E-11D6-AEA5-0003938BEB0A 289#define kIOFireWireNubInterfaceID_v5 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 290 0xD4, 0x90, 0x0C, 0x5A, 0xC6, 0x9E, 0x11, 0xD6,\ 291 0xAE, 0xA5, 0x00, 0x03, 0x93, 0x8B, 0xEB, 0x0A ) 292// kIOFireWireUnitInterfaceID_v5 293// uuid string: 121D7347-C69F-11D6-9B31-0003938BEB0A 294#define kIOFireWireUnitInterfaceID_v5 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 295 0x12, 0x1D, 0x73, 0x47, 0xC6, 0x9F, 0x11, 0xD6,\ 296 0x9B, 0x31, 0x00, 0x03, 0x93, 0x8B, 0xEB, 0x0A ) 297// kIOFireWireDeviceInterfaceID_v5 298// uuid string: 127A12F6-C69F-11D6-9D11-0003938BEB0A 299#define kIOFireWireDeviceInterfaceID_v5 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 300 0x12, 0x7A, 0x12, 0xF6, 0xC6, 0x9F, 0x11, 0xD6,\ 301 0x9D, 0x11, 0x00, 0x03, 0x93, 0x8B, 0xEB, 0x0A ) 302 303// 304// version 4 interfaces (obsolete) 305// 306// availability: 307// Mac OS X 10.2 "Jaguar" and later 308// 309// kIOFireWireNubInterface_v4 310// uuid string: 939151B8-6945-11D6-BEC7-0003933F84F0 311#define kIOFireWireNubInterfaceID_v4 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 312 0x93, 0x91, 0x51, 0xB8, 0x69, 0x45, 0x11, 0xD6,\ 313 0xBE, 0xC7, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 314 315// kIOFireWireUnitInterface_v4 316// uuid string: D1A395C9-6945-11D6-9B32-0003933F84F0 317#define kIOFireWireUnitInterfaceID_v4 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 318 0xD1, 0xA3, 0x95, 0xC9, 0x69, 0x45, 0x11, 0xD6,\ 319 0x9B, 0x32, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 320 321// kIOFireWireDeviceInterface_v4 322// uuid string: F4B3748B-6945-11D6-8299-0003933F84F0 323#define kIOFireWireDeviceInterfaceID_v4 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 324 0xF4, 0xB3, 0x74, 0x8B, 0x69, 0x45, 0x11, 0xD6,\ 325 0x82, 0x99, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 326 327// 328// version 3 interfaces (obsolete) 329// 330// availability: 331// Mac OS X 10.2 "Jaguar" and later 332// 333 334// kIOFireWireNubInterfaceID_v3 335// uuid string: F70FE149-E393-11D5-958A-0003933F84F0 336#define kIOFireWireNubInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 337 0xF7, 0x0F, 0xE1, 0x49, 0xE3, 0x93, 0x11, 0xD5,\ 338 0x95, 0x8A, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 339 340// kIOFireWireUnitInterfaceID_v3 341// uuid string: FE7A02EB-E393-11D5-8A61-0003933F84F0 342#define kIOFireWireUnitInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 343 0xFE, 0x7A, 0x02, 0xEB, 0xE3, 0x93, 0x11, 0xD5,\ 344 0x8A, 0x61, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 345 346// kIOFireWireDeviceInterfaceID_v3 347// uuid string: 00EB71A0-E394-11D5-829A-0003933F84F0 348#define kIOFireWireDeviceInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 349 0x00, 0xEB, 0x71, 0xA0, 0xE3, 0x94, 0x11, 0xD5,\ 350 0x82, 0x9A, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 351 352// 353// version 2 interfaces (obsolete) 354// 355// availability: 356// Mac OS X 10.1 and later 357// 358 359// kIOFireWireNubInterfaceID 360// uuid string: 2575E4C4-B6C1-11D5-8F73-003065AF75CC 361#define kIOFireWireNubInterfaceID CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 362 0x25, 0x75, 0xE4, 0xC4, 0xB6, 0xC1, 0x11, 0xD5,\ 363 0x8F, 0x73, 0x00, 0x30, 0x65, 0xAF, 0x75, 0xCC ) 364 365// kIOFireWireUnitInterfaceID 366// uuid string: A02CC5D4-B6C1-11D5-AEA8-003065AF75CC 367#define kIOFireWireUnitInterfaceID CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 368 0xA0, 0x2C, 0xC5, 0xD4, 0xB6, 0xC1, 0x11, 0xD5,\ 369 0xAE, 0xA8, 0x00, 0x30, 0x65, 0xAF, 0x75, 0xCC ) 370 371// kIOFireWireDeviceInterfaceID_v2 372// uuid string: B3993EB8-56E2-11D5-8BD0-003065423456 373#define kIOFireWireDeviceInterfaceID_v2 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 374 0xB3, 0x99, 0x3E, 0xB8, 0x56, 0xE2, 0x11, 0xD5,\ 375 0x8B, 0xD0, 0x00, 0x30, 0x65, 0x42, 0x34, 0x56) 376 377// 378// version 1 interfaces (obsolete) 379// 380// availablity: 381// Mac OS X 10.0.0 and later 382// 383 384// kIOFireWireDeviceInterfaceID 385// (obsolete: do not use. may be removed in the future.) 386// uuid string: E3DF4460-F197-11D4-8AC8-000502072F80 387#define kIOFireWireDeviceInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 388 0xE3, 0xDF, 0x44, 0x60, 0xF1, 0x97, 0x11, 0xD4,\ 389 0x8A, 0xC8, 0x00, 0x05, 0x02, 0x07, 0x2F, 0x80) 390 391#pragma mark - 392#pragma mark COMMAND OBJECT UUIDs 393// ============================================================ 394// command objects 395// ============================================================ 396 397// version 3 interfaces: 398// 399// availability: 400// Mac OS X "Leopard" and later 401// 402 403// uuid string : 18B932AA-697A-4C7E-8F22-80EE746773A9 404#define kIOFireWireAsyncStreamCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault, \ 405 0x18, 0xB9, 0x32, 0xAA, 0x69, 0x7A, 0x4C, 0x7E, \ 406 0x8F, 0x22, 0x80, 0xEE, 0x74, 0x67, 0x73, 0xA9 ) 407 408 409// uuid string : F3FF3AC6-FE88-47A0-ACB7-509009808128 410#define kIOFireWirePHYCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 411 0xF3, 0xFF, 0x3A, 0xC6, 0xFE, 0x88, 0x47, 0xA0, \ 412 0xAC, 0xB7, 0x50, 0x90, 0x09, 0x80, 0x81, 0x28 ) 413 414// uuid string : FAF5529D-9F99-42CB-B0E8-67860807F551 415#define kIOFireWireVectorCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 416 0xFA, 0xF5, 0x52, 0x9D, 0x9F, 0x99, 0x42, 0xCB,\ 417 0xB0, 0xE8, 0x67, 0x86, 0x08, 0x07, 0xF5, 51) 418 419// uuid: 12DE8E37-0BE4-4094-882F-FD0B932A3174 420#define kIOFireWireIRMAllocationInterfaceID CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 421 0x12, 0xDE, 0x8E, 0x37, 0x0B, 0xE4, 0x40, 0x94, \ 422 0x88, 0x2F, 0xFD, 0x0B, 0x93, 0x2A, 0x31, 0x74 ) 423 424// uuid string: 577B1AFE-1A48-4137-8993-71077820E0CD 425#define kIOFireWireCommandInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 426 0x57, 0x7B, 0x1A, 0xFE, 0x1A, 0x48, 0x41, 0x37,\ 427 0x89, 0x93, 0x71, 0x07, 0x78, 0x20, 0xE0, CD ) 428 429// uuid string: 30FB7D2A-FF2E-4236-871B-2A473B0B7B3B 430#define kIOFireWireReadCommandInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 431 0x30, 0xFB, 0x7D, 0x2A, 0xFF, 0x2E, 0x42, 0x36,\ 432 0x87, 0x1B, 0x2A, 0x47, 0x3B, 0x0B, 0x7B, 0x3B ) 433 434// uuid string: EF55343D-40A4-4007-BF99-DF1413251309 435#define kIOFireWireWriteCommandInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 436 0xEF, 0x55, 0x34, 0x3D, 0x40, 0xA4, 0x40, 0x07,\ 437 0xBF, 0x99, 0xDF, 0x14, 0x13, 0x25, 0x13, 0x09 ) 438 439// uuid string: 037F5D98-F5F9-4FBF-9267-4B9BFE9642D6 440#define kIOFireWireCompareSwapCommandInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 441 0x03, 0x7F, 0x5D, 0x98, 0xF5, 0xF9, 0x4F, 0xBF,\ 442 0x92, 0x67, 0x4B, 0x9B, 0xFE, 0x96, 0x42, 0xD6 ) 443// 444// version 2 interfaces: 445// 446// availability: 447// Mac OS X "Jaguar" and later 448// 449 450// kIOFireWireCompareSwapCommandInterfaceID_v2 451// uuid string: 6100FEC9-6946-11D6-8A49-0003933F84F0 452#define kIOFireWireCompareSwapCommandInterfaceID_v2 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 453 0x61, 0x00, 0xFE, 0xC9, 0x69, 0x46, 0x11, 0xD6,\ 454 0x8A, 0x49, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 455 456// 457// version 1 interfaces (obsolete) 458// 459 460// uuid string: F8B6993A-F197-11D4-A3F1-000502072F80 461#define kIOFireWireCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 462 0xF8, 0xB6, 0x99, 0x3A, 0xF1, 0x97, 0x11, 0xD4,\ 463 0xA3, 0xF1, 0x00, 0x05, 0x02, 0x07, 0x2F, 0x80) 464 465// uuid string: AB26F124-76E9-11D5-86D5-003065423456 466#define kIOFireWireReadCommandInterfaceID_v2 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 467 0xAB, 0x26, 0xF1, 0x24, 0x76, 0xE9, 0x11, 0xD5,\ 468 0x86, 0xD5, 0x00, 0x30, 0x65, 0x42, 0x34, 0x56) 469 470// uuid string: 1023605C-76EA-11D5-B82A-003065423456 471#define kIOFireWireWriteCommandInterfaceID_v2 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 472 0x10, 0x23, 0x60, 0x5C, 0x76, 0xEA, 0x11, 0xD5,\ 473 0xB8, 0x2A, 0x00, 0x30, 0x65, 0x42, 0x34, 0x56) 474 475// uuid string: 70C10E38-F64A-11D4-AFE7-0050E4D93B36 476#define kIOFireWireCompareSwapCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 477 0x70, 0xC1, 0x0E, 0x38, 0xF6, 0x4A, 0x11, 0xD4,\ 478 0xAF, 0xE7, 0x00, 0x50, 0xE4, 0xD9, 0x3B, 0x36) 479 480// obsolete: do not use. may be removed in the future. 481// uuid string: 3D72672A-F64A-11D4-9683-0050E4D93B36 482#define kIOFireWireReadQuadletCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 483 0x3D, 0x72, 0x67, 0x2A, 0xF6, 0x4A, 0x11, 0xD4,\ 484 0x96, 0x83, 0x00, 0x50, 0xE4, 0xD9, 0x3B, 0x36) 485 486// obsolete: do not use. may be removed in the future. 487// uuid string: 5C9423CE-F64A-11D4-AB7B-0050E4D93B36 488#define kIOFireWireWriteQuadletCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 489 0x5C, 0x94, 0x23, 0xCE, 0xF6, 0x4A, 0x11, 0xD4,\ 490 0xAB, 0x7B, 0x00, 0x50, 0xE4, 0xD9, 0x3B, 0x3) 491 492// obsolete: do not use. may be removed in the future. 493// uuid string: 6E32F9D4-F63A-11D4-A194-003065423456 494#define kIOFireWireReadCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 495 0x6E, 0x32, 0xF9, 0xD4, 0xF6, 0x3A, 0x11, 0xD4,\ 496 0xA1, 0x94, 0x00, 0x30, 0x65, 0x42, 0x34, 0x56) 497 498// obsolete: do not use. may be removed in the future. 499// uuid string: 4EDDED10-F64A-11D4-B7A5-0050E4D93B36 500#define kIOFireWireWriteCommandInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 501 0x4E, 0xDD, 0xED, 0x10, 0xF6, 0x4A, 0x11, 0xD4,\ 502 0xB7, 0xA5, 0x00, 0x50, 0xE4, 0xD9, 0x3B, 0x36) 503 504#pragma mark - 505#pragma mark ADDRESS SPACE UUIDs 506// ============================================================ 507// address spaces 508// ============================================================ 509 510// uuid string: 0D32AC50-F198-11D4-8DB5-000502072F80 511#define kIOFireWirePseudoAddressSpaceInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 512 0x0D, 0x32, 0xAC, 0x50, 0xF1, 0x98, 0x11, 0xD4,\ 513 0x8D, 0xB5, 0x00, 0x05, 0x02, 0x07, 0x2F, 0x80) 514 515// uuid string: 489110F6-F198-11D4-8BEB-000502072F80 516#define kIOFireWirePhysicalAddressSpaceInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 517 0x48, 0x91, 0x10, 0xF6, 0xF1, 0x98, 0x11, 0xD4,\ 518 0x8B, 0xEB, 0x00, 0x05, 0x02, 0x07, 0x2F, 0x80) 519 520 521// uuid string: 763F18CA-5E84-4612-A2BD-10011730E131 522#define kIOFireWirePHYPacketListenerInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 523 0x76, 0x3F, 0x18, 0xCA, 0x5E, 0x84, 0x46, 0x12,\ 524 0xA2, 0xBD, 0x10, 0x01, 0x17, 0x30, 0xE1, 0x31) 525 526#pragma mark - 527#pragma mark CONFIG ROM UUIDs 528// ============================================================ 529// config ROM 530// ============================================================ 531 532// uuid string: 69CA4D74-F198-11D4-B325-000502072F80 533#define kIOFireWireLocalUnitDirectoryInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 534 0x69, 0xCA, 0x4D, 0x74, 0xF1, 0x98, 0x11, 0xD4,\ 535 0xB3, 0x25, 0x00, 0x05, 0x02, 0x07, 0x2F, 0x80) 536 537// uuid string: 7D43B506-F198-11D4-AA10-000502072F80 538#define kIOFireWireConfigDirectoryInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 539 0x7D, 0x43, 0xB5, 0x06, 0xF1, 0x98, 0x11, 0xD4,\ 540 0xAA, 0x10, 0x00, 0x05, 0x02, 0x07, 0x2F, 0x80) 541 542#pragma mark - 543#pragma mark INTERFACE TYPES 544// ============================================================ 545// IOFireWireLib interface types 546// ============================================================ 547 548typedef struct IOFireWireDeviceInterface_t** IOFireWireLibDeviceRef ; 549typedef IOFireWireLibDeviceRef IOFireWireLibUnitRef ; 550typedef IOFireWireLibDeviceRef IOFireWireLibNubRef ; 551typedef struct IOFireWirePseudoAddressSpaceInterface_t** IOFireWireLibPseudoAddressSpaceRef ; 552typedef struct IOFireWirePhysicalAddressSpaceInterface_t** IOFireWireLibPhysicalAddressSpaceRef ; 553typedef struct IOFireWireLocalUnitDirectoryInterface_t** IOFireWireLibLocalUnitDirectoryRef ; 554typedef struct IOFireWireConfigDirectoryInterface_t** IOFireWireLibConfigDirectoryRef ; 555 556typedef struct IOFireWireCommandInterface_t** IOFireWireLibCommandRef ; 557typedef struct IOFireWireReadCommandInterface_t** IOFireWireLibReadCommandRef ; 558typedef struct IOFireWireReadQuadletCommandInterface_t** IOFireWireLibReadQuadletCommandRef ; 559typedef struct IOFireWireWriteCommandInterface_t** IOFireWireLibWriteCommandRef ; 560typedef struct IOFireWireWriteQuadletCommandInterface_t** IOFireWireLibWriteQuadletCommandRef ; 561typedef struct IOFireWireCompareSwapCommandInterface_t** IOFireWireLibCompareSwapCommandRef ; 562typedef struct IOFireWireLibVectorCommandInterface_t** IOFireWireLibVectorCommandRef; 563typedef struct IOFireWirePHYCommandInterface_t** IOFireWireLibPHYCommandRef; 564typedef struct IOFireWireAsyncStreamCommandInterface_t** IOFireWireLibAsyncStreamCommandRef; 565 566typedef struct IOFireWireCompareSwapCommandInterface_v3_t** IOFireWireLibCompareSwapCommandV3Ref ; 567 568typedef struct IOFireWireLibIRMAllocationInterface_t** IOFireWireLibIRMAllocationRef ; 569 570// --- isoch interfaces ---------- 571typedef struct IOFireWireIsochChannelInterface_t** IOFireWireLibIsochChannelRef ; 572typedef struct IOFireWireIsochPortInterface_t** IOFireWireLibIsochPortRef ; 573typedef struct IOFireWireRemoteIsochPortInterface_t** IOFireWireLibRemoteIsochPortRef ; 574typedef struct IOFireWireLocalIsochPortInterface_t** IOFireWireLibLocalIsochPortRef ; 575typedef struct IOFireWireDCLCommandPoolInterface_t** IOFireWireLibDCLCommandPoolRef ; 576typedef struct IOFireWireNuDCLPoolInterface_t** IOFireWireLibNuDCLPoolRef ; 577typedef struct IOFWAsyncStreamListenerInterface_t** IOFWAsyncStreamListenerInterfaceRef; 578typedef struct IOFireWireLibPHYPacketListenerInterface_t** IOFireWireLibPHYPacketListenerRef; 579 580#pragma mark - 581#pragma mark CALLBACK TYPES 582// ============================================================ 583// IOFireWireLib callback types 584// ============================================================ 585 586/*! @typedef IOFireWirePseudoAddressSpaceReadHandler 587 @abstract This callback is called to handle read requests to pseudo address spaces. This function 588 should fill in the specified area in the pseudo address space backing store and call 589 ClientCommandIsComplete with the specified command ID 590 @param addressSpace The address space to which the request is being made 591 @param commandID An FWClientCommandID which should be passed to ClientCommandIsComplete when 592 the buffer has been filled in 593 @param packetLen number of bytes requested 594 @param packetOffset number of bytes from beginning of address space backing store 595 @param srcNodeID nodeID of the requester 596 @param destAddressHi high 16 bits of destination address on this computer 597 @param destAddressLo low 32 bits of destination address on this computer 598 @param refCon user specified reference number passed in when the address space was created 599*/ 600typedef UInt32 (*IOFireWirePseudoAddressSpaceReadHandler)( 601 IOFireWireLibPseudoAddressSpaceRef addressSpace, 602 FWClientCommandID commandID, 603 UInt32 packetLen, 604 UInt32 packetOffset, 605 UInt16 srcNodeID, // nodeID of requester 606 UInt32 destAddressHi, // destination on this node 607 UInt32 destAddressLo, 608 void * refCon) ; 609 610/*! @typedef IOFireWirePseudoAddressSpaceSkippedPacketHandler 611 @abstract Callback called when incoming packets have been dropped from the internal queue 612 @param addressSpace The address space which dropped the packet(s) 613 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 614 @param skippedPacketCount The number of skipped packets 615*/ 616typedef void (*IOFireWirePseudoAddressSpaceSkippedPacketHandler)( 617 IOFireWireLibPseudoAddressSpaceRef addressSpace, 618 FWClientCommandID commandID, 619 UInt32 skippedPacketCount) ; 620 621/*! @typedef IOFireWirePseudoAddressSpaceWriteHandler 622 @abstract Callback called to handle write requests to a pseudo address space. 623 @param addressSpace The address space to which the write is being made 624 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 625 @param packetLen Length in bytes of incoming packet 626 @param packet Pointer to the received data 627 @param srcNodeID Node ID of the sender 628 @param destAddressHi high 16 bits of destination address on this computer 629 @param destAddressLo low 32 bits of destination address on this computer 630 @param refCon user specified reference number passed in when the address space was created 631*/ 632typedef UInt32 (*IOFireWirePseudoAddressSpaceWriteHandler)( 633 IOFireWireLibPseudoAddressSpaceRef addressSpace, 634 FWClientCommandID commandID, 635 UInt32 packetLen, 636 void* packet, 637 UInt16 srcNodeID, // nodeID of sender 638 UInt32 destAddressHi, // destination on this node 639 UInt32 destAddressLo, 640 void * refCon) ; 641 642/*! @typedef IOFireWireBusResetHandler 643 @abstract Called when a bus reset has occured, but before FireWire has completed 644 configuring the bus. 645 @param interface A reference to the device on which the callback was installed 646 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 647*/ 648typedef void (*IOFireWireBusResetHandler)( 649 IOFireWireLibDeviceRef interface, 650 FWClientCommandID commandID ); // parameters may change 651 652/*! 653 @typedef IOFireWireBusResetDoneHandler 654 @abstract Called when a bus reset has occured and FireWire has completed configuring 655 the bus. 656 @param interface A reference to the device on which the callback was installed 657 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 658*/ 659typedef void (*IOFireWireBusResetDoneHandler)( 660 IOFireWireLibDeviceRef interface, 661 FWClientCommandID commandID ) ; // parameters may change 662 663/*! @typedef IOFireWireLibCommandCallback 664 @abstract Callback called when an asynchronous command has completed executing 665 @param refCon A user specified reference value set before command object was submitted 666*/ 667typedef void (*IOFireWireLibCommandCallback)( 668 void* refCon, 669 IOReturn completionStatus) ; 670 671/*! @typedef IOFireWireLibPHYPacketCallback 672 @abstract Callback called to handle incoming PHY packets 673 @param listener The listener which received the callback 674 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 675 @param data1 first quad of received PHY packet 676 @param data2 second quad of received PHY packet 677 @param refCon user specified reference value specified on the listener 678*/ 679typedef void (*IOFireWireLibPHYPacketCallback)( 680 IOFireWireLibPHYPacketListenerRef listener, 681 FWClientCommandID commandID, 682 UInt32 data1, 683 UInt32 data2, 684 void * refCon ); 685 686/*! @typedef IOFireWireLibPHYPacketSkippedCallback 687 @abstract Callback called when incoming packets have been dropped from the internal queue 688 @param listener The listener which dropped the packets 689 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 690 @param skippedPacketCount The number of skipped packets 691 @param refCon user specified reference value specified on the listener 692*/ 693typedef void (*IOFireWireLibPHYPacketSkippedCallback)( 694 IOFireWireLibPHYPacketListenerRef listener, 695 FWClientCommandID commandID, 696 UInt32 skippedPacketCount, 697 void * refCon ); 698 699/*! @typedef IOFireWireLibIRMAllocationLostNotificationProc 700@abstract Callback called when an IOFireWireLibIRMAllocationRef fails to reclaim IRM resources after a bus-reset 701*/ 702typedef void (*IOFireWireLibIRMAllocationLostNotificationProc)(IOFireWireLibIRMAllocationRef irmAllocation, void *refCon); 703 704/*! @typedef IOFWAsyncStreamListenerHandler 705 @abstract Callback called to handle Async Stream packets. 706 @param listener The listener which received the callback 707 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 708 @param packet Pointer to the received data 709 @param refCon user specified reference number passed in when async stream 710 interface is created 711*/ 712typedef UInt32 (*IOFWAsyncStreamListenerHandler)( 713 IOFWAsyncStreamListenerInterfaceRef listener, 714 FWClientCommandID commandID, 715 UInt32 size, 716 void* packet, 717 void* refCon) ; 718 719 720/*! @typedef IOFWAsyncStreamListenerSkippedPacketHandler 721 @abstract Callback called when incoming packets have been dropped from the internal queue 722 @param listener The listener which dropped the packets 723 @param commandID An FWClientCommandID to be passed to ClientCommandIsComplete() 724 @param skippedPacketCount The number of skipped packets 725*/ 726typedef void (*IOFWAsyncStreamListenerSkippedPacketHandler)( 727 IOFWAsyncStreamListenerInterfaceRef listener, 728 FWClientCommandID commandID, 729 UInt32 skippedPacketCount) ; 730 731#pragma mark - 732#pragma mark DEVICE INTERFACE 733// ============================================================ 734// IOFireWireDeviceInterface 735// ============================================================ 736 737/*! @class 738 @abstract IOFireWireDeviceInterface is your primary gateway to the functionality contained in 739 IOFireWireLib. 740 @discussion 741 You can use IOFireWireDeviceInterface to:<br> 742 <ul> 743 <li>perform synchronous read, write and lock operations</li> 744 <li>perform other miscellanous bus operations, such as reset the FireWire bus. </li> 745 <li>create FireWire command objects and interfaces used to perform 746 synchronous/asynchronous read, write and lock operations. These include:</li> 747 <ul type="square"> 748 <li>IOFireWireReadCommandInterface 749 <li>IOFireWireReadQuadletCommandInterface 750 <li>IOFireWireWriteCommandInterface 751 <li>IOFireWireWriteQuadletCommandInterface 752 <li>IOFireWireCompareSwapCommandInterface 753 </ul> 754 <li>create interfaces which provide a other extended services. These include:</li> 755 <ul type="square"> 756 <li>IOFireWirePseudoAddressSpaceInterface -- pseudo address space services</li> 757 <li>IOFireWirePhysicalAddressSpaceInterface -- physical address space services</li> 758 <li>IOFireWireLocalUnitDirectoryInterface -- manage local unit directories in the mac</li> 759 <li>IOFireWireConfigDirectoryInterface -- access and browse remote device config directories</li> 760 </ul> 761 <li>create interfaces which provide isochronous services (see IOFireWireLibIsoch.h). These include:</li> 762 <ul type="square"> 763 <li>IOFireWireIsochChannelInterface -- create/manage talker and listener isoch channels</li> 764 <li>IOFireWireLocalIsochPortInterface -- create local isoch ports</li> 765 <li>IOFireWireRemoteIsochPortInterface -- create remote isoch ports</li> 766 <li>IOFireWireDCLCommandPoolInterface -- create a DCL command pool allocator.</li> 767 </ul> 768 </ul> 769 770*/ 771typedef struct IOFireWireDeviceInterface_t 772{ 773 IUNKNOWN_C_GUTS ; 774 775 /*! Interface version */ 776 UInt32 version; 777 778 /*! Interface revision */ 779 UInt32 revision; // version/revision 780 781 // --- maintenance methods ------------- 782 /*! 783 @function InterfaceIsInited 784 @abstract Determine whether interface has been properly inited. 785 @param self The device interface to use. 786 @result Returns true if interface is inited and false if is it not. 787 */ 788 Boolean (*InterfaceIsInited)(IOFireWireLibDeviceRef self) ; 789 790 /*! 791 @function GetDevice 792 @abstract Get the IOKit service to which this interface is connected. 793 @param self The device interface to use. 794 @result Returns an io_object_t corresponding to the device the interface is 795 using 796 */ 797 io_object_t (*GetDevice)(IOFireWireLibDeviceRef self) ; 798 799 /*! 800 @function Open 801 @abstract Open the connected device for exclusive access. When you have 802 the device open using this method, all accesses by other clients of 803 this device will be denied until Close() is called. 804 @param self The device interface to use. 805 @result An IOReturn error code 806 */ 807 IOReturn (*Open)(IOFireWireLibDeviceRef self) ; 808 809 /*! 810 @function OpenWithSessionRef 811 @abstract An open function which allows this interface to have access 812 to the device when already opened. The service which has already opened 813 the device must be able to provide an IOFireWireSessionRef. 814 @param self The device interface to use 815 @param sessionRef The sessionRef returned from the client who has 816 the device open 817 @result An IOReturn error code 818 */ 819 IOReturn (*OpenWithSessionRef)(IOFireWireLibDeviceRef self, IOFireWireSessionRef sessionRef) ; 820 821 /*! 822 @function Close 823 @abstract Release exclusive access to the device 824 @param self The device interface to use 825 */ 826 void (*Close)(IOFireWireLibDeviceRef self) ; 827 828 // --- notification -------------------- 829 /*! 830 @function NotificationIsOn 831 @abstract Determine whether callback notifications for this interface are currently active 832 @param self The device interface to use 833 @result A Boolean value where true indicates notifications are active 834 */ 835 const Boolean (*NotificationIsOn)(IOFireWireLibDeviceRef self) ; 836 837 /*! 838 @function AddCallbackDispatcherToRunLoop 839 @abstract Installs the proper run loop event source to allow callbacks to function. This method 840 must be called before callback notifications for this interface or any interfaces 841 created using this interface can function. 842 @param self The device interface to use. 843 @param inRunLoop The run loop on which to install the event source 844 */ 845 const IOReturn (*AddCallbackDispatcherToRunLoop)(IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop) ; 846 847 /*! 848 @function RemoveCallbackDispatcherFromRunLoop 849 @abstract Reverses the effects of AddCallbackDispatcherToRunLoop(). This method removes 850 the run loop event source that was added to the specified run loop preventing any 851 future callbacks from being called 852 @param self The device interface to use. 853 */ 854 const void (*RemoveCallbackDispatcherFromRunLoop)(IOFireWireLibDeviceRef self) ; 855 856 /*! 857 @function TurnOnNotification 858 @abstract Activates any callbacks specified for this device interface. Only works after 859 AddCallbackDispatcherToRunLoop has been called. See also AddIsochCallbackDispatcherToRunLoop(). 860 @param self The device interface to use. 861 @result A Boolean value. Returns true on success. 862 */ 863 const Boolean (*TurnOnNotification)(IOFireWireLibDeviceRef self) ; 864 865 /*! 866 @function TurnOffNotification 867 @abstract Deactivates and callbacks specified for this device interface. Reverses the 868 effects of TurnOnNotification() 869 @param self The device interface to use. 870 */ 871 void (*TurnOffNotification)(IOFireWireLibDeviceRef self) ; 872 873 /*! 874 @function SetBusResetHandler 875 @abstract Sets the callback that should be called when a bus reset occurs. Note that this callback 876 can be called multiple times before the bus reset done handler is called. (f.ex., multiple bus 877 resets might occur before bus reconfiguration has completed.) 878 @param self The device interface to use. 879 @param handler Function pointer to the handler to install 880 @result Returns an IOFireWireBusResetHandler function pointer to the previously installed 881 bus reset handler. Returns 0 if none was set. 882 */ 883 const IOFireWireBusResetHandler 884 (*SetBusResetHandler)(IOFireWireLibDeviceRef self, IOFireWireBusResetHandler handler) ; 885 886 /*! 887 @function SetBusResetDoneHandler 888 @abstract Sets the callback that should be called after a bus reset has occurred and reconfiguration 889 of the bus has been completed. This function will only be called once per bus reset. 890 @param self The device interface to use. 891 @param handler Function pointer to the handler to install 892 @result Returns on IOFireWireBusResetDoneHandler function pointer to the previously installed 893 bus reset handler. Returns 0 if none was set. 894 */ 895 const IOFireWireBusResetDoneHandler 896 (*SetBusResetDoneHandler)(IOFireWireLibDeviceRef self, IOFireWireBusResetDoneHandler handler) ; 897 /*! 898 @function ClientCommandIsComplete 899 @abstract This function must be called from callback routines once they have completed processing 900 a callback. This function only applies to callbacks which take an IOFireWireLibDeviceRef (i.e. bus reset), 901 parameter. 902 @param commandID The command ID passed to the callback function when it was called 903 @param status An IOReturn value indicating the completion status of the callback function 904 */ 905 void (*ClientCommandIsComplete)(IOFireWireLibDeviceRef self, FWClientCommandID commandID, IOReturn status) ; 906 907 // --- read/write/lock operations ------- 908 /*! 909 @function Read 910 @abstract Perform synchronous block read 911 @param self The device interface to use. 912 @param device The service (representing an attached FireWire device) to read. 913 For 48-bit, device relative addressing, pass the service used to create the device interface. This 914 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 915 unsupported. 916 @param addr Command target address 917 @param buf A pointer to a buffer where the results will be stored 918 @param size Number of bytes to read 919 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 920 specified in generation. Pass false to ignore the generation parameter. The generation can be 921 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 922 923 @param generation The FireWire bus generation during which the command should be executed. Ignored 924 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 925 @result An IOReturn error code 926 */ 927 IOReturn (*Read)(IOFireWireLibDeviceRef self, 928 io_object_t device, 929 const FWAddress* addr, 930 void* buf, 931 UInt32* size, 932 Boolean failOnReset, 933 UInt32 generation) ; 934 935 /*! 936 @function ReadQuadlet 937 @abstract Perform synchronous quadlet read 938 @param self The device interface to use. 939 @param device The service (representing an attached FireWire device) to read. 940 For 48-bit, device relative addressing, pass the service used to create the device interface. This 941 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 942 unsupported. 943 @param addr Command target address 944 @param val A pointer to where to data should be stored 945 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 946 specified in generation. Pass false to ignore the generation parameter. The generation can be 947 obtained by calling GetBusGeneration() 948 @param generation The FireWire bus generation during which the command should be executed. Ignored 949 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 950 @result An IOReturn error code 951 */ 952 IOReturn (*ReadQuadlet)( IOFireWireLibDeviceRef self, 953 io_object_t device, 954 const FWAddress* addr, 955 UInt32* val, 956 Boolean failOnReset, 957 UInt32 generation) ; 958 /*! 959 @function Write 960 @abstract Perform synchronous block write 961 @param self The device interface to use. 962 @param device The service (representing an attached FireWire device) to which to write. 963 For 48-bit, device relative addressing, pass the service used to create the device interface. This 964 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 965 unsupported. 966 @param addr Command target address 967 @param buf A pointer to a buffer where the results will be stored 968 @param size Number of bytes to read 969 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 970 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 971 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 972 @param generation The FireWire bus generation during which the command should be executed. Ignored 973 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 974 @result An IOReturn error code 975 */ 976 IOReturn (*Write)( IOFireWireLibDeviceRef self, 977 io_object_t device, 978 const FWAddress* addr, 979 const void* buf, 980 UInt32* size, 981 Boolean failOnReset, 982 UInt32 generation) ; 983 984 /*! 985 @function WriteQuadlet 986 @abstract Perform synchronous quadlet write 987 @param self The device interface to use. 988 @param device The service (representing an attached FireWire device) to which to write. 989 For 48-bit, device relative addressing, pass the service used to create the device interface. This 990 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 991 unsupported. 992 @param addr Command target address 993 @param val The value to write 994 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 995 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 996 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 997 @param generation The FireWire bus generation during which the command should be executed. Ignored 998 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 999 @result An IOReturn error code 1000 */ 1001 IOReturn (*WriteQuadlet)(IOFireWireLibDeviceRef self, io_object_t device, const FWAddress* addr, const UInt32 val, Boolean failOnReset, UInt32 generation) ; 1002 1003 /*! 1004 @function CompareSwap 1005 @abstract Perform synchronous lock operation 1006 @param self The device interface to use. 1007 @param device The service (representing an attached FireWire device) to which to write. 1008 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1009 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1010 unsupported. 1011 @param addr Command target address 1012 @param cmpVal The check/compare value 1013 @param newVal Value to set 1014 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1015 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1016 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 1017 @param generation The FireWire bus generation during which the command should be executed. Ignored 1018 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 1019 @result An IOReturn error code 1020 */ 1021 IOReturn (*CompareSwap)(IOFireWireLibDeviceRef self, io_object_t device, const FWAddress* addr, UInt32 cmpVal, UInt32 newVal, Boolean failOnReset, UInt32 generation) ; 1022 1023 // --- FireWire command object methods --------- 1024 1025 /*! 1026 @function CreateReadCommand 1027 @abstract Create a block read command object. 1028 @param self The device interface to use. 1029 @param device The service (representing an attached FireWire device) to which to write. 1030 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1031 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1032 unsupported. Setting the callback value to nil defaults to synchronous execution. 1033 @param addr Command target address 1034 @param buf A pointer to a buffer where the results will be stored 1035 @param size Number of bytes to read 1036 @param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution. 1037 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1038 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1039 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 1040 @param generation The FireWire bus generation during which the command should be executed. Ignored 1041 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 1042 @result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef. 1043 */ 1044 IOFireWireLibCommandRef (*CreateReadCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress * addr, void* buf, UInt32 size, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void* inRefCon, REFIID iid) ; 1045 1046 /*! @function CreateReadQuadletCommand 1047 @abstract Create a quadlet read command object. 1048 @param self The device interface to use. 1049 @param device The service (representing an attached FireWire device) to which to write. 1050 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1051 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1052 unsupported. Setting the callback value to nil defaults to synchronous execution. 1053 @param addr Command target address 1054 @param quads An array of quadlets where results should be stored 1055 @param numQuads Number of quadlets to read 1056 @param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution. 1057 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1058 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1059 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 1060 @param generation The FireWire bus generation during which the command should be executed. Ignored 1061 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 1062 @result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.*/ 1063 IOFireWireLibCommandRef (*CreateReadQuadletCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress * addr, UInt32 quads[], UInt32 numQuads, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void* inRefCon, REFIID iid) ; 1064 1065 /*! @function CreateWriteCommand 1066 @abstract Create a block write command object. 1067 @param self The device interface to use. 1068 @param device The service (representing an attached FireWire device) to which to write. 1069 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1070 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1071 unsupported. Setting the callback value to nil defaults to synchronous execution. 1072 @param addr Command target address 1073 @param buf A pointer to the buffer containing the data to be written 1074 @param size Number of bytes to write 1075 @param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution. 1076 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1077 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1078 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 1079 @param generation The FireWire bus generation during which the command should be executed. Ignored 1080 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 1081 @result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.*/ 1082 IOFireWireLibCommandRef (*CreateWriteCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress * addr, void* buf, UInt32 size, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void* inRefCon, REFIID iid) ; 1083 1084 /*! 1085 @function CreateWriteQuadletCommand 1086 @abstract Create a quadlet write command object. 1087 @param self The device interface to use. 1088 @param device The service (representing an attached FireWire device) to which to write. 1089 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1090 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1091 unsupported. Setting the callback value to nil defaults to synchronous execution. 1092 @param addr Command target address 1093 @param quads An array of quadlets containing quadlets to be written 1094 @param numQuads Number of quadlets to write 1095 @param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution. 1096 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1097 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1098 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 1099 @param generation The FireWire bus generation during which the command should be executed. Ignored 1100 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 1101 @result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef. 1102 */ 1103 IOFireWireLibCommandRef (*CreateWriteQuadletCommand)(IOFireWireLibDeviceRef self, io_object_t device, const FWAddress * addr, UInt32 quads[], UInt32 numQuads, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void* inRefCon, REFIID iid) ; 1104 1105 /*! 1106 @function CreateCompareSwapCommand 1107 @abstract Create a quadlet compare/swap command object. 1108 @param self The device interface to use. 1109 @param device The service (representing an attached FireWire device) to which to write. 1110 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1111 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1112 unsupported. Setting the callback value to nil defaults to synchronous execution. 1113 @param addr Command target address 1114 @param cmpVal 32-bit value expected at target address 1115 @param newVal 32-bit value to be set at target address 1116 @param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution. 1117 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1118 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1119 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 1120 @param generation The FireWire bus generation during which the command should be executed. Ignored 1121 if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. 1122 @result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef. */ 1123 IOFireWireLibCommandRef (*CreateCompareSwapCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress * addr, UInt32 cmpVal, UInt32 newVal, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void* inRefCon, REFIID iid) ; 1124 1125 // --- other methods --------------------------- 1126 /*! @function BusReset 1127 @abstract Cause a bus reset 1128 @param self The device interface to use. */ 1129 IOReturn (*BusReset)( IOFireWireLibDeviceRef self) ; 1130 1131 /*! @function GetCycleTime 1132 @abstract Get bus cycle time. 1133 @param self The device interface to use. 1134 @param outCycleTime A pointer to a UInt32 to hold the result 1135 @result An IOReturn error code. */ 1136 IOReturn (*GetCycleTime)( IOFireWireLibDeviceRef self, UInt32* outCycleTime) ; 1137 1138 /*! @function GetGenerationAndNodeID 1139 @abstract (Obsolete) Get bus generation and remote device node ID. 1140 @discussion Obsolete -- Please use GetBusGeneration() and/or GetRemoteNodeID() in 1141 interface v4. 1142 @param self The device interface to use. 1143 @param outGeneration A pointer to a UInt32 to hold the generation result 1144 @param outNodeID A pointer to a UInt16 to hold the remote device node ID 1145 @result An IOReturn error code. */ 1146 IOReturn (*GetGenerationAndNodeID)( IOFireWireLibDeviceRef self, UInt32* outGeneration, UInt16* outNodeID) ; 1147 1148 /*! @function GetLocalNodeID 1149 @abstract (Obsolete) Get local node ID. 1150 @discussion Obsolete -- Please use GetBusGeneration() and GetLocalNodeIDWithGeneration() in 1151 interface v4. 1152 @param self The device interface to use. 1153 @param outLocalNodeID A pointer to a UInt16 to hold the local device node ID 1154 @result An IOReturn error code. */ 1155 IOReturn (*GetLocalNodeID)( IOFireWireLibDeviceRef self, UInt16* outLocalNodeID) ; 1156 1157 /*! @function GetResetTime 1158 @abstract Get time since last bus reset. 1159 @param self The device interface to use. 1160 @param outResetTime A pointer to an AbsolutTime to hold the result. 1161 @result An IOReturn error code. */ 1162 IOReturn (*GetResetTime)( 1163 IOFireWireLibDeviceRef self, 1164 AbsoluteTime* outResetTime) ; 1165 1166 // --- unit directory support ------------------ 1167 /*! @function CreateLocalUnitDirectory 1168 @abstract Creates a local unit directory object and returns an interface to it. An 1169 instance of a unit directory object corresponds to an instance of a unit 1170 directory in the local machine's configuration ROM. 1171 @param self The device interface to use. 1172 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1173 type of interface to be returned for the created unit directory object. 1174 @result An IOFireWireLibLocalUnitDirectoryRef. Returns 0 upon failure */ 1175 IOFireWireLibLocalUnitDirectoryRef (*CreateLocalUnitDirectory)( IOFireWireLibDeviceRef self, REFIID iid) ; 1176 1177 // --- config directory support ---------------- 1178 /*! @function GetConfigDirectory 1179 @abstract Creates a config directory object and returns an interface to it. The 1180 created config directory object represents the config directory in the remote 1181 device or unit to which the creating device interface is attached. 1182 @param self The device interface to use. 1183 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1184 type of interface to be returned for the created config directory object. 1185 @result An IOFireWireLibConfigDirectoryRef which should be released using Release(). 1186 Returns 0 upon failure. */ 1187 IOFireWireLibConfigDirectoryRef (*GetConfigDirectory)( IOFireWireLibDeviceRef self, REFIID iid) ; 1188 1189 /*! @function CreateConfigDirectoryWithIOObject 1190 @abstract This function can be used to create a config directory object and a 1191 corresponding interface from an opaque IOObject reference. Some configuration 1192 directory interface methods may return an io_object_t instead of an 1193 IOFireWireLibConfigDirectoryRef. Use this function to obtain an 1194 IOFireWireLibConfigDirectoryRef from an io_object_t. 1195 @param self The device interface to use. 1196 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1197 type of interface to be returned for the created config directory object. 1198 @result An IOFireWireLibConfigDirectoryRef. Returns 0 upon failure */ 1199 IOFireWireLibConfigDirectoryRef (*CreateConfigDirectoryWithIOObject)( IOFireWireLibDeviceRef self, io_object_t inObject, REFIID iid) ; 1200 1201 // --- address space support ------------------- 1202 /*! @function CreatePseudoAddressSpace 1203 @abstract Creates a pseudo address space object and returns an interface to it. This 1204 will create a pseudo address space (software-backed) on the local machine. 1205 @param self The device interface to use. 1206 @param inSize The size in bytes of this address space. 1207 @param inRefCon A user specified reference value. This will be passed to all callback functions. 1208 @param inQueueBufferSize The size of the queue which receives packets from the bus before they are handed to 1209 the client and/or put in the backing store. A larger queue can help eliminate dropped packets 1210 when receiving large bursts of data. When a packet is received which can not fit into the queue, 1211 the packet dropped callback will be called. 1212 @param inBackingStore An optional block of allocated memory representing the contents of the address space. This 1213 memory block must be of size inSize. 1214 @param inFlags A UInt32 with bits set corresponding to the flags that should be set 1215 for this address space. 1216 <ul> 1217 <li>kFWAddressSpaceNoFlags -- All flags off</li> 1218 <li>kFWAddressSpaceNoWriteAccess -- Write access to this address space will be disallowed. 1219 Setting this flag also disables compare/swap transactions on this address space.</li> 1220 <li>kFWAddressSpaceNoReadAccess -- Read access access to this address space will be disallowed. 1221 Setting this flag also disables compare/swap transactions on this address space.</li> 1222 <li>kFWAddressSpaceAutoWriteReply -- Writes will be made automatically, directly modifying the contents 1223 of the backing store. The user process will not be notified of writes.</li> 1224 <li>kFWAddressSpaceAutoReadReply -- Reads to this address space will be answered automagically 1225 using the contents of the backing store. The user process will not be notified of reads.</li> 1226 <li>kFWAddressSpaceAutoCopyOnWrite -- Writes to this address space will be made directly 1227 to the backing store at the same time the user process is notified of a write.</li> 1228 </ul> 1229 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1230 type of interface to be returned for the created pseudo address space object. 1231 @result An IOFireWireLibPseudoAddressSpaceRef. Returns 0 upon failure */ 1232 IOFireWireLibPseudoAddressSpaceRef (*CreatePseudoAddressSpace)( 1233 IOFireWireLibDeviceRef self, 1234 UInt32 inSize, 1235 void* inRefCon, 1236 UInt32 inQueueBufferSize, 1237 void* inBackingStore, 1238 UInt32 inFlags, 1239 REFIID iid) ; 1240 1241 /*! @function CreatePhysicalAddressSpace 1242 @abstract Creates a physical address space object and returns an interface to it. This 1243 will create a physical address space on the local machine. 1244 @param self The device interface to use. 1245 @param inSize The size in bytes of this address space. 1246 @param inBackingStore An block of allocated memory representing the contents of the address space. 1247 @param inFlags A UInt32 with bits set corresponding to the flags that should be set 1248 for this address space. For future use -- always pass 0. 1249 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1250 type of interface to be returned for the created physical address space object. 1251 @result An IOFireWireLibPhysicalAddressSpaceRef. Returns 0 upon failure */ 1252 IOFireWireLibPhysicalAddressSpaceRef (*CreatePhysicalAddressSpace)( IOFireWireLibDeviceRef self, UInt32 inSize, void* inBackingStore, UInt32 inFlags, REFIID iid) ; 1253 1254 // --- debugging ------------------------------- 1255 1256 /*! Description forthcoming */ 1257 IOReturn (*FireBugMsg)( IOFireWireLibDeviceRef self, const char* msg) ; 1258 1259 // 1260 // NOTE: the following methods available only in interface v2 and later 1261 // 1262 1263 // --- eye-sock-run-U.S. ----------------------- 1264 /*! @function AddIsochCallbackDispatcherToRunLoop 1265 @abstract This function adds an event source for the isochronous callback dispatcher 1266 to the specified CFRunLoop. Isochronous related callbacks will not function 1267 before this function is called. This functions is similar to 1268 AddCallbackDispatcherToRunLoop. The passed CFRunLoop can be different 1269 from that passed to AddCallbackDispatcherToRunLoop. 1270 @param self The device interface to use. 1271 @param inRunLoop A CFRunLoopRef for the run loop to which the event loop source 1272 should be added 1273 @result An IOReturn error code. */ 1274 IOReturn (*AddIsochCallbackDispatcherToRunLoop)( 1275 IOFireWireLibDeviceRef self, 1276 CFRunLoopRef inRunLoop) ; 1277 1278 /*! @function CreateRemoteIsochPort 1279 @abstract Creates a remote isochronous port object and returns an interface to it. A 1280 remote isochronous port object is an abstract entity used to represent a remote 1281 talker or listener device on an isochronous channel. 1282 @param self The device interface to use. 1283 @param inTalking Pass true if this port represents an isochronous talker. Pass 1284 false if this port represents an isochronous listener. 1285 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1286 type of interface to be returned for the created remote isochronous port object. 1287 @result An IOFireWireLibRemoteIsochPortRef. Returns 0 upon failure */ 1288 IOFireWireLibRemoteIsochPortRef 1289 (*CreateRemoteIsochPort)( 1290 IOFireWireLibDeviceRef self, 1291 Boolean inTalking, 1292 REFIID iid) ; 1293 1294 /*! @function CreateLocalIsochPort 1295 @abstract Creates a local isochronous port object and returns an interface to it. A 1296 local isochronous port object is an abstract entity used to represent a 1297 talking or listening endpoint in the local machine. 1298 @param self The device interface to use. 1299 @param inTalking Pass true if this port represents an isochronous talker. Pass 1300 false if this port represents an isochronous listener. 1301 @param inDCLProgram A pointer to the first DCL command struct of the DCL program 1302 to be compiled and used to send or receive data on this port. 1303 @param inStartEvent Start event: 0 or kFWDCLCycleEvent or kFWDCLSyBitsEvent 1304 @param inStartState Start state bits. For kFWDCLCycleEvent specifies the cycle to start the DMA on. 1305 For kFWDCLSyBitsEvent specifies the packet sync field value for the first packet to receive. 1306 @param inStartMask Start mask bits. For kFWDCLCycleEvent specifies a mask for the start cycle: 1307 the DMA will start when currentCycle & inStartMask == inStartEvent & inStartMask. 1308 For kFWDCLSyBitsEvent specifies a mask for the sync field: 1309 the DMA will start when packet sync == inStartEvent & inStartMask. 1310 @param inDCLProgramRanges This is an optional optimization parameter which can be used 1311 to decrease the time the local port object spends determining which set of virtual 1312 ranges the passed DCL program occupies. Pass a pointer to an array of IOVirtualRange 1313 structs or nil to ignore this parameter. 1314 @param inDCLProgramRangeCount The number of virtual ranges passed to inDCLProgramRanges. 1315 Pass 0 for none. 1316 @param inBufferRanges This is an optional optimization parameter which can be used 1317 to decrease the time the local port object spends determining which set of virtual 1318 ranges the data buffers referenced by the passed DCL program occupy. Pass a pointer 1319 to an array of IOVirtualRange structs or nil to ignore this parameter. 1320 @param inBufferRangeCount The number of virtual ranges passed to inBufferRanges. 1321 Pass 0 for none. 1322 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1323 type of interface to be returned for the created object. 1324 @result An IOFireWireLibLocalIsochPortRef. Returns 0 upon failure */ 1325 IOFireWireLibLocalIsochPortRef 1326 (*CreateLocalIsochPort)( 1327 IOFireWireLibDeviceRef self, 1328 Boolean inTalking, 1329 DCLCommand* inDCLProgram, 1330 UInt32 inStartEvent, 1331 UInt32 inStartState, 1332 UInt32 inStartMask, 1333 IOVirtualRange inDCLProgramRanges[], // optional optimization parameters 1334 UInt32 inDCLProgramRangeCount, 1335 IOVirtualRange inBufferRanges[], 1336 UInt32 inBufferRangeCount, 1337 REFIID iid) ; 1338 1339 /*! @function CreateIsochChannel 1340 @abstract Creates an isochronous channel object and returns an interface to it. An 1341 isochronous channel object is an abstract entity used to represent a 1342 FireWire isochronous channel. 1343 @param self The device interface to use. 1344 @param doIrm Controls whether the channel automatically performs IRM operations. 1345 Pass true if the channel should allocate its channel and bandwidth with 1346 the IRM. Pass false to ignore the IRM. 1347 @param packetSize Size of payload in bytes of packets being sent or received with this channel, 1348 excluding headers. This is automatically translated into a bandwidth allocation appropriate 1349 for the speed passed in prefSpeed. 1350 @param prefSpeed The preferred bus speed of this channel. 1351 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1352 type of interface to be returned for the created object. 1353 @result An IOFireWireLibIsochChannelRef. Returns 0 upon failure */ 1354 IOFireWireLibIsochChannelRef 1355 (*CreateIsochChannel)( 1356 IOFireWireLibDeviceRef self, 1357 Boolean doIrm, 1358 UInt32 packetSize, 1359 IOFWSpeed prefSpeed, 1360 REFIID iid ) ; 1361 1362 /*! @function CreateDCLCommandPool 1363 @abstract Creates a command pool object and returns an interface to it. The command 1364 pool can be used to build DCL programs. 1365 @param self The device interface to use. 1366 @param size Starting size of command pool 1367 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1368 type of interface to be returned for the created object. 1369 @result An IOFireWireLibDCLCommandPoolRef. Returns 0 upon failure */ 1370 IOFireWireLibDCLCommandPoolRef 1371 (*CreateDCLCommandPool)( 1372 IOFireWireLibDeviceRef self, 1373 IOByteCount size, 1374 REFIID iid ) ; 1375 1376 // --- refcons --------------------------------- 1377 /*! @function GetRefCon 1378 @abstract Get user reference value set on this interface 1379 @param self The device interface to use. 1380 @result Returns the user's reference value set on this interface. */ 1381 void* (*GetRefCon)( 1382 IOFireWireLibDeviceRef self) ; 1383 /*! @function SetRefCon 1384 @abstract Set user reference value on this interface 1385 @param self The device interface to use. 1386 @param refCon The reference value to set. */ 1387 void (*SetRefCon)( 1388 IOFireWireLibDeviceRef self, 1389 const void* refCon) ; 1390 1391 // --- debugging ------------------------------- 1392 // do not use this function 1393 /*! @function 1394 @description 1395 Do not use this function. 1396 */ 1397 CFTypeRef (*GetDebugProperty)( 1398 IOFireWireLibDeviceRef self, 1399 void* interface, 1400 CFStringRef inPropertyName, 1401 CFTypeID* outPropertyType) ; 1402 1403 /*! @function PrintDCLProgram 1404 @abstract Walk a DCL program linked list and print its contents 1405 @param self The device interface to use. 1406 @param inProgram A pointer to the first DCL of the program to print 1407 @param inLength Number of DCLs expected in the program. PrintDCLProgram() will 1408 report an error if this number does not match the number of DCLs found 1409 in the program. */ 1410 void (*PrintDCLProgram)( 1411 IOFireWireLibDeviceRef self, 1412 const DCLCommand* inProgram, 1413 UInt32 inLength) ; 1414 1415 // 1416 // NOTE: the following methods available only in interface v3 and later 1417 // 1418 1419 // --- v3 functions ---------- 1420 /*! @function CreateInitialUnitsPseudoAddressSpace 1421 @abstract Creates a pseudo address space in initial units space. 1422 @discussion Creates a pseudo address space object in initial units space and returns an interface to it. This 1423 will create a pseudo address space (software-backed) on the local machine. 1424 1425 Availablilty: IOFireWireDeviceInterface_v3, and newer 1426 1427 @param self The device interface to use. 1428 @param inAddressLo The lower 32 bits of the base address of the address space to be created. The address is always 1429 in initial units space. 1430 @param inSize The size in bytes of this address space. 1431 @param inRefCon A user specified reference value. This will be passed to all callback functions. 1432 @param inQueueBufferSize The size of the queue which receives packets from the bus before they are handed to 1433 the client and/or put in the backing store. A larger queue can help eliminate dropped packets 1434 when receiving large bursts of data. When a packet is received which can not fit into the queue, 1435 the packet dropped callback will be called. 1436 @param inBackingStore An optional block of allocated memory representing the contents of the address space. This 1437 memory block must be of size inSize. 1438 @param inFlags A UInt32 with bits set corresponding to the flags that should be set 1439 for this address space. 1440 <ul> 1441 <li>kFWAddressSpaceNoFlags -- All flags off</li> 1442 <li>kFWAddressSpaceNoWriteAccess -- Write access to this address space will be disallowed. 1443 Setting this flag also disables compare/swap transactions on this address space.</li> 1444 <li>kFWAddressSpaceNoReadAccess -- Read access access to this address space will be disallowed. 1445 Setting this flag also disables compare/swap transactions on this address space.</li> 1446 <li>kFWAddressSpaceAutoWriteReply -- Writes will be made automatically, directly modifying the contents 1447 of the backing store. The user process will not be notified of writes.</li> 1448 <li>kFWAddressSpaceAutoReadReply -- Reads to this address space will be answered automagically 1449 using the contents of the backing store. The user process will not be notified of reads.</li> 1450 <li>kFWAddressSpaceAutoCopyOnWrite -- Writes to this address space will be made directly 1451 to the backing store at the same time the user process is notified of a write. Clients 1452 will only be notified of a write if kFWAddressSpaceAutoWriteReply is not set.</li> 1453 <li>kFWAddressSpaceShareIfExists -- Allows creation of this address space even if another client 1454 already has an address space at the requested address. All clients will be notified of writes to 1455 covered addresses.</li> 1456 <li>kFWAddressSpaceExclusive -- Ensures that the allocation of this address space will fail if any portion 1457 of this address range is already allocated. If the allocation is successful this flag ensures that any 1458 future allocations overlapping this range will fail even if allocted with kFWAddressSpaceShareIfExists.</li> 1459 </ul> 1460 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1461 type of interface to be returned for the created pseudo address space object. 1462 @result An IOFireWireLibPseudoAddressSpaceRef. Returns 0 upon failure */ 1463 IOFireWireLibPseudoAddressSpaceRef (*CreateInitialUnitsPseudoAddressSpace)( 1464 IOFireWireLibDeviceRef self, 1465 UInt32 inAddressLo, 1466 UInt32 inSize, 1467 void* inRefCon, 1468 UInt32 inQueueBufferSize, 1469 void* inBackingStore, 1470 UInt32 inFlags, 1471 REFIID iid) ; 1472 /*! 1473 @function AddCallbackDispatcherToRunLoopForMode 1474 @abstract Add a run loop event source to allow IOFireWireLib callbacks to function. 1475 @discussion Installs the proper run loop event source to allow callbacks to function. This method 1476 must be called before callback notifications for this interface or any interfaces 1477 created using this interface can function. With this function, you can additionally specify 1478 for which run loop modes this source should be added. 1479 1480 Availability: IOFireWireDeviceInterface_v3, and newer 1481 1482 @param self The device interface to use. 1483 @param inRunLoop The run loop on which to install the event source 1484 @param inRunLoopMode The run loop mode(s) for which to install the event source 1485 @result An IOReturn error code. */ 1486 IOReturn (*AddCallbackDispatcherToRunLoopForMode)( 1487 IOFireWireLibDeviceRef self, 1488 CFRunLoopRef inRunLoop, 1489 CFStringRef inRunLoopMode ) ; 1490 /*! @function AddIsochCallbackDispatcherToRunLoop 1491 @abstract Add a run loop event source to allow IOFireWireLib isoch callbacks to function. 1492 @discussion This function adds an event source for the isochronous callback dispatcher 1493 to the specified CFRunLoop. Isochronous related callbacks will not be called unless 1494 this function has been called. This function is similar to AddCallbackDispatcherToRunLoop. 1495 The passed CFRunLoop can be different from that passed to AddCallbackDispatcherToRunLoop. 1496 1497 Availability: IOFireWireDeviceInterface_v3, and newer 1498 1499 @param self The device interface to use. 1500 @param inRunLoop A CFRunLoopRef for the run loop to which the event loop source 1501 should be added 1502 @param inRunLoopMode The run loop mode(s) for which to install the event source 1503 @result An IOReturn error code. */ 1504 IOReturn (*AddIsochCallbackDispatcherToRunLoopForMode)( 1505 IOFireWireLibDeviceRef self, 1506 CFRunLoopRef inRunLoop, 1507 CFStringRef inRunLoopMode ) ; 1508 /*! 1509 @function RemoveIsochCallbackDispatcherFromRunLoop 1510 @abstract Removes an IOFireWireLib-added run loop event source. 1511 @discussion Reverses the effects of AddIsochCallbackDispatcherToRunLoop(). This method removes 1512 the run loop event source that was added to the specified run loop preventing any 1513 future callbacks from being called. 1514 1515 Availability: IOFireWireDeviceInterface_v3, and newer 1516 1517 @param self The device interface to use. 1518 */ 1519 void (*RemoveIsochCallbackDispatcherFromRunLoop)( 1520 IOFireWireLibDeviceRef self) ; 1521 1522 /*! 1523 @function Seize 1524 @abstract Seize control of device/unit 1525 @discussion Allows a user space client to seize control of an in-kernel service even if 1526 that service has been Opened() by another client or in-kernel driver. This function should be 1527 used with care. Admin rights are required to use this function. 1528 1529 Calling this method makes it appear to all other drivers that the device has been unplugged. 1530 Open() should be called after this method has been invoked. 1531 1532 When access is complete, Close() and then IOServiceRequestProbe() should be called to restore 1533 normal operation. Calling IOServiceRequestProbe() makes it appear that the device has been "re-plugged." 1534 @param self The device interface to use. 1535 @param inFlags Reserved for future use. Set to NULL. Description forthcoming? 1536 */ 1537 IOReturn (*Seize)( 1538 IOFireWireLibDeviceRef self, 1539 IOOptionBits inFlags, 1540 ... ) ; 1541 1542 /*! 1543 @function FireLog 1544 @abstract Logs string to in-kernel debug buffer 1545 @param self The device interface to use. 1546 */ 1547 IOReturn (*FireLog)( 1548 IOFireWireLibDeviceRef self, 1549 const char* format, 1550 ... ) ; 1551 1552 /*! @function GetBusCycleTime 1553 @abstract Get bus and cycle time. 1554 @param self The device interface to use. 1555 @param outBusTime A pointer to a UInt32 to hold the bus time 1556 @param outCycleTime A pointer to a UInt32 to hold the cycle time 1557 @result An IOReturn error code. */ 1558 IOReturn (*GetBusCycleTime)( IOFireWireLibDeviceRef self, UInt32* outBusTime, UInt32* outCycleTime) ; 1559 1560 // 1561 // v4 1562 // 1563 1564 /*! 1565 @function CreateCompareSwapCommand64 1566 @abstract Create a quadlet compare/swap command object and initialize it with 64-bit values. 1567 @param self The device interface to use. 1568 @param device The service (representing an attached FireWire device) to which to write. 1569 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1570 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1571 unsupported. Setting the callback value to nil defaults to synchronous execution. 1572 @param addr Command target address 1573 @param cmpVal 64-bit value expected at target address 1574 @param newVal 64-bit value to be set at target address 1575 @param callback Command completion callback. 1576 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1577 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1578 obtained by calling GetBusGeneration() 1579 @param generation The FireWire bus generation during which the command should be executed. Ignored 1580 if failOnReset is false. 1581 @result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef. */ 1582 IOFireWireLibCommandRef (*CreateCompareSwapCommand64)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress* addr, 1583 UInt64 cmpVal, UInt64 newVal, IOFireWireLibCommandCallback callback, 1584 Boolean failOnReset, UInt32 generation, void* inRefCon, REFIID iid) ; 1585 1586 /*! 1587 @function CompareSwap64 1588 @abstract Perform synchronous lock operation 1589 @param self The device interface to use. 1590 @param device The service (representing an attached FireWire device) to which to write. 1591 For 48-bit, device relative addressing, pass the service used to create the device interface. This 1592 can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are 1593 unsupported. 1594 1595 If the quadlets stored at 'oldVal' match those passed to 'expectedVal', the lock operation was 1596 successful. 1597 @param addr Command target address 1598 @param expectedVal Pointer to quadlets expected at target. 1599 @param newVal Pointer to quadlets to atomically set at target if compare is successful. 1600 @param oldVal Pointer to quadlets to hold value found at target address after transaction if completed. 1601 @param size Size in bytes of compare swap transaction to perform. Value values are 4 and 8. 1602 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1603 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1604 obtained by calling GetBusGeneration() 1605 @param generation The FireWire bus generation during which the command should be executed. Ignored 1606 if failOnReset is false. 1607 @result An IOReturn error code 1608 */ 1609 IOReturn (*CompareSwap64)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress* addr, 1610 UInt32* expectedVal, UInt32* newVal, UInt32* oldVal, IOByteCount size, 1611 Boolean failOnReset, UInt32 generation) ; 1612 1613 /*! @function GetBusGeneration 1614 @abstract Get bus generation number. 1615 @discussion The bus generation number stays constant between bus resets and can be 1616 used in combination with a FireWire node ID to uniquely identify nodes on the bus. 1617 Pass the generation number to functions that take or return FireWire node IDs. 1618 1619 Availability: IOFireWireDeviceInterface_v4 and newer 1620 1621 @param self The device interface to use. 1622 @param outGeneration A pointer to a UInt32 to hold the bus generation number 1623 @result Returns kIOReturnSuccess if a valid bus generation has been returned in 'outGeneration'.*/ 1624 IOReturn (*GetBusGeneration)( IOFireWireLibDeviceRef self, UInt32* outGeneration ) ; 1625 1626 /*! @function GetLocalNodeIDWithGeneration 1627 @abstract Get node ID of local machine. 1628 @discussion Use this function instead of GetLocalNodeID(). 1629 1630 Availability: IOFireWireDeviceInterface_v4 and newer 1631 1632 @param self The device interface to use. 1633 @param checkGeneration A bus generation number obtained from GetBusGeneration() 1634 @param outLocalNodeID A pointer to a UInt16 to hold the node ID of the local machine. 1635 @result Returns kIOReturnSuccess if a valid nodeID has been returned in 'outLocalNodeID'. Returns 1636 kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.*/ 1637 IOReturn (*GetLocalNodeIDWithGeneration)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16* outLocalNodeID ) ; 1638 1639 /*! @function GetRemoteNodeID 1640 @abstract Get node ID of device to which this interface is attached. 1641 @discussion 1642 1643 Availability: IOFireWireDeviceInterface_v4 and newer 1644 1645 @param self The device interface to use. 1646 @param checkGeneration A bus generation number obtained from GetBusGeneration() 1647 @param outRemoteNodeID A pointer to a UInt16 to hold the node ID of the remote device. 1648 @result Returns kIOReturnSuccess if a valid nodeID has been returned in 'outRemoteNodeID'. Returns 1649 kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.*/ 1650 IOReturn (*GetRemoteNodeID)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16* outRemoteNodeID ) ; 1651 1652 /*! @function GetSpeedToNode 1653 @abstract Get maximum transfer speed to device to which this interface is attached. 1654 @discussion 1655 1656 Availability: IOFireWireDeviceInterface_v4 and newer 1657 1658 @param self The device interface to use. 1659 @param checkGeneration A bus generation number obtained from GetBusGeneration() 1660 @param outSpeed A pointer to an IOFWSpeed to hold the maximum speed to the remote device. 1661 @result Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns 1662 kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.*/ 1663 IOReturn (*GetSpeedToNode)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, IOFWSpeed* outSpeed) ; 1664 1665 /*! @function GetSpeedBetweenNodes 1666 @abstract Get the maximum transfer speed between nodes 'srcNodeID' and 'destNodeID'. 1667 @discussion 1668 1669 Availability: IOFireWireDeviceInterface_v4 and newer 1670 1671 @param self The device interface to use. 1672 @param checkGeneration A bus generation number obtained from GetBusGeneration() 1673 @param srcNodeID A FireWire node ID. 1674 @param destNodeID A FireWire node ID. 1675 @param outSpeed A pointer to an IOFWSpeed to hold the maximum transfer speed between node 'srcNodeID' and 'destNodeID'. 1676 @result Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns 1677 kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.*/ 1678 IOReturn (*GetSpeedBetweenNodes)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16 srcNodeID, UInt16 destNodeID, IOFWSpeed* outSpeed) ; 1679 1680 // 1681 // v5 1682 // 1683 1684 /*! Description forthcoming */ 1685 IOReturn (*GetIRMNodeID)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16* outIRMNodeID ) ; 1686 1687 // 1688 // v6 1689 // 1690 1691 /*! Description forthcoming */ 1692 IOReturn (*ClipMaxRec2K)( IOFireWireLibDeviceRef self, Boolean clipMaxRec ) ; 1693 1694 /*! Description forthcoming */ 1695 IOFireWireLibNuDCLPoolRef (*CreateNuDCLPool)( IOFireWireLibDeviceRef self, UInt32 capacity, REFIID iid ) ; 1696 1697 // 1698 // v7 1699 // 1700 1701 /*! Description forthcoming */ 1702 IOFireWireSessionRef (*GetSessionRef)( IOFireWireLibDeviceRef self ) ; 1703 1704 // 1705 // v8 1706 // 1707 1708 /*! @function CreateLocalIsochPortWithOptions 1709 @abstract Create a local isoch port 1710 @discussion 1711 1712 Same as CreateLocalIsochPort(), above, but allows additional options to be passed. 1713 Availability: IOFireWireDeviceInterface_v8 and newer 1714 1715 @param options Currently supported options are 'kFWIsochPortUseSeparateKernelThread'. If this 1716 option is used, a separate kernel thread will be created to handle interrupt 1717 processing for this port only. 1718 Pass 'kFWIsochPortDefaultOptions' for no options. 1719 @result Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns 1720 kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.*/ 1721 1722 IOFireWireLibLocalIsochPortRef (*CreateLocalIsochPortWithOptions)( 1723 IOFireWireLibDeviceRef self, 1724 Boolean inTalking, 1725 DCLCommand * dclProgram, 1726 UInt32 startEvent, 1727 UInt32 startState, 1728 UInt32 startMask, 1729 IOVirtualRange dclProgramRanges[], // optional optimization parameters 1730 UInt32 dclProgramRangeCount, 1731 IOVirtualRange bufferRanges[], 1732 UInt32 bufferRangeCount, 1733 IOFWIsochPortOptions options, 1734 REFIID iid) ; 1735 1736 // 1737 // v9 1738 // 1739 1740 /*! @function CreateVectorCommand 1741 @abstract Create a vector command object. 1742 @param self The device interface to use. 1743 @param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution. 1744 @param inRefCon Reference constant for 3rd party use. 1745 @result An IOFireWireLibVectorCommandRef interface*/ 1746 IOFireWireLibVectorCommandRef (*CreateVectorCommand)( IOFireWireLibDeviceRef self, IOFireWireLibCommandCallback callback, void* inRefCon, REFIID iid) ; 1747 1748 /*! @function AllocateIRMBandwidthInGeneration 1749 @abstract Attempt to allocate some isochronous bandwidth from the IRM 1750 @discussion 1751 1752 Attempts to allocates some isochronous bandwidth from the IRM, if the generation matches the current generation. 1753 Availability: IOFireWireDeviceInterface_v9 and newer 1754 1755 @param bandwidthUnits The number of bandwidth units to allocate 1756 1757 @param generation The bus generation that this allocation attempt is to take place in. 1758 1759 @result Returns kIOReturnSuccess if bandwidth allocation was successful. Returns kIOFireWireBusReset if 1760 'generation' does not match the current bus generation number. Returns kIOReturnError for any other 1761 error (such as the allocation failed) */ 1762 IOReturn (*AllocateIRMBandwidthInGeneration)(IOFireWireLibDeviceRef self, UInt32 bandwidthUnits, UInt32 generation) ; 1763 1764 /*! @function ReleaseIRMBandwidthInGeneration 1765 @abstract Attempt to release some isochronous bandwidth from the IRM 1766 @discussion 1767 1768 Attempts to release some isochronous bandwidth from the IRM, if the generation matches the current generation. 1769 Availability: IOFireWireDeviceInterface_v9 and newer 1770 1771 @param bandwidthUnits The number of bandwidth units to release 1772 1773 @param generation The bus generation that this release attempt is to take place in. 1774 1775 @result Returns kIOReturnSuccess if bandwidth release was successful. Returns kIOFireWireBusReset if 1776 'generation' does not match the current bus generation number. Returns kIOReturnError for any other 1777 error (such as the allocation failed) */ 1778 IOReturn (*ReleaseIRMBandwidthInGeneration)(IOFireWireLibDeviceRef self, UInt32 bandwidthUnits, UInt32 generation) ; 1779 1780 /*! @function AllocateIRMChannelInGeneration 1781 @abstract Attempt to allocate an isochronous channel from the IRM 1782 @discussion 1783 1784 Attempts to allocates an isochronous channel from the IRM, if the generation matches the current generation. 1785 Availability: IOFireWireDeviceInterface_v9 and newer 1786 1787 @param isochChannel The isochronous channel to allocate 1788 1789 @param generation The bus generation that this allocation attempt is to take place in. 1790 1791 @result Returns kIOReturnSuccess if channel allocation was successful. Returns kIOFireWireBusReset if 1792 'generation' does not match the current bus generation number. Returns kIOReturnError for any other 1793 error (such as the allocation failed) */ 1794 IOReturn (*AllocateIRMChannelInGeneration)(IOFireWireLibDeviceRef self, UInt8 isochChannel, UInt32 generation) ; 1795 1796 /*! @function ReleaseIRMChannelInGeneration 1797 @abstract Attempt to release an isochronous channel from the IRM 1798 @discussion 1799 1800 Attempts to release an isochronous channel from the IRM, if the generation matches the current generation. 1801 Availability: IOFireWireDeviceInterface_v9 and newer 1802 1803 @param isochChannel The isochronous channel to release 1804 1805 @param generation The bus generation that this release attempt is to take place in. 1806 1807 @result Returns kIOReturnSuccess if channel relase was successful. Returns kIOFireWireBusReset if 1808 'generation' does not match the current bus generation number. Returns kIOReturnError for any other 1809 error (such as the allocation failed) */ 1810 IOReturn (*ReleaseIRMChannelInGeneration)(IOFireWireLibDeviceRef self, UInt8 isochChannel, UInt32 generation) ; 1811 1812 /*! @function CreateIRMAllocation 1813 @abstract Attempt to create an IRM allocation that persists accross bus-resets. 1814 @discussion 1815 1816 Create an IOFireWireIRMAllocation object, which can be used to allocate IRM resources, and will reallocate automatically after bus-resets (if possible). 1817 1818 Availability: IOFireWireDeviceInterface_v9 and newer 1819 1820 @param releaseIRMResourcesOnFree Specify whether or not the IRM resources shall be released when the IOFireWireLibIRMAllocation is destroyed. Can be overrided later. 1821 1822 @param callback The handler to notify clients of failure to reclaim IRM resources after bus-reset. 1823 1824 @param pLostNotificationProcRefCon The refCon passed with the callback. 1825 1826 @result Returns a pointer to the newly created IRM allocation object, if successful, NULL otherwise. 1827 */ 1828 IOFireWireLibIRMAllocationRef (*CreateIRMAllocation)( IOFireWireLibDeviceRef self, 1829 Boolean releaseIRMResourcesOnFree, 1830 IOFireWireLibIRMAllocationLostNotificationProc callback, 1831 void *pLostNotificationProcRefCon, 1832 REFIID iid) ; 1833 1834 /*! @function CreateAsyncStreamListener 1835 @abstract Creates a async stream listener object and returns an interface to it. 1836 @param self The device interface to use. 1837 @param channel The channel to allocate. 1838 @param inRefCon A user specified reference value. This will be passed to all callback functions. 1839 @param inQueueBufferSize The size of the queue which receives packets from the bus before they are handed to 1840 the client. A larger queue can help eliminate dropped packets 1841 when receiving large bursts of data. When a packet is received which can not fit into the queue, 1842 the packet dropped callback will be called. 1843 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1844 type of interface to be returned for the created ayns stream listener object. 1845 @result An IOFWAsyncStreamListenerInterfaceRef. Returns 0 upon failure */ 1846 IOFWAsyncStreamListenerInterfaceRef (*CreateAsyncStreamListener)( IOFireWireLibDeviceRef self, 1847 UInt32 channel, 1848 IOFWAsyncStreamListenerHandler callback, 1849 void* inRefCon, 1850 UInt32 inQueueBufferSize, 1851 REFIID iid) ; 1852 1853 1854 /*! @function GetIsochAsyncPort 1855 @abstract Returns the notification port used for async and isoch callbacks 1856 @discussion 1857 1858 If necessary GetIsochAsyncPort will allocate the port. 1859 1860 Availability: IOFireWireDeviceInterface_v9 and newer 1861 1862 @param self The device interface to use. 1863 @result Returns the mach_port used for notifications */ 1864 1865 mach_port_t (*GetIsochAsyncPort)( IOFireWireLibDeviceRef self ); 1866 1867 /*! 1868 @function CreatePHYCommand 1869 @abstract Create a command object for sending a PHY packet 1870 @param self The device interface to use. 1871 @param data1 phy packet quadlet 1 1872 @param data2 phy packet quadlet 1 1873 @param callback completion callback 1874 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1875 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1876 obtained by calling GetBusGeneration() 1877 @param generation The FireWire bus generation during which the command should be executed. Ignored 1878 if failOnReset is false. 1879 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1880 type of interface to be returned for the created phy command object. 1881 @result An IOReturn error code 1882 */ 1883 1884 IOFireWireLibCommandRef (*CreatePHYCommand)( IOFireWireLibDeviceRef self, 1885 UInt32 data1, 1886 UInt32 data2, 1887 IOFireWireLibCommandCallback callback, 1888 Boolean failOnReset, 1889 UInt32 generation, 1890 void* inRefCon, 1891 REFIID iid ); 1892 1893 /*! 1894 @function CreatePHYPacketListener 1895 @abstract Create a listener object for receiving PHY packets 1896 @param self The device interface to use. 1897 @param queueCount The maximum queue size to use to buffer phy packets between kernel and user space 1898 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1899 type of interface to be returned for the created phy packet listener object. 1900 @result An IOReturn error code 1901 */ 1902 1903 IOFireWireLibPHYPacketListenerRef (*CreatePHYPacketListener)( IOFireWireLibDeviceRef self, 1904 UInt32 queueCount, 1905 REFIID iid ); 1906 1907 1908 /*! 1909 @function CreateAsyncStreamCommand 1910 @abstract Create a command object for sending Async Stream packets 1911 @param self The device interface to use. 1912 @param channel The channel number to use. 1913 @param buf A pointer to the buffer containing the data to be written 1914 @param size Number of bytes to write 1915 @param callback Command completion callback. 1916 @param failOnReset Pass true if the command should only be executed during the FireWire bus generation 1917 specified in 'generation'. Pass false to ignore the generation parameter. The generation can be 1918 obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing. 1919 @param inRefCon A user specified reference value. This will be passed to all callback functions. 1920 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the 1921 type of interface to be returned for the created phy packet listener object. 1922 @result An IOReturn error code 1923 */ 1924 IOFireWireLibCommandRef (*CreateAsyncStreamCommand)(IOFireWireLibDeviceRef self, 1925 UInt32 channel, 1926 UInt32 sync, 1927 UInt32 tag, 1928 void* buf, 1929 UInt32 size, 1930 IOFireWireLibCommandCallback callback, 1931 Boolean failOnReset, 1932 UInt32 generation, 1933 void* inRefCon, 1934 REFIID iid); 1935 1936 /*! @function GetCycleTimeAndUpTime 1937 @abstract Get bus cycle time and cpu uptime. 1938 @param self The device interface to use. 1939 @param outCycleTime A pointer to a UInt32 to hold the result 1940 @param outUpTime A pointer to a UInt64 to hold the result 1941 @result An IOReturn error code. */ 1942 IOReturn (*GetCycleTimeAndUpTime)( IOFireWireLibDeviceRef self, UInt32* outCycleTime, UInt64* outUpTime) ; 1943 1944} IOFireWireDeviceInterface, IOFireWireUnitInterface, IOFireWireNubInterface ; 1945#endif // ifdef KERNEL 1946 1947#pragma mark - 1948#pragma mark PSEUDO ADDRESS SPACE 1949// ============================================================ 1950// IOFireWirePseudoAddressSpaceInterface 1951// ============================================================ 1952 1953// creation flags 1954/*! FireWire address space creation flags */ 1955typedef enum 1956{ 1957 kFWAddressSpaceNoFlags = 0, 1958 kFWAddressSpaceNoWriteAccess = (1 << 0) , 1959 kFWAddressSpaceNoReadAccess = (1 << 1) , 1960 kFWAddressSpaceAutoWriteReply = (1 << 2) , 1961 kFWAddressSpaceAutoReadReply = (1 << 3) , 1962 kFWAddressSpaceAutoCopyOnWrite = (1 << 4) , 1963 kFWAddressSpaceShareIfExists = (1 << 5) , 1964 kFWAddressSpaceExclusive = (1 << 6) 1965} FWAddressSpaceFlags ; 1966 1967#ifndef KERNEL 1968/*! @class 1969 @discussion Represents and provides management functions for a pseudo address 1970 space (software-backed) in the local machine. 1971 1972 Pseudo address space objects can be created using IOFireWireDeviceInterface.*/ 1973typedef struct IOFireWirePseudoAddressSpaceInterface_t 1974{ 1975 IUNKNOWN_C_GUTS ; 1976 1977 /*! Interface version */ 1978 UInt32 version; 1979 1980 /*! Interface revision */ 1981 UInt32 revision; 1982 1983 /*! @function SetWriteHandler 1984 @abstract Set the callback that should be called to handle write accesses to 1985 the corresponding address space 1986 @param self The address space interface to use. 1987 @param inWriter The callback to set. 1988 @result Returns the callback that was previously set or nil for none.*/ 1989 const IOFireWirePseudoAddressSpaceWriteHandler (*SetWriteHandler)( IOFireWireLibPseudoAddressSpaceRef self, IOFireWirePseudoAddressSpaceWriteHandler inWriter) ; 1990 1991 /*! @function SetReadHandler 1992 @abstract Set the callback that should be called to handle read accesses to 1993 the corresponding address space 1994 @param self The address space interface to use. 1995 @param inReader The callback to set. 1996 @result Returns the callback that was previously set or nil for none.*/ 1997 const IOFireWirePseudoAddressSpaceReadHandler (*SetReadHandler)( IOFireWireLibPseudoAddressSpaceRef self, IOFireWirePseudoAddressSpaceReadHandler inReader) ; 1998 1999 /*! @function SetSkippedPacketHandler 2000 @abstract Set the callback that should be called when incoming packets are 2001 dropped by the address space. 2002 @param self The address space interface to use. 2003 @param inHandler The callback to set. 2004 @result Returns the callback that was previously set or nil for none.*/ 2005 const IOFireWirePseudoAddressSpaceSkippedPacketHandler (*SetSkippedPacketHandler)( IOFireWireLibPseudoAddressSpaceRef self, IOFireWirePseudoAddressSpaceSkippedPacketHandler inHandler) ; 2006 2007 /*! @function NotificationIsOn 2008 @abstract Is notification on? 2009 @param self The address space interface to use. 2010 @result Returns true if packet notifications for this address space are active */ 2011 Boolean (*NotificationIsOn)(IOFireWireLibPseudoAddressSpaceRef self) ; 2012 2013 /*! @function TurnOnNotification 2014 @abstract Try to turn on packet notifications for this address space. 2015 @param self The address space interface to use. 2016 @result Returns true upon success */ 2017 Boolean (*TurnOnNotification)(IOFireWireLibPseudoAddressSpaceRef self) ; 2018 2019 /*! @function TurnOffNotification 2020 @abstract Force packet notification off. 2021 @param self The pseudo address interface to use. */ 2022 void (*TurnOffNotification)(IOFireWireLibPseudoAddressSpaceRef self) ; 2023 2024 /*! @function ClientCommandIsComplete 2025 @abstract Notify the address space that a packet notification handler has completed. 2026 @discussion Packet notifications are received one at a time, in order. This function 2027 must be called after a packet handler has completed its work. 2028 @param self The address space interface to use. 2029 @param commandID The ID of the packet notification being completed. This is the same 2030 ID that was passed when a packet notification handler is called. 2031 @param status The completion status of the packet handler */ 2032 void (*ClientCommandIsComplete)(IOFireWireLibPseudoAddressSpaceRef self, FWClientCommandID commandID, IOReturn status) ; 2033 2034 // --- accessors ---------- 2035 /*! @function GetFWAddress 2036 @abstract Get the FireWire address of this address space 2037 @param self The pseudo address interface to use. */ 2038 void (*GetFWAddress)(IOFireWireLibPseudoAddressSpaceRef self, FWAddress* outAddr) ; 2039 2040 /*! @function GetBuffer 2041 @abstract Get a pointer to the backing store for this address space 2042 @param self The address space interface to use. 2043 @result A pointer to the backing store of this pseudo address space. Returns 2044 nil if none. */ 2045 void* (*GetBuffer)(IOFireWireLibPseudoAddressSpaceRef self) ; 2046 2047 /*! @function GetBufferSize 2048 @abstract Get the size in bytes of this address space. 2049 @param self The address space interface to use. 2050 @result Size of the pseudo address space in bytes. Returns 0 for none.*/ 2051 const UInt32 (*GetBufferSize)(IOFireWireLibPseudoAddressSpaceRef self) ; 2052 2053 /*! @function GetRefCon 2054 @abstract Returns the user refCon value for this address space. 2055 @param self The address space interface to use. 2056 @result Size of the pseudo address space in bytes. Returns 0 for none.*/ 2057 void* (*GetRefCon)(IOFireWireLibPseudoAddressSpaceRef self) ; 2058 2059 2060} IOFireWirePseudoAddressSpaceInterface ; 2061 2062#pragma mark - 2063#pragma mark IRM ALLOCATION 2064// ============================================================ 2065// IOFireWireLibIRMAllocationInterface 2066// ============================================================ 2067/*! @class 2068 Description forthcoming 2069 */ 2070typedef struct IOFireWireLibIRMAllocationInterface_t 2071{ 2072 IUNKNOWN_C_GUTS ; 2073 UInt32 version, revision ; 2074 2075 /*! @function setReleaseIRMResourcesOnFree 2076 @abstract Set a new value for releaseIRMResourcesOnFree 2077 @param self The IRMAllocation interface to use. 2078 @param doRelease The new value for releaseIRMResourcesOnFree. */ 2079 const void (*setReleaseIRMResourcesOnFree)( IOFireWireLibIRMAllocationRef self, Boolean doRelease) ; 2080 2081 /*! @function allocateIsochResources 2082 @abstract Use this interface to allocate isochronous resources 2083 @param self The IRMAllocation interface to use. 2084 @param isochChannel The isoch channel to allocate. 2085 @param bandwidthUnits The bandwidth units to allocate. 2086 @result Returns true if allocation success */ 2087 IOReturn (*allocateIsochResources)(IOFireWireLibIRMAllocationRef self, UInt8 isochChannel, UInt32 bandwidthUnits); 2088 2089 /*! @function deallocateIsochResources 2090 @abstract Deallocate previously allocated resources 2091 @param self The IRMAllocation interface to use. 2092 @result Returns true if deallocation success */ 2093 IOReturn (*deallocateIsochResources)(IOFireWireLibIRMAllocationRef self); 2094 2095 /*! @function areIsochResourcesAllocated 2096 @abstract Poll to see if IRM resources are still allocated 2097 @param self The IRMAllocation interface to use. 2098 @param pAllocatedIsochChannel If allocated, the channel 2099 @param pAllocatedBandwidthUnits If allocated, the amount of bandwidth 2100 @result Returns true if currently allocated, false otherwise */ 2101 Boolean (*areIsochResourcesAllocated)(IOFireWireLibIRMAllocationRef self, UInt8 *pAllocatedIsochChannel, UInt32 *pAllocatedBandwidthUnits); 2102 2103 /*! @function NotificationIsOn 2104 @abstract Is notification on? 2105 @param self The IRMAllocation interface to use. 2106 @result Returns true if notifications for this IRMAllocation are enabled */ 2107 Boolean (*NotificationIsOn)(IOFireWireLibIRMAllocationRef self) ; 2108 2109 /*! @function TurnOnNotification 2110 @abstract Try to turn on notifications 2111 @param self The IRMAllocation interface to use. 2112 @result Returns true upon success */ 2113 Boolean (*TurnOnNotification)(IOFireWireLibIRMAllocationRef self) ; 2114 2115 /*! @function TurnOffNotification 2116 @abstract Force notification off. 2117 @param self The IRMAllocation interface to use. */ 2118 void (*TurnOffNotification)(IOFireWireLibIRMAllocationRef self) ; 2119 2120 /*! @function SetRefCon 2121 @abstract Set a new refcon 2122 @param self The IRMAllocation interface to use. 2123 @param refCon The new refcon value. */ 2124 void (*SetRefCon)(IOFireWireLibIRMAllocationRef self, void* refCon) ; 2125 2126 /*! @function GetRefCon 2127 @abstract Get the current refcon 2128 @param self The IRMAllocation interface to use. 2129 @result Returns the current refcon value */ 2130 void* (*GetRefCon)(IOFireWireLibIRMAllocationRef self) ; 2131}IOFireWireLibIRMAllocationInterface; 2132 2133#pragma mark - 2134#pragma mark LOCAL UNIT DIRECTORY INTERFACE 2135// ============================================================ 2136// 2137// IOFireWireLocalUnitDirectoryInterface 2138// 2139// ============================================================ 2140 2141/*! @class 2142 @discussion Allows creation and management of unit directories in the config 2143 ROM of the local machine. After the unit directory has been built, 2144 Publish() should be called to cause it to appear in the config ROM. 2145 Unpublish() has the reverse effect as Publish(). 2146 2147 This interface can be created using IOFireWireDeviceInterface::CreateLocalUnitDirectory. */ 2148typedef struct IOFireWireLocalUnitDirectoryInterface_t 2149{ 2150 IUNKNOWN_C_GUTS ; 2151 2152 /*! Interface version */ 2153 UInt32 version; 2154 2155 /*! Interface revision */ 2156 UInt32 revision ; 2157 2158 // --- adding to ROM ------------------- 2159 /*! @function AddEntry_Ptr 2160 @abstract Append a data leaf 2161 @discussion Appends a leaf data node to a unit directory 2162 @param self The local unit directory interface to use. 2163 @param key The config ROM key for the data to be added. 2164 @param inBuffer A pointer to the data to be placed in the added leaf. 2165 @param inLen Length of the data being added. 2166 @param inDesc Reserved; set to NULL. */ 2167 IOReturn (*AddEntry_Ptr)(IOFireWireLibLocalUnitDirectoryRef self, int key, void* inBuffer, size_t inLen, CFStringRef inDesc) ; 2168 2169 /*! @function AddEntry_UInt32 2170 @abstract Append an immediate leaf 2171 @discussion Appends an immediate leaf to a unit directory. Note that only the lower 3 bytes 2172 of the passed in value can appear in the unit directory. 2173 @param self The local unit directory interface to use. 2174 @param key The config ROM key for the data to be added. 2175 @param value The value to be added. 2176 @param inDesc Reserved; set to NULL. */ 2177 IOReturn (*AddEntry_UInt32)(IOFireWireLibLocalUnitDirectoryRef self, int key, UInt32 value, CFStringRef inDesc) ; 2178 2179 /*! @function AddEntry_FWAddress 2180 @abstract Append an offset leaf 2181 @discussion Appends an offset leaf to a unit directory. The address passed in value should be an 2182 address in initial unit space of the local config ROM. 2183 @param self The local unit directory interface to use. 2184 @param key The config ROM key for the data to be added. 2185 @param value A pointer to a FireWire address. 2186 @param inDesc Reserved; set to NULL. */ 2187 IOReturn (*AddEntry_FWAddress)(IOFireWireLibLocalUnitDirectoryRef self, int key, const FWAddress* value, CFStringRef inDesc) ; 2188 2189 // Use this function to cause your unit directory to appear in the Mac's config ROM. 2190 /*! @function Publish 2191 @abstract Causes a constructed or updated unit directory to appear in the local machine's 2192 config ROM. Note that this call will cause a bus reset, after which the unit directory will 2193 be visible to devices on the bus. 2194 @param self The local unit directory interface to use. */ 2195 IOReturn (*Publish)(IOFireWireLibLocalUnitDirectoryRef self) ; 2196 2197 /*! @function Unpublish 2198 @abstract Has the opposite effect from Publish(). This call removes a unit directory from the 2199 local machine's config ROM. Note that this call will cause a bus reset, after which the unit directory will 2200 no longer appear to devices on the bus. 2201 @param self The local unit directory interface to use. */ 2202 IOReturn (*Unpublish)(IOFireWireLibLocalUnitDirectoryRef self) ; 2203} IOFireWireLocalUnitDirectoryInterface ; 2204 2205#pragma mark - 2206#pragma mark PHYSICAL ADDRESS SPACE INTERFACE 2207// ============================================================ 2208// 2209// IOFireWireLibPhysicalAddressSpaceInterface 2210// 2211// ============================================================ 2212 2213/*! @class 2214 @abstract IOFireWireLib physical address space object. ( interface name: IOFireWirePhysicalAddressSpaceInterface ) 2215 @discussion Represents and provides management functions for a physical address 2216 space (hardware-backed) in the local machine.<br> 2217 Physical address space objects can be created using IOFireWireDeviceInterface.*/ 2218typedef struct IOFireWirePhysicalAddressSpaceInterface_t 2219{ 2220 IUNKNOWN_C_GUTS ; 2221 2222 /*! Interface version. */ 2223 UInt32 version; 2224 2225 /*! Interface revision. */ 2226 UInt32 revision ; 2227 /*! @function GetPhysicalSegments 2228 @abstract Returns the list of physical memory ranges this address space occupies 2229 on the local machine. 2230 @param self The address space interface to use. 2231 @param ioSegmentCount Pass in a pointer to the number of list entries in 2232 outSegments and outAddress. Upon completion, this will contain the actual 2233 number of segments returned in outSegments and outAddress 2234 @param outSegments A pointer to an array to hold the function results. Upon 2235 completion, this will contain the lengths of the physical segments this 2236 address space occupies on the local machine 2237 @param outAddresses A pointer to an array to hold the function results. Upon 2238 completion, this will contain the addresses of the physical segments this 2239 address space occupies on the local machine. If NULL, ioSegmentCount 2240 will contain the number of physical segments in the address space.*/ 2241 2242 void (*GetPhysicalSegments)( 2243 IOFireWireLibPhysicalAddressSpaceRef self, 2244 UInt32* ioSegmentCount, 2245 IOByteCount outSegments[], 2246 IOPhysicalAddress outAddresses[]) ; 2247 /*! @function GetPhysicalSegment 2248 @abstract Returns the physical segment containing the address at a specified offset 2249 from the beginning of this address space 2250 @param self The address space interface to use. 2251 @param offset Offset from beginning of address space 2252 @param length Pointer to a value which upon completion will contain the length of 2253 the segment returned by the function. 2254 @result The address of the physical segment containing the address at the specified 2255 offset of the address space */ 2256 IOPhysicalAddress (*GetPhysicalSegment)( 2257 IOFireWireLibPhysicalAddressSpaceRef self, 2258 IOByteCount offset, 2259 IOByteCount* length) ; 2260 2261 /*! @function GetPhysicalAddress 2262 @abstract Returns the physical address of the beginning of this address space 2263 @param self The address space interface to use. 2264 @result The physical address of the start of this address space */ 2265 IOPhysicalAddress (*GetPhysicalAddress)( 2266 IOFireWireLibPhysicalAddressSpaceRef self) ; 2267 2268 // --- accessors ---------- 2269 /*! @function GetFWAddress 2270 @abstract Get the FireWire address of this address space 2271 @param self The address space interface to use. */ 2272 void (*GetFWAddress)( 2273 IOFireWireLibPhysicalAddressSpaceRef self, 2274 FWAddress* outAddr) ; 2275 2276 /*! @function GetBuffer 2277 @abstract Get a pointer to the backing store for this address space 2278 @param self The address space interface to use. 2279 @result A pointer to the backing store of this address space.*/ 2280 void* (*GetBuffer)( 2281 IOFireWireLibPhysicalAddressSpaceRef self) ; 2282 2283 /*! @function GetBufferSize 2284 @abstract Get the size in bytes of this address space. 2285 @param self The address space interface to use. 2286 @result Size of the pseudo address space in bytes. */ 2287 const UInt32 (*GetBufferSize)( 2288 IOFireWireLibPhysicalAddressSpaceRef self) ; 2289 2290} IOFireWirePhysicalAddressSpaceInterface ; 2291#endif // ifndef KERNEL 2292 2293#pragma mark - 2294#pragma mark COMMAND OBJECT INTERFACES 2295// ================================================================= 2296// command objects 2297// ================================================================= 2298 2299#define kFireWireCommandUserFlagsMask (0x0000FFFF) 2300 2301// 8 quadlets 2302#define kFWUserCommandSubmitWithCopyMaxBufferBytes 32 2303 2304// 2305// Flags to be set on IOFireWireLib command objects 2306// Passed to SetFlags() 2307// 2308/*! @enum IOFireWireLib Command Flags 2309 @abstract Flags for IOFireWireLib command objects 2310 @discussion 2311 Pass these flags to the object's SetFlags callback. 2312 */ 2313enum 2314{ 2315 kFWCommandNoFlags = 0, 2316 kFWCommandInterfaceForceNoCopy = (1 << 0), 2317 kFWCommandInterfaceForceCopyAlways = (1 << 1), 2318 kFWCommandInterfaceSyncExecute = (1 << 2), 2319 kFWCommandInterfaceAbsolute = (1 << 3), 2320 kFWVectorCommandInterfaceOrdered = (1 << 4), 2321 kFWCommandInterfaceForceBlockRequest = (1 << 5) 2322} ; 2323 2324/*! @enum IOFireWireLib failOnReset Flags 2325 @abstract Flags for IOFireWireLib commands 2326 @discussion 2327 Pass these flags in the failOnReset of various commands. 2328 */ 2329enum 2330{ 2331 kFWDontFailOnReset = false, 2332 kFWFailOnReset = true 2333} ; 2334 2335/*! @enum IOFireWireLib Additional Command Flags 2336 @abstract Flags for IOFireWireLib commands 2337 @discussion 2338 Pass these flags to the object's SetFlags callback. 2339 */ 2340enum { 2341 kFireWireCommandUseCopy = (1 << 16), 2342 kFireWireCommandAbsolute = (1 << 17) 2343} ; 2344 2345#ifndef KERNEL 2346// 2347// IOFIREWIRELIBCOMMAND_C_GUTS 2348// Macro used to insert generic superclass function definitions into all subclass of 2349// IOFireWireCommand. Comments for functions contained in this macro follow below: 2350// 2351/*! @parseOnly */ 2352#define IOFIREWIRELIBCOMMAND_C_GUTS \ 2353 /*! @function GetStatus \ 2354 @abstract Return command completion status. \ 2355 @discussion Availability: (for interfaces obtained with ID) \ 2356 <table border="0" rules="all"> \ 2357 <tr> \ 2358 <td width="20%"></td> \ 2359 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2360 <td>YES</td> \ 2361 </tr> \ 2362 <tr> \ 2363 <td width="20%"></td> \ 2364 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2365 <td>YES</td> \ 2366 </tr> \ 2367 <tr> \ 2368 <td width="20%"></td> \ 2369 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2370 <td>YES</td> \ 2371 </tr> \ 2372 <tr> \ 2373 <td width="20%"></td> \ 2374 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2375 <td>YES</td> \ 2376 </tr> \ 2377 <tr> \ 2378 <td width="20%"></td> \ 2379 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2380 <td>YES</td> \ 2381 </tr> \ 2382 <tr> \ 2383 <td width="20%"></td> \ 2384 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2385 <td>YES</td> \ 2386 </tr> \ 2387 <tr> \ 2388 <td width="20%"></td> \ 2389 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2390 <td>YES</td> \ 2391 </tr> \ 2392 <tr> \ 2393 <td width="20%"></td> \ 2394 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2395 <td>YES</td> \ 2396 </tr> \ 2397 </table> \ 2398 \ 2399 @param self The command object interface of interest \ 2400 @result An IOReturn error code indicating the completion error (if any) returned the last \ 2401 time this command object was executed */ \ 2402 IOReturn (*GetStatus)(IOFireWireLibCommandRef self) ; \ 2403 /*! @function GetTransferredBytes \ 2404 @abstract Return number of bytes transferred by this command object when it last completed \ 2405 execution. \ 2406 @discussion Availability: (for interfaces obtained with ID) \ 2407 <table border="0" rules="all"> \ 2408 <tr> \ 2409 <td width="20%"></td> \ 2410 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2411 <td>YES</td> \ 2412 </tr> \ 2413 <tr> \ 2414 <td width="20%"></td> \ 2415 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2416 <td>YES</td> \ 2417 </tr> \ 2418 <tr> \ 2419 <td width="20%"></td> \ 2420 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2421 <td>YES</td> \ 2422 </tr> \ 2423 <tr> \ 2424 <td width="20%"></td> \ 2425 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2426 <td>YES</td> \ 2427 </tr> \ 2428 <tr> \ 2429 <td width="20%"></td> \ 2430 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2431 <td>YES</td> \ 2432 </tr> \ 2433 <tr> \ 2434 <td width="20%"></td> \ 2435 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2436 <td>YES</td> \ 2437 </tr> \ 2438 <tr> \ 2439 <td width="20%"></td> \ 2440 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2441 <td>YES</td> \ 2442 </tr> \ 2443 <tr> \ 2444 <td width="20%"></td> \ 2445 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2446 <td>YES</td> \ 2447 </tr> \ 2448 </table> \ 2449 @param self The command object interface of interest \ 2450 @result A UInt32 containing the bytes transferred value */ \ 2451 UInt32 (*GetTransferredBytes)(IOFireWireLibCommandRef self) ; \ 2452 /*! @function GetTargetAddress \ 2453 @abstract Get command target address. \ 2454 @discussion Availability: (for interfaces obtained with ID) \ 2455 <table border="0" rules="all"> \ 2456 <tr> \ 2457 <td width="20%"></td> \ 2458 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2459 <td>YES</td> \ 2460 </tr> \ 2461 <tr> \ 2462 <td width="20%"></td> \ 2463 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2464 <td>YES</td> \ 2465 </tr> \ 2466 <tr> \ 2467 <td width="20%"></td> \ 2468 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2469 <td>YES</td> \ 2470 </tr> \ 2471 <tr> \ 2472 <td width="20%"></td> \ 2473 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2474 <td>YES</td> \ 2475 </tr> \ 2476 <tr> \ 2477 <td width="20%"></td> \ 2478 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2479 <td>YES</td> \ 2480 </tr> \ 2481 <tr> \ 2482 <td width="20%"></td> \ 2483 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2484 <td>YES</td> \ 2485 </tr> \ 2486 <tr> \ 2487 <td width="20%"></td> \ 2488 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2489 <td>YES</td> \ 2490 </tr> \ 2491 <tr> \ 2492 <td width="20%"></td> \ 2493 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2494 <td>NO</td> \ 2495 </tr> \ 2496 </table> \ 2497 @param self The command object interface of interest \ 2498 @param outAddr A pointer to an FWAddress to contain the function result. */ \ 2499 void (*GetTargetAddress)(IOFireWireLibCommandRef self, FWAddress* outAddr) ; \ 2500 /*! @function SetTarget \ 2501 @abstract Set command target address \ 2502 @discussion Availability: (for interfaces obtained with ID) \ 2503 <table border="0" rules="all"> \ 2504 <tr> \ 2505 <td width="20%"></td> \ 2506 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2507 <td>YES</td> \ 2508 </tr> \ 2509 <tr> \ 2510 <td width="20%"></td> \ 2511 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2512 <td>YES</td> \ 2513 </tr> \ 2514 <tr> \ 2515 <td width="20%"></td> \ 2516 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2517 <td>YES</td> \ 2518 </tr> \ 2519 <tr> \ 2520 <td width="20%"></td> \ 2521 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2522 <td>YES</td> \ 2523 </tr> \ 2524 <tr> \ 2525 <td width="20%"></td> \ 2526 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2527 <td>YES</td> \ 2528 </tr> \ 2529 <tr> \ 2530 <td width="20%"></td> \ 2531 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2532 <td>YES</td> \ 2533 </tr> \ 2534 <tr> \ 2535 <td width="20%"></td> \ 2536 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2537 <td>YES</td> \ 2538 </tr> \ 2539 <tr> \ 2540 <td width="20%"></td> \ 2541 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2542 <td>NO</td> \ 2543 </tr> \ 2544 </table> \ 2545 @param self The command object interface of interest \ 2546 @param addr A pointer to an FWAddress. */ \ 2547 void (*SetTarget)(IOFireWireLibCommandRef self, const FWAddress* addr) ; \ 2548 /*! @function SetGeneration \ 2549 @abstract Set FireWire bus generation for which the command object shall be valid. \ 2550 If the failOnReset attribute has been set, the command will only be considered for \ 2551 execution during the bus generation specified by this function. \ 2552 @discussion Availability: (for interfaces obtained with ID) \ 2553 <table border="0" rules="all"> \ 2554 <tr> \ 2555 <td width="20%"></td> \ 2556 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2557 <td>YES</td> \ 2558 </tr> \ 2559 <tr> \ 2560 <td width="20%"></td> \ 2561 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2562 <td>YES</td> \ 2563 </tr> \ 2564 <tr> \ 2565 <td width="20%"></td> \ 2566 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2567 <td>YES</td> \ 2568 </tr> \ 2569 <tr> \ 2570 <td width="20%"></td> \ 2571 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2572 <td>YES</td> \ 2573 </tr> \ 2574 <tr> \ 2575 <td width="20%"></td> \ 2576 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2577 <td>YES</td> \ 2578 </tr> \ 2579 <tr> \ 2580 <td width="20%"></td> \ 2581 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2582 <td>YES</td> \ 2583 </tr> \ 2584 <tr> \ 2585 <td width="20%"></td> \ 2586 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2587 <td>YES</td> \ 2588 </tr> \ 2589 <tr> \ 2590 <td width="20%"></td> \ 2591 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2592 <td>YES</td> \ 2593 </tr> \ 2594 </table> \ 2595 @param self The command object interface of interest \ 2596 @param generation A bus generation. The current bus generation can be obtained \ 2597 from IOFireWireDeviceInterface::GetBusGeneration(). */ \ 2598 void (*SetGeneration)(IOFireWireLibCommandRef self, UInt32 generation) ; \ 2599 /*! @function SetCallback \ 2600 @abstract Set the completion handler to be called once the command completes \ 2601 asynchronous execution . \ 2602 @discussion Availability: (for interfaces obtained with ID) \ 2603 <table border="0" rules="all"> \ 2604 <tr> \ 2605 <td width="20%"></td> \ 2606 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2607 <td>YES</td> \ 2608 </tr> \ 2609 <tr> \ 2610 <td width="20%"></td> \ 2611 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2612 <td>YES</td> \ 2613 </tr> \ 2614 <tr> \ 2615 <td width="20%"></td> \ 2616 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2617 <td>YES</td> \ 2618 </tr> \ 2619 <tr> \ 2620 <td width="20%"></td> \ 2621 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2622 <td>YES</td> \ 2623 </tr> \ 2624 <tr> \ 2625 <td width="20%"></td> \ 2626 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2627 <td>YES</td> \ 2628 </tr> \ 2629 <tr> \ 2630 <td width="20%"></td> \ 2631 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2632 <td>YES</td> \ 2633 </tr> \ 2634 <tr> \ 2635 <td width="20%"></td> \ 2636 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2637 <td>YES</td> \ 2638 </tr> \ 2639 <tr> \ 2640 <td width="20%"></td> \ 2641 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2642 <td>YES</td> \ 2643 </tr> \ 2644 </table> \ 2645 @param self The command object interface of interest \ 2646 @param inCallback A callback handler. Passing nil forces the command object to \ 2647 execute synchronously. */ \ 2648 void (*SetCallback)(IOFireWireLibCommandRef self, IOFireWireLibCommandCallback inCallback) ; \ 2649 /*! @function SetRefCon \ 2650 @abstract Set the user refCon value. This is the user defined value that will be passed \ 2651 in the refCon argument to the completion function. \ 2652 @discussion Availability: (for interfaces obtained with ID) \ 2653 <table border="0" rules="all"> \ 2654 <tr> \ 2655 <td width="20%"></td> \ 2656 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2657 <td>YES</td> \ 2658 </tr> \ 2659 <tr> \ 2660 <td width="20%"></td> \ 2661 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2662 <td>YES</td> \ 2663 </tr> \ 2664 <tr> \ 2665 <td width="20%"></td> \ 2666 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2667 <td>YES</td> \ 2668 </tr> \ 2669 <tr> \ 2670 <td width="20%"></td> \ 2671 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2672 <td>YES</td> \ 2673 </tr> \ 2674 <tr> \ 2675 <td width="20%"></td> \ 2676 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2677 <td>YES</td> \ 2678 </tr> \ 2679 <tr> \ 2680 <td width="20%"></td> \ 2681 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2682 <td>YES</td> \ 2683 </tr> \ 2684 <tr> \ 2685 <td width="20%"></td> \ 2686 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2687 <td>YES</td> \ 2688 </tr> \ 2689 <tr> \ 2690 <td width="20%"></td> \ 2691 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2692 <td>YES</td> \ 2693 </tr> \ 2694 </table> */ \ 2695 void (*SetRefCon)(IOFireWireLibCommandRef self, void* refCon) ; \ 2696 /*! @function IsExecuting \ 2697 @abstract Is this command object currently executing? \ 2698 @discussion Availability: (for interfaces obtained with ID) \ 2699 <table border="0" rules="all"> \ 2700 <tr> \ 2701 <td width="20%"></td> \ 2702 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2703 <td>YES</td> \ 2704 </tr> \ 2705 <tr> \ 2706 <td width="20%"></td> \ 2707 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2708 <td>YES</td> \ 2709 </tr> \ 2710 <tr> \ 2711 <td width="20%"></td> \ 2712 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2713 <td>YES</td> \ 2714 </tr> \ 2715 <tr> \ 2716 <td width="20%"></td> \ 2717 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2718 <td>YES</td> \ 2719 </tr> \ 2720 <tr> \ 2721 <td width="20%"></td> \ 2722 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2723 <td>YES</td> \ 2724 </tr> \ 2725 <tr> \ 2726 <td width="20%"></td> \ 2727 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2728 <td>YES</td> \ 2729 </tr> \ 2730 <tr> \ 2731 <td width="20%"></td> \ 2732 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2733 <td>YES</td> \ 2734 </tr> \ 2735 <tr> \ 2736 <td width="20%"></td> \ 2737 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2738 <td>YES</td> \ 2739 </tr> \ 2740 </table> \ 2741 @param self The command object interface of interest \ 2742 @result Returns true if the command object is executing. */ \ 2743 const Boolean (*IsExecuting)(IOFireWireLibCommandRef self) ; \ 2744 /*! Description forthcoming */ \ 2745 IOReturn (*Submit)(IOFireWireLibCommandRef self) ; \ 2746 /*! @function Submit \ 2747 @abstract Submit this command object to FireWire for execution. \ 2748 @discussion Availability: (for interfaces obtained with ID) \ 2749 <table border="0" rules="all"> \ 2750 <tr> \ 2751 <td width="20%"></td> \ 2752 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2753 <td>YES</td> \ 2754 </tr> \ 2755 <tr> \ 2756 <td width="20%"></td> \ 2757 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2758 <td>YES</td> \ 2759 </tr> \ 2760 <tr> \ 2761 <td width="20%"></td> \ 2762 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2763 <td>YES</td> \ 2764 </tr> \ 2765 <tr> \ 2766 <td width="20%"></td> \ 2767 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2768 <td>YES</td> \ 2769 </tr> \ 2770 <tr> \ 2771 <td width="20%"></td> \ 2772 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2773 <td>YES</td> \ 2774 </tr> \ 2775 <tr> \ 2776 <td width="20%"></td> \ 2777 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2778 <td>YES</td> \ 2779 </tr> \ 2780 <tr> \ 2781 <td width="20%"></td> \ 2782 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2783 <td>YES</td> \ 2784 </tr> \ 2785 <tr> \ 2786 <td width="20%"></td> \ 2787 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2788 <td>YES</td> \ 2789 </tr> \ 2790 </table> \ 2791 @param self The command object interface of interest \ 2792 @result An IOReturn result code indicating whether or not the command was successfully \ 2793 submitted */ \ 2794 /*! @function SubmitWithRefconAndCallback \ 2795 @abstract Set the command refCon value and callback handler, and submit the command \ 2796 to FireWire for execution. \ 2797 @discussion Availability: (for interfaces obtained with ID) \ 2798 <table border="0" rules="all"> \ 2799 <tr> \ 2800 <td width="20%"></td> \ 2801 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2802 <td>YES</td> \ 2803 </tr> \ 2804 <tr> \ 2805 <td width="20%"></td> \ 2806 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2807 <td>YES</td> \ 2808 </tr> \ 2809 <tr> \ 2810 <td width="20%"></td> \ 2811 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2812 <td>YES</td> \ 2813 </tr> \ 2814 <tr> \ 2815 <td width="20%"></td> \ 2816 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2817 <td>YES</td> \ 2818 </tr> \ 2819 <tr> \ 2820 <td width="20%"></td> \ 2821 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2822 <td>YES</td> \ 2823 </tr> \ 2824 <tr> \ 2825 <td width="20%"></td> \ 2826 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2827 <td>YES</td> \ 2828 </tr> \ 2829 <tr> \ 2830 <td width="20%"></td> \ 2831 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2832 <td>YES</td> \ 2833 </tr> \ 2834 <tr> \ 2835 <td width="20%"></td> \ 2836 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2837 <td>YES</td> \ 2838 </tr> \ 2839 </table> \ 2840 @param self The command object interface of interest \ 2841 @result An IOReturn result code indicating whether or not the command was successfully \ 2842 submitted */ \ 2843 IOReturn (*SubmitWithRefconAndCallback)(IOFireWireLibCommandRef self, void* refCon, IOFireWireLibCommandCallback inCallback) ;\ 2844 /*! @function Cancel \ 2845 @abstract Cancel command execution \ 2846 @discussion Availability: (for interfaces obtained with ID) \ 2847 <table border="0" rules="all"> \ 2848 <tr> \ 2849 <td width="20%"></td> \ 2850 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2851 <td>YES</td> \ 2852 </tr> \ 2853 <tr> \ 2854 <td width="20%"></td> \ 2855 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2856 <td>YES</td> \ 2857 </tr> \ 2858 <tr> \ 2859 <td width="20%"></td> \ 2860 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2861 <td>YES</td> \ 2862 </tr> \ 2863 <tr> \ 2864 <td width="20%"></td> \ 2865 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2866 <td>YES</td> \ 2867 </tr> \ 2868 <tr> \ 2869 <td width="20%"></td> \ 2870 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2871 <td>YES</td> \ 2872 </tr> \ 2873 <tr> \ 2874 <td width="20%"></td> \ 2875 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2876 <td>YES</td> \ 2877 </tr> \ 2878 <tr> \ 2879 <td width="20%"></td> \ 2880 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2881 <td>YES</td> \ 2882 </tr> \ 2883 <tr> \ 2884 <td width="20%"></td> \ 2885 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2886 <td>YES</td> \ 2887 </tr> \ 2888 </table> \ 2889 @param self The command object interface of interest \ 2890 @result An IOReturn result code */ \ 2891 IOReturn (*Cancel)(IOFireWireLibCommandRef self, IOReturn reason) 2892 2893/*! @parseOnly */ 2894#define IOFIREWIRELIBCOMMAND_C_GUTS_v2 \ 2895 /*! @function SetBuffer \ 2896 @abstract Set the buffer where read data should be stored. \ 2897 @discussion Availability: (for interfaces obtained with ID) \ 2898 <table border="0" rules="all"> \ 2899 <tr> \ 2900 <td width="20%"></td> \ 2901 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2902 <td>NO</td> \ 2903 </tr> \ 2904 <tr> \ 2905 <td width="20%"></td> \ 2906 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2907 <td>YES</td> \ 2908 </tr> \ 2909 <tr> \ 2910 <td width="20%"></td> \ 2911 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2912 <td>NO</td> \ 2913 </tr> \ 2914 <tr> \ 2915 <td width="20%"></td> \ 2916 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2917 <td>YES</td> \ 2918 </tr> \ 2919 <tr> \ 2920 <td width="20%"></td> \ 2921 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2922 <td>NO</td> \ 2923 </tr> \ 2924 <tr> \ 2925 <td width="20%"></td> \ 2926 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2927 <td>NO</td> \ 2928 </tr> \ 2929 <tr> \ 2930 <td width="20%"></td> \ 2931 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2932 <td>NO</td> \ 2933 </tr> \ 2934 <tr> \ 2935 <td width="20%"></td> \ 2936 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2937 <td>YES</td> \ 2938 </tr> \ 2939 </table> \ 2940 @param self The command object interface of interest \ 2941 @param size Size in bytes of the receive buffer. \ 2942 @param buf A pointer to the receive buffer. */ \ 2943 void (*SetBuffer)(IOFireWireLibCommandRef self, UInt32 size, void* buf) ; \ 2944 /*! @function GetBuffer \ 2945 @abstract Set the command refCon value and callback handler, and submit the command \ 2946 to FireWire for execution. \ 2947 @discussion Availability: (for interfaces obtained with ID) \ 2948 <table border="0" rules="all"> \ 2949 <tr> \ 2950 <td width="20%"></td> \ 2951 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2952 <td>NO</td> \ 2953 </tr> \ 2954 <tr> \ 2955 <td width="20%"></td> \ 2956 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 2957 <td>YES</td> \ 2958 </tr> \ 2959 <tr> \ 2960 <td width="20%"></td> \ 2961 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 2962 <td>NO</td> \ 2963 </tr> \ 2964 <tr> \ 2965 <td width="20%"></td> \ 2966 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 2967 <td>YES</td> \ 2968 </tr> \ 2969 <tr> \ 2970 <td width="20%"></td> \ 2971 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 2972 <td>NO</td> \ 2973 </tr> \ 2974 <tr> \ 2975 <td width="20%"></td> \ 2976 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 2977 <td>NO</td> \ 2978 </tr> \ 2979 <tr> \ 2980 <td width="20%"></td> \ 2981 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 2982 <td>NO</td> \ 2983 </tr> \ 2984 <tr> \ 2985 <td width="20%"></td> \ 2986 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 2987 <td>YES</td> \ 2988 </tr> \ 2989 </table> \ 2990 @param self The command object interface of interest */ \ 2991 void (*GetBuffer)(IOFireWireLibCommandRef self, UInt32* outSize, void** outBuf) ; \ 2992 /*! @function SetMaxPacket \ 2993 @abstract Set the maximum size in bytes of packets transferred by this command. \ 2994 @discussion Availability: (for interfaces obtained with ID) \ 2995 <table border="0" rules="all"> \ 2996 <tr> \ 2997 <td width="20%"></td> \ 2998 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 2999 <td>NO</td> \ 3000 </tr> \ 3001 <tr> \ 3002 <td width="20%"></td> \ 3003 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 3004 <td>YES</td> \ 3005 </tr> \ 3006 <tr> \ 3007 <td width="20%"></td> \ 3008 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 3009 <td>NO</td> \ 3010 </tr> \ 3011 <tr> \ 3012 <td width="20%"></td> \ 3013 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 3014 <td>YES</td> \ 3015 </tr> \ 3016 <tr> \ 3017 <td width="20%"></td> \ 3018 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 3019 <td>NO</td> \ 3020 </tr> \ 3021 <tr> \ 3022 <td width="20%"></td> \ 3023 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 3024 <td>NO</td> \ 3025 </tr> \ 3026 <tr> \ 3027 <td width="20%"></td> \ 3028 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 3029 <td>NO</td> \ 3030 </tr> \ 3031 <tr> \ 3032 <td width="20%"></td> \ 3033 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 3034 <td>YES</td> \ 3035 </tr> \ 3036 </table> \ 3037 @param self The command object interface of interest \ 3038 @param maxPacketSize Size in bytes of largest packet that should be transferred \ 3039 by this command. \ 3040 @result An IOReturn result code indicating whether or not the command was successfully \ 3041 submitted */ \ 3042 IOReturn (*SetMaxPacket)(IOFireWireLibCommandRef self, IOByteCount maxPacketSize) ; \ 3043 /*! @function SetFlags \ 3044 @abstract Set flags governing this command's execution. \ 3045 @discussion Availability: (for interfaces obtained with ID) \ 3046 <table border="0" rules="all"> \ 3047 <tr> \ 3048 <td width="20%"></td> \ 3049 <td><code>kIOFireWireReadCommandInterfaceID</code></td> \ 3050 <td>NO</td> \ 3051 </tr> \ 3052 <tr> \ 3053 <td width="20%"></td> \ 3054 <td><code>kIOFireWireReadCommandInterfaceID_v2</code></td> \ 3055 <td>YES</td> \ 3056 </tr> \ 3057 <tr> \ 3058 <td width="20%"></td> \ 3059 <td><code>kIOFireWireWriteCommandInterfaceID</code></td> \ 3060 <td>NO</td> \ 3061 </tr> \ 3062 <tr> \ 3063 <td width="20%"></td> \ 3064 <td><code>kIOFireWireWriteCommandInterfaceID_v2</code></td> \ 3065 <td>YES</td> \ 3066 </tr> \ 3067 <tr> \ 3068 <td width="20%"></td> \ 3069 <td><code>kIOFireWireReadQuadletCommandInterfaceID</code></td> \ 3070 <td>NO</td> \ 3071 </tr> \ 3072 <tr> \ 3073 <td width="20%"></td> \ 3074 <td><code>kIOFireWireWriteQuadletCommandInterfaceID</code></td> \ 3075 <td>NO</td> \ 3076 </tr> \ 3077 <tr> \ 3078 <td width="20%"></td> \ 3079 <td><code>kIOFireWireCompareSwapCommandInterfaceID</code></td> \ 3080 <td>NO</td> \ 3081 </tr> \ 3082 <tr> \ 3083 <td width="20%"></td> \ 3084 <td><code>kIOFireWireAsyncStreamCommandInterfaceID</code></td> \ 3085 <td>YES</td> \ 3086 </tr> \ 3087 </table> \ 3088 @param self The command object interface of interest \ 3089 @param inFlags A UInt32 with bits set corresponding to the flags that should be set \ 3090 for this command object. The following values may be used:<br> \ 3091 <ul> \ 3092 <li>kFWCommandNoFlags -- all flags off</li> \ 3093 <li>kFWCommandInterfaceForceNoCopy -- data sent by this command should always be \ 3094 received/sent directly from the buffer set with SetBuffer(). Whatever data \ 3095 is in the buffer when the command is submitted will be used.</li> \ 3096 <li>kFWCommandInterfaceForceCopyAlways -- data will always be copied out of the \ 3097 command object data buffer when SetBuffer() is called, up to a maximum \ 3098 allowed size (kFWUserCommandSubmitWithCopyMaxBufferBytes). This can result \ 3099 in faster data transfer. Changes made to the data buffer contents after \ 3100 calling SetBuffer() will be ignored; SetBuffer() should be called whenever \ 3101 the data buffer contents change.</li> \ 3102 <li>kFWCommandInterfaceSyncExecute -- Setting this flag causes the command object \ 3103 to execute synchronously. The calling context will block until the command \ 3104 object has completed execution or an error occurs. Using synchronous execution \ 3105 can avoid kernel transitions associated with asynchronous completion and often \ 3106 remove the need for a state machine.</li> \ 3107 <li>kFWCommandInterfaceForceBlockRequest -- Setting this flag causes read and write \ 3108 transactions to use block request packets even if the payload is 4 bytes. If this \ 3109 flag is not set 4 byte transactions will occur using quadlet transactions.</li> \ 3110 </ul>*/ \ 3111 void (*SetFlags)(IOFireWireLibCommandRef self, UInt32 inFlags) 3112 3113/*! @parseOnly */ 3114#define IOFIREWIRELIBCOMMAND_C_GUTS_v3 \ 3115 /*! @function SetTimeoutDuration \ 3116 @abstract Sets the duration of the timeout for this command. \ 3117 @param self A reference to the command \ 3118 @param duration A timeout value in microseconds \ 3119 @result void */ \ 3120 void (*SetTimeoutDuration)(IOFireWireLibCommandRef self, UInt32 duration ); \ 3121 /*! @function SetMaxRetryCount \ 3122 @abstract Sets the maximum number of retries for this command. \ 3123 @param self A reference to the command \ 3124 @param count The number of retires \ 3125 @result void */ \ 3126 void (*SetMaxRetryCount)(IOFireWireLibCommandRef self, UInt32 count ); \ 3127 /*! @function GetAckCode \ 3128 @abstract Gets the most recently received ack code for this transaction. \ 3129 @param self A reference to the command \ 3130 @result The FireWire ack code. */ \ 3131 UInt32 (*GetAckCode)( IOFireWireLibCommandRef self ); \ 3132 /*! @function GetResponseCode \ 3133 @abstract Gets the most recently received response code for this transaction. \ 3134 @param self A reference to the command \ 3135 @result The FireWire response code. */ \ 3136 UInt32 (*GetResponseCode)( IOFireWireLibCommandRef self ); \ 3137 /*! @function SetMaxPacketSpeed \ 3138 @abstract Gets the most recently received ack code for this transaction. \ 3139 @param self A reference to the command \ 3140 @param speed the desired maximum packet speed \ 3141 @result void */ \ 3142 void (*SetMaxPacketSpeed)( IOFireWireLibCommandRef self, IOFWSpeed speed ); \ 3143 /*! @function GetRefCon \ 3144 @abstract Gets the refcon associated with this command \ 3145 @param self A reference to the command \ 3146 @result void */ \ 3147 void * (*GetRefCon)( IOFireWireLibCommandRef self ) 3148 3149/*! @class 3150 @abstract IOFireWireLib command object. 3151 @discussion Represents an object that is configured and submitted to issue synchronous 3152 and asynchronous bus commands. This is a superclass containing all command object 3153 functionality not specific to any kind of bus transaction. 3154 3155 Note that data may not always be transferred to or from the data buffer 3156 for command objects at the time the command is submitted. In some cases the 3157 transfer may happen as soon as SetBuffer() (below, v2 interfaces and newer) 3158 is called. You can use the SetFlags() call (below, v2 interfaces and newer) to 3159 control this behavior. 3160 3161*/ 3162typedef struct IOFireWireCommandInterface_t 3163{ 3164 3165 IUNKNOWN_C_GUTS ; 3166 3167 /*! Interface version */ 3168 UInt32 version; 3169 3170 /*! Interface revision */ 3171 UInt32 revision; 3172 3173 /* IMPORTANT: Do not add HeaderDoc markup to the following symbols; they 3174 contain HeaderDoc markup, and that would be bad. 3175 */ 3176 3177 IOFIREWIRELIBCOMMAND_C_GUTS ; 3178 3179 // version 2 interfaces: (appear in IOFireWireReadCommandInterface_v2 and IOFireWireWriteCommandInterface_v2) 3180 IOFIREWIRELIBCOMMAND_C_GUTS_v2 ; 3181 3182 IOFIREWIRELIBCOMMAND_C_GUTS_v3 ; 3183 3184} IOFireWireCommandInterface ; 3185 3186/*! @class 3187 @abstract IOFireWireLib block read command object. 3188 @discussion Represents an object that is configured and submitted to issue synchronous 3189 and asynchronous block read commands. 3190 3191 This interface contains all methods of IOFireWireCommandInterface. 3192 This interface will contain all v2 methods of IOFireWireCommandInterface 3193 when instantiated as v2 or newer. */ 3194typedef struct IOFireWireReadCommandInterface_t 3195{ 3196 3197 IUNKNOWN_C_GUTS ; 3198 3199 /*! Interface version. */ 3200 UInt32 version; 3201 3202 /*! Interface revision. */ 3203 UInt32 revision; 3204 3205 IOFIREWIRELIBCOMMAND_C_GUTS ; 3206 3207 // following functions 3208 // available only in IOFireWireReadCommandInterface interface v2 and newer 3209 IOFIREWIRELIBCOMMAND_C_GUTS_v2 ; 3210 3211 IOFIREWIRELIBCOMMAND_C_GUTS_v3 ; 3212} IOFireWireReadCommandInterface ; 3213 3214/*! @class 3215 @abstract IOFireWireLib block read command object. 3216 @discussion Represents an object that is configured and submitted to issue synchronous 3217 and asynchronous block read commands. 3218 3219 This interface contains all methods of IOFireWireCommandInterface. 3220 This interface will contain all v2 methods of IOFireWireCommandInterface 3221 when instantiated as v2 or newer. */ 3222typedef struct IOFireWireWriteCommandInterface_t 3223{ 3224 3225 IUNKNOWN_C_GUTS ; 3226 3227 /*! Interface version. */ 3228 UInt32 version; 3229 3230 /*! Interface revision. */ 3231 UInt32 revision; 3232 3233 IOFIREWIRELIBCOMMAND_C_GUTS ; 3234 3235 // following functions 3236 // available only in IOFireWireWriteCommandInterface_v2 and newer 3237 IOFIREWIRELIBCOMMAND_C_GUTS_v2 ; 3238 3239 IOFIREWIRELIBCOMMAND_C_GUTS_v3 ; 3240 3241} IOFireWireWriteCommandInterface ; 3242 3243 3244/*! @class 3245 Description forthcoming 3246*/ 3247typedef struct IOFireWireCompareSwapCommandInterface_t 3248{ 3249 IUNKNOWN_C_GUTS ; 3250 3251 /*! Interface version. */ 3252 UInt32 version; 3253 3254 /*! Interface revision. */ 3255 UInt32 revision; 3256 3257 IOFIREWIRELIBCOMMAND_C_GUTS ; 3258 3259 /*! @function SetValues 3260 @abstract Set values for 32-bit compare swap operation. Calling this function will 3261 make the command object perform 32-bit compare swap transactions on the bus. To perform 3262 64-bit compare swap operations, use the SetValues64() call, below. 3263 @discussion Available in v2 and newer. 3264 @param self The command object interface of interest 3265 @param cmpVal The value expected at the address targeted by this command object 3266 @param newVal The value to be written at the address targeted by this command object */ 3267 void (*SetValues)(IOFireWireLibCompareSwapCommandRef self, UInt32 cmpVal, UInt32 newVal) ; 3268 3269 // --- v2 --- 3270 3271 /*! @function SetValues64 3272 @abstract Set values for 64-bit compare swap operation. Calling this function will 3273 make the command object perform 64-bit compare swap transactions on the bus. To perform 3274 32-bit compare swap operations, use the SetValues() call, above. 3275 @discussion Available in v2 and newer. 3276 @param self The command object interface of interest 3277 @param cmpVal The value expected at the address targeted by this command object 3278 @param newVal The value to be written at the address targeted by this command object */ 3279 void (*SetValues64)(IOFireWireLibCompareSwapCommandRef self, UInt64 cmpVal, UInt64 newVal) ; 3280 3281 /*! @function DidLock 3282 @abstract Was the last lock operation successful? 3283 @discussion Available in v2 and newer. 3284 @param self The command object interface of interest 3285 @result Returns true if the last lock operation performed by this command object was successful, 3286 false otherwise. */ 3287 Boolean (*DidLock)(IOFireWireLibCompareSwapCommandRef self) ; 3288 3289 /*! @function Locked 3290 @abstract Get the 32-bit value returned on the last compare swap operation. 3291 @discussion Available in v2 and newer. 3292 @param self The command object interface of interest 3293 @param oldValue A pointer to contain the value returned by the target of this command 3294 on the last compare swap operation 3295 @result Returns kIOReturnBadArgument if the last compare swap operation performed was 64-bit. */ 3296 IOReturn (*Locked)(IOFireWireLibCompareSwapCommandRef self, UInt32* oldValue) ; 3297 3298 /*! @function Locked64 3299 @abstract Get the 64-bit value returned on the last compare swap operation. 3300 @discussion Available in v2 and newer. 3301 @param self The command object interface of interest 3302 @param oldValue A pointer to contain the value returned by the target of this command 3303 on the last compare swap operation 3304 @result Returns kIOReturnBadArgument if the last compare swap performed was 32-bit. */ 3305 IOReturn (*Locked64)(IOFireWireLibCompareSwapCommandRef self, UInt64* oldValue) ; 3306 3307 /*! @function SetFlags 3308 @abstract Set flags governing this command's execution. 3309 @discussion Available in v2 and newer. Same as SetFlags() above. 3310 @param self The command object interface of interest. 3311 @param inFlags A UInt32 with bits set corresponding to the flags that should be set. */ 3312 void (*SetFlags)(IOFireWireLibCompareSwapCommandRef self, UInt32 inFlags) ; 3313 3314} IOFireWireCompareSwapCommandInterface ; 3315 3316/*! @class 3317 Description forthcoming 3318*/ 3319typedef struct IOFireWireCompareSwapCommandInterface_v3_t 3320{ 3321 3322 IUNKNOWN_C_GUTS ; 3323 3324 /*! Interface version. */ 3325 UInt32 version; 3326 3327 /*! Interface version. */ 3328 UInt32 revision; 3329 3330 IOFIREWIRELIBCOMMAND_C_GUTS; 3331 3332 IOFIREWIRELIBCOMMAND_C_GUTS_v2; 3333 3334 IOFIREWIRELIBCOMMAND_C_GUTS_v3; 3335 3336 /*! @function SetValues 3337 @abstract Set values for 32-bit compare swap operation. Calling this function will 3338 make the command object perform 32-bit compare swap transactions on the bus. To perform 3339 64-bit compare swap operations, use the SetValues64() call, below. 3340 @discussion Available in v2 and newer. 3341 @param self The command object interface of interest 3342 @param cmpVal The value expected at the address targeted by this command object 3343 @param newVal The value to be written at the address targeted by this command object */ 3344 void (*SetValues)(IOFireWireLibCompareSwapCommandV3Ref self, UInt32 cmpVal, UInt32 newVal) ; 3345 3346 // --- v2 --- 3347 3348 /*! @function SetValues64 3349 @abstract Set values for 64-bit compare swap operation. Calling this function will 3350 make the command object perform 64-bit compare swap transactions on the bus. To perform 3351 32-bit compare swap operations, use the SetValues() call, above. 3352 @discussion Available in v2 and newer. 3353 @param self The command object interface of interest 3354 @param cmpVal The value expected at the address targeted by this command object 3355 @param newVal The value to be written at the address targeted by this command object */ 3356 void (*SetValues64)(IOFireWireLibCompareSwapCommandV3Ref self, UInt64 cmpVal, UInt64 newVal) ; 3357 3358 /*! @function DidLock 3359 @abstract Was the last lock operation successful? 3360 @discussion Available in v2 and newer. 3361 @param self The command object interface of interest 3362 @result Returns true if the last lock operation performed by this command object was successful, 3363 false otherwise. */ 3364 Boolean (*DidLock)(IOFireWireLibCompareSwapCommandV3Ref self) ; 3365 3366 /*! @function Locked 3367 @abstract Get the 32-bit value returned on the last compare swap operation. 3368 @discussion Available in v2 and newer. 3369 @param self The command object interface of interest 3370 @param oldValue A pointer to contain the value returned by the target of this command 3371 on the last compare swap operation 3372 @result Returns kIOReturnBadArgument if the last compare swap operation performed was 64-bit. */ 3373 IOReturn (*Locked)(IOFireWireLibCompareSwapCommandV3Ref self, UInt32* oldValue) ; 3374 3375 /*! @function Locked64 3376 @abstract Get the 64-bit value returned on the last compare swap operation. 3377 @discussion Available in v2 and newer. 3378 @param self The command object interface of interest 3379 @param oldValue A pointer to contain the value returned by the target of this command 3380 on the last compare swap operation 3381 @result Returns kIOReturnBadArgument if the last compare swap performed was 32-bit. */ 3382 IOReturn (*Locked64)(IOFireWireLibCompareSwapCommandV3Ref self, UInt64* oldValue) ; 3383 3384} IOFireWireCompareSwapCommandInterface_v3 ; 3385 3386/*! @class 3387 Description forthcoming 3388*/ 3389typedef struct IOFireWirePHYCommandInterface_t 3390{ 3391 IUNKNOWN_C_GUTS ; 3392 3393 /*! Interface version. */ 3394 UInt32 version; 3395 3396 /*! Interface revision. */ 3397 UInt32 revision; 3398 3399 IOFIREWIRELIBCOMMAND_C_GUTS; 3400 3401 IOFIREWIRELIBCOMMAND_C_GUTS_v2; 3402 3403 IOFIREWIRELIBCOMMAND_C_GUTS_v3; 3404 3405 /*! @function SetDataQuads 3406 @abstract Set the 2 quadlets of data to be sent in a PHY packet. 3407 @discussion Available in v1 and newer. 3408 @param self The command object interface of interest 3409 @param data1 The value of the first quad of the phy packet 3410 @param data2 The value of the second quad of the phy packet */ 3411 void (*SetDataQuads)( IOFireWireLibPHYCommandRef self, UInt32 data1, UInt32 data2 ); 3412 3413} IOFireWirePHYCommandInterface; 3414 3415/*! @class 3416 Description forthcoming 3417*/ 3418typedef struct IOFireWireAsyncStreamCommandInterface_t 3419{ 3420 IUNKNOWN_C_GUTS ; 3421 3422 /*! Interface version. */ 3423 UInt32 version; 3424 3425 /*! Interface revision. */ 3426 UInt32 revision; 3427 3428 IOFIREWIRELIBCOMMAND_C_GUTS; 3429 3430 IOFIREWIRELIBCOMMAND_C_GUTS_v2; 3431 3432 IOFIREWIRELIBCOMMAND_C_GUTS_v3; 3433 3434 /*! @function SetChannel 3435 @abstract Set the new channel to transmit the AsyncStream command. 3436 @discussion Available in v1 and newer. 3437 @param self The command object interface of interest 3438 @param channel The channel for AsyncStream command transmit.*/ 3439 void (*SetChannel)( IOFireWireLibAsyncStreamCommandRef self, UInt32 channel ); 3440 3441 /*! @function SetSyncBits 3442 @abstract Set the sync bits for the AsynStream packets. 3443 @discussion Available in v1 and newer. 3444 @param self The command object interface of interest 3445 @param sync The value for sync bits in the AsyncStream packet */ 3446 void (*SetSyncBits)( IOFireWireLibAsyncStreamCommandRef self, UInt16 sync ); 3447 3448 /*! @function SetTagBits 3449 @abstract Set the tag bits for the AsynStream packets. 3450 @discussion Available in v1 and newer. 3451 @param self The command object interface of interest 3452 @param tag The value for tag bits in the AsyncStream packet */ 3453 void (*SetTagBits)( IOFireWireLibAsyncStreamCommandRef self, UInt16 tag ); 3454 3455} IOFireWireAsyncStreamCommandInterface; 3456 3457/*! @class 3458 @abstract IOFireWireReadQuadletCommandInterface -- IOFireWireLib quadlet read command object. 3459 @discussion Obsolete; do not use. Use IOFireWireReadCommandInterface v2 or newer 3460 and its function SetMaxPacket() */ 3461typedef struct IOFireWireReadQuadletCommandInterface_t 3462{ 3463 IUNKNOWN_C_GUTS ; 3464 3465 /*! Interface version. */ 3466 UInt32 version; 3467 3468 /*! Interface revision. */ 3469 UInt32 revision; 3470 3471 IOFIREWIRELIBCOMMAND_C_GUTS ; 3472 3473 /*! @function SetQuads 3474 @abstract Set destination for read data 3475 @param self The command object interface of interest 3476 @param inQuads An array of quadlets 3477 @param inNumQuads Number of quadlet in 'inQuads' */ 3478 void (*SetQuads)(IOFireWireLibReadQuadletCommandRef self, UInt32 inQuads[], UInt32 inNumQuads) ; 3479} IOFireWireReadQuadletCommandInterface ; 3480 3481/*! @class 3482 @abstract IOFireWireLib quadlet read command object. 3483 @discussion Obsolete; do not use. Use IOFireWireWriteCommandInterface v2 or newer 3484 and its function SetMaxPacket() */ 3485typedef struct IOFireWireWriteQuadletCommandInterface_t 3486{ 3487 IUNKNOWN_C_GUTS ; 3488 3489 /*! Interface version. */ 3490 UInt32 version; 3491 3492 /*! Interface revision. */ 3493 UInt32 revision; 3494 3495 IOFIREWIRELIBCOMMAND_C_GUTS ; 3496 3497 /*! IOFireWireLibWriteQuadletCommandRef */ 3498 void (*SetQuads)(IOFireWireLibWriteQuadletCommandRef self, UInt32 inQuads[], UInt32 inNumQuads) ; 3499 3500} IOFireWireWriteQuadletCommandInterface ; 3501 3502#pragma mark - 3503#pragma mark CONFIG DIRECTORY INTERFACE 3504// ============================================================ 3505// IOFireWireConfigDirectoryInterface 3506// ============================================================ 3507 3508 3509/*! @class 3510 @abstract IOFireWireLib device config ROM browsing interface 3511 @discussion Represents an interface to the config ROM of a remote device. You can use the 3512 methods of this interface to browser the ROM and obtain key values. You can also 3513 create additional IOFireWireConfigDirectoryInterface's to represent subdirectories 3514 within the ROM.*/ 3515typedef struct IOFireWireConfigDirectoryInterface_t 3516{ 3517 3518 IUNKNOWN_C_GUTS ; 3519 3520 /*! Interface version. */ 3521 UInt32 version; 3522 3523 /*! Interface revision. */ 3524 UInt32 revision ; 3525 3526 /*! @function Update 3527 @abstract Causes the ROM data to be updated through the specified byte offset. This 3528 function should not be called in normal usage. 3529 @param self The config directory interface of interest 3530 @param inOffset Offset in bytes indicating length of ROM to be updated. 3531 @result An IOReturn result code */ 3532 IOReturn (*Update) ( IOFireWireLibConfigDirectoryRef self, UInt32 inOffset) ; 3533 3534 /*! Description forthcoming */ 3535 IOReturn (*GetKeyType) ( IOFireWireLibConfigDirectoryRef self, int inKey, IOConfigKeyType* outType); 3536 /*! Description forthcoming */ 3537 IOReturn (*GetKeyValue_UInt32) ( IOFireWireLibConfigDirectoryRef self, int inKey, UInt32* outValue, CFStringRef* outText); 3538 /*! Description forthcoming */ 3539 IOReturn (*GetKeyValue_Data) ( IOFireWireLibConfigDirectoryRef self, int inKey, CFDataRef* outValue, CFStringRef* outText); 3540 /*! Description forthcoming */ 3541 IOReturn (*GetKeyValue_ConfigDirectory) ( IOFireWireLibConfigDirectoryRef self, int inKey, IOFireWireLibConfigDirectoryRef* outValue, REFIID iid, CFStringRef* outText); 3542 /*! Description forthcoming */ 3543 IOReturn (*GetKeyOffset_FWAddress) ( IOFireWireLibConfigDirectoryRef self, int inKey, FWAddress* outValue, CFStringRef* text); 3544 /*! Description forthcoming */ 3545 IOReturn (*GetIndexType) ( IOFireWireLibConfigDirectoryRef self, int inIndex, IOConfigKeyType* type); 3546 /*! Description forthcoming */ 3547 IOReturn (*GetIndexKey) ( IOFireWireLibConfigDirectoryRef self, int inIndex, int * key); 3548 /*! Description forthcoming */ 3549 IOReturn (*GetIndexValue_UInt32) ( IOFireWireLibConfigDirectoryRef self, int inIndex, UInt32 * value); 3550 /*! Description forthcoming */ 3551 IOReturn (*GetIndexValue_Data) ( IOFireWireLibConfigDirectoryRef self, int inIndex, CFDataRef * value); 3552 /*! Description forthcoming */ 3553 IOReturn (*GetIndexValue_String) ( IOFireWireLibConfigDirectoryRef self, int inIndex, CFStringRef* outValue); 3554 /*! Description forthcoming */ 3555 IOReturn (*GetIndexValue_ConfigDirectory) ( IOFireWireLibConfigDirectoryRef self, int inIndex, IOFireWireLibConfigDirectoryRef* outValue, REFIID iid); 3556 /*! Description forthcoming */ 3557 IOReturn (*GetIndexOffset_FWAddress) ( IOFireWireLibConfigDirectoryRef self, int inIndex, FWAddress* outValue); 3558 /*! Description forthcoming */ 3559 IOReturn (*GetIndexOffset_UInt32) ( IOFireWireLibConfigDirectoryRef self, int inIndex, UInt32* outValue); 3560 /*! Description forthcoming */ 3561 IOReturn (*GetIndexEntry) ( IOFireWireLibConfigDirectoryRef self, int inIndex, UInt32* outValue); 3562 /*! Description forthcoming */ 3563 IOReturn (*GetSubdirectories) ( IOFireWireLibConfigDirectoryRef self, io_iterator_t* outIterator); 3564 /*! Description forthcoming */ 3565 IOReturn (*GetKeySubdirectories) ( IOFireWireLibConfigDirectoryRef self, int inKey, io_iterator_t* outIterator); 3566 /*! Description forthcoming */ 3567 IOReturn (*GetType) ( IOFireWireLibConfigDirectoryRef self, int* outType) ; 3568 /*! Description forthcoming */ 3569 IOReturn (*GetNumEntries) ( IOFireWireLibConfigDirectoryRef self, int* outNumEntries) ; 3570 3571} IOFireWireConfigDirectoryInterface ; 3572 3573/*! Description forthcoming */ 3574CF_INLINE IOVirtualRange 3575IOVirtualRangeMake( IOVirtualAddress address, IOByteCount length ) 3576{ 3577 IOVirtualRange range ; 3578 range.address = address ; 3579 range.length = length ; 3580 return range ; 3581} 3582 3583#pragma mark - 3584#pragma mark VECTOR COMMAND INTERFACE 3585// ============================================================ 3586// IOFireWireVectorCommandInterface 3587// ============================================================ 3588 3589 3590/*! @class 3591 @abstract IOFireWireLib command object for grouping commands execution. 3592 @discussion Read and Write commands can be attached in order to the vector command. When 3593 the vector command is submitted all the commands are sent to the kernel for execution. 3594 When all the commands in a vector command are complete the vector command's completion is called. 3595 The advantage over submitting and completeing each command simultaneously is that only one kernel transition 3596 will be used for submission and one for completion, regardless of the number of commands in the vector.*/ 3597typedef struct IOFireWireLibVectorCommandInterface_t 3598{ 3599 3600 IUNKNOWN_C_GUTS ; 3601 3602 /*! Interface version. */ 3603 UInt32 version; 3604 3605 /*! Interface revision. */ 3606 UInt32 revision; 3607 3608 /*! @function Submit 3609 @abstract Submit this command object to FireWire for execution. 3610 @param self A reference to the vector command object 3611 @result An IOReturn result code */ 3612 3613 IOReturn (*Submit)(IOFireWireLibVectorCommandRef self); 3614 3615 /*! @function Submit 3616 @abstract Submit this command object to FireWire for execution. 3617 @discussion A convienence method to set the callback and refcon and then submit. 3618 @param self A reference to the vector command object 3619 @param refCon A reference constant for 3rd party use. This is the same refcon set with SetRefCon and retreived with GetRefCon. 3620 @param inCallback A callback function to be called upon command completion. 3621 @result An IOReturn result code */ 3622 3623 IOReturn (*SubmitWithRefconAndCallback)(IOFireWireLibVectorCommandRef self, void* refCon, IOFireWireLibCommandCallback inCallback); 3624 3625 /*! @function IsExecuting 3626 @abstract Checks if the vector command is currently executing. 3627 @param self A reference to the vector command object 3628 @result True if the command is executing, false otherwise */ 3629 3630 Boolean (*IsExecuting)(IOFireWireLibVectorCommandRef self); 3631 3632 /*! @function SetCallback 3633 @abstract Set the callback routine for this command. 3634 @param self A reference to the vector command object 3635 @param inCallback A callback function to be called upon command completion. 3636 @result void */ 3637 3638 void (*SetCallback)(IOFireWireLibVectorCommandRef self, IOFireWireLibCommandCallback inCallback); 3639 3640 /*! @function SetRefCon 3641 @abstract Set the reference constant for this command. 3642 @param self A reference to the vector command object 3643 @param refCon A reference constant for 3rd party use. 3644 @result void */ 3645 3646 void (*SetRefCon)(IOFireWireLibVectorCommandRef self, void* refCon); 3647 3648 /*! @function GetRefCon 3649 @abstract Get the reference constant for this command. 3650 @param self A reference to the vector command object 3651 @result The reference contant set in SetRefCon */ 3652 3653 void * (*GetRefCon)(IOFireWireLibVectorCommandRef self); 3654 3655 /*! @function SetFlags 3656 @abstract Set flags governing this command's execution. 3657 @param self A reference to the vector command object 3658 @param inFlags A UInt32 with bits set corresponding to the flags that should be set 3659 for this command object. The following values may be used:<br> 3660 <ul> 3661 <li>kFWCommandNoFlags -- all flags off</li> 3662 <li>kFWCommandInterfaceSyncExecute -- Setting this flag causes the command object 3663 to execute synchronously. The calling context will block until the command 3664 object has completed execution or an error occurs. Using synchronous execution 3665 can avoid kernel transitions associated with asynchronous completion and often 3666 remove the need for a state machine.</li> 3667 <li>kFWVectorCommandInterfaceOrdered - Normally all commands in a vector are executed 3668 simultaneously. Setting this flag will dispatch a command only after the prior 3669 command has completed. 3670 </ul> 3671 @result void */ 3672 3673 void (*SetFlags)(IOFireWireLibVectorCommandRef self, UInt32 inFlags); 3674 3675 /*! @function GetFlags 3676 @abstract Get the flags currently set for this command. 3677 @param self A reference to the vector command object 3678 @result The flags set in SetFlags */ 3679 3680 UInt32 (*GetFlags)(IOFireWireLibVectorCommandRef self); 3681 3682 /*! @function EnsureCapacity 3683 @abstract Sets the number of commands this vector can hold. 3684 @discussion The vector can grow dynamically, but for performance 3685 reasons developers may want the storage preallocated for a certain 3686 number of commmands 3687 @param self A reference to the vector command object 3688 @param capacity The number of commands this vector command should expect to hold 3689 @result An IOReturn result code */ 3690 3691 IOReturn (*EnsureCapacity)(IOFireWireLibVectorCommandRef self, UInt32 capacity); 3692 3693 /*! @function AddCommand 3694 @abstract Adds a command to the vector command. 3695 @param self A reference to the vector command object 3696 @param command A reference to the command to add 3697 @result An IOReturn result code */ 3698 3699 void (*AddCommand)(IOFireWireLibVectorCommandRef self, IOFireWireLibCommandRef command); 3700 3701 /*! @function RemoveCommand 3702 @abstract Removes a command to the vector command. 3703 @param self A reference to the vector command object 3704 @param command A reference to the command to be removed 3705 @result An IOReturn result code */ 3706 3707 void (*RemoveCommand)(IOFireWireLibVectorCommandRef self, IOFireWireLibCommandRef command); 3708 3709 /*! @function InsertCommandAtIndex 3710 @abstract Inserts a command at a given index. Commands at and after 3711 this index will be moved to their next sequential index. 3712 @param self A reference to the vector command object 3713 @param command A reference to the command to be inserted 3714 @param index The index to insert the command at. 3715 */ 3716 3717 void (*InsertCommandAtIndex)(IOFireWireLibVectorCommandRef self, IOFireWireLibCommandRef command, UInt32 index); 3718 3719 /*! @function GetCommandAtIndex 3720 @abstract Returns the command at a given index. 3721 @discussion Returns kIOReturnBadArgument if the index is out of bounds. 3722 @param self A reference to the vector command object 3723 @param index The index to return a command from 3724 @result The IOFireWireLibCommandRef at the specified index on return */ 3725 3726 IOFireWireLibCommandRef (*GetCommandAtIndex)(IOFireWireLibVectorCommandRef self, UInt32 index); 3727 3728 /*! @function GetIndexOfCommand 3729 @abstract Returns the index of the specified command. 3730 @discussion Returns kIOReturnNotFound if the command does not exist in this vector. 3731 @param self A reference to the vector command object 3732 @param command The command in question 3733 @result The index of the specified command */ 3734 3735 UInt32 (*GetIndexOfCommand)(IOFireWireLibVectorCommandRef self, IOFireWireLibCommandRef command); 3736 3737 /*! @function RemoveCommandAtIndex 3738 @abstract Removes the command at a give index. Commands at and afte 3739 this index will be moved to their previous sequential index. 3740 @discussion Returns kIOReturnBadArgument if the index is out of bounds. 3741 @param self A reference to the vector command object 3742 @param index Will be set to the index of the specified command. 3743 */ 3744 3745 void (*RemoveCommandAtIndex)(IOFireWireLibVectorCommandRef self, UInt32 index); 3746 3747 /*! @function RemoveAllCommands 3748 @abstract Removes all commands from the vector. 3749 @param self A reference to the vector command object 3750 */ 3751 3752 void (*RemoveAllCommands)(IOFireWireLibVectorCommandRef self); 3753 3754 /*! @function GetCommandCount 3755 @abstract Returns the number of commands currently in this vector. 3756 @param self A reference to the vector command object 3757 @result UInt32 The number of commands in this vector */ 3758 3759 UInt32 (*GetCommandCount)(IOFireWireLibVectorCommandRef self); 3760 3761} IOFireWireLibVectorCommandInterface; 3762 3763#pragma mark - 3764#pragma mark PHY PACKET LISTENER INTERFACE 3765// ============================================================ 3766// IOFireWireLibPHYPacketListenerInterface Interface 3767// ============================================================ 3768 3769/*! @class 3770 @discussion Represents and provides management functions for a phy packet listener object. 3771*/ 3772typedef struct IOFireWireLibPHYPacketListenerInterface_t 3773{ 3774 IUNKNOWN_C_GUTS ; 3775 3776 /*! Interface version. */ 3777 UInt16 version; 3778 3779 /*! Interface revision. */ 3780 UInt16 revision; 3781 3782 /*! @function SetListenerCallback 3783 @abstract Set the callback that should be called to handle incoming phy packets 3784 @param self The PHY packet listener object. 3785 @param inCallback The callback to set. 3786 */ 3787 void (*SetListenerCallback)( IOFireWireLibPHYPacketListenerRef self, IOFireWireLibPHYPacketCallback inCallback ); 3788 3789 /*! @function SetSkippedPacketCallback 3790 @abstract Set the callback that should be called when incoming phy packets are 3791 dropped by the listener space. 3792 @param self The PHY packet listener object. 3793 @param inCallback The callback to set. 3794 */ 3795 void (*SetSkippedPacketCallback)( IOFireWireLibPHYPacketListenerRef self, IOFireWireLibPHYPacketSkippedCallback inCallback ); 3796 3797 /*! @function NotificationIsOn 3798 @abstract Is notification on? 3799 @param self The PHY packet listener object. 3800 @result Returns true if packet notifications for this listener are active 3801 */ 3802 Boolean (*NotificationIsOn)( IOFireWireLibPHYPacketListenerRef self ); 3803 3804 /*! @function TurnOnNotification 3805 @abstract Try to turn on packet notifications for this listener. 3806 @param self The PHY packet listener object. 3807 @result Returns kIOReturnSuccess if successful */ 3808 IOReturn (*TurnOnNotification)( IOFireWireLibPHYPacketListenerRef self ); 3809 3810 /*! @function TurnOffNotification 3811 @abstract Turn packet notification off. 3812 @param self The PHY packet listener object. */ 3813 void (*TurnOffNotification)( IOFireWireLibPHYPacketListenerRef self ); 3814 3815 /*! @function ClientCommandIsComplete 3816 @abstract Notify the PHY packet listener object that a packet notification handler has completed. 3817 @discussion Packet notifications are received one at a time, in order. This function 3818 must be called after a packet handler has completed its work. 3819 @param self The PHY packet listener object. 3820 @param commandID The ID of the packet notification being completed. This is the same 3821 ID that was passed when a packet notification handler is called. 3822 */ 3823 void (*ClientCommandIsComplete)(IOFireWireLibPHYPacketListenerRef self, FWClientCommandID commandID ); 3824 3825 // --- accessors ---------- 3826 3827 /*! @function SetRefCon 3828 @abstract Sets the user refCon value for this interface. 3829 @param self The PHY packet listener object. 3830 @param refcon the refcon */ 3831 void (*SetRefCon)( IOFireWireLibPHYPacketListenerRef self, void * refcon ); 3832 3833 /*! @function GetRefCon 3834 @abstract Returns the user refCon value for thisinterface. 3835 @param self The PHY packet listener object. 3836 @result returns the refcon */ 3837 void* (*GetRefCon)( IOFireWireLibPHYPacketListenerRef self ); 3838 3839 /*! @function SetFlags 3840 @abstract set flags for the listener. 3841 @param self The PHY packet listener object. 3842 @param flags No current flags are defined. 3843 */ 3844 void (*SetFlags)( IOFireWireLibPHYPacketListenerRef self, UInt32 flags ); 3845 3846 /*! @function GetFlags 3847 @abstract get the flags of listener. 3848 @param self The PHY packet listener object. 3849 @result flags No current flags are defined. */ 3850 UInt32 (*GetFlags)( IOFireWireLibPHYPacketListenerRef self ); 3851 3852} IOFireWireLibPHYPacketListenerInterface; 3853 3854#endif // ifndef KERNEL 3855 3856#endif //__IOFireWireLib_H__ 3857