1/* 2 * Copyright (c) 1998-2001 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * The contents of this file constitute Original Code as defined in and 7 * are subject to the Apple Public Source License Version 1.1 (the 8 * "License"). You may not use this file except in compliance with the 9 * License. Please obtain a copy of the License at 10 * http://www.apple.com/publicsource and read it before using this file. 11 * 12 * This Original Code and all software distributed under the License are 13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 17 * License for the specific language governing rights and limitations 18 * under the License. 19 * 20 * @APPLE_LICENSE_HEADER_END@ 21 */ 22 23#ifndef _IOKIT_IOFIREWIREAVCLIB_H_ 24#define _IOKIT_IOFIREWIREAVCLIB_H_ 25 26#include <IOKit/IOCFPlugIn.h> 27#include <IOKit/firewire/IOFireWireFamilyCommon.h> 28#include <IOKit/avc/IOFireWireAVCConsts.h> 29 30// Unit type UUID 31/* 6AAF2EF7-D476-11D5-B57C-0003934B81A0 */ 32#define kIOFireWireAVCLibUnitTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 330x6A, 0xAF, 0x2E, 0xF7, 0xD4, 0x76, 0x11, 0xD5, 0xB5, 0x7C, 0x00, 0x03, 0x93, 0x4B, 0x81, 0xA0) 34 35// Unit Factory UUID 36/* 3F4057BC-D479-11D5-9F05-0003934B81A0 */ 37#define kIOFireWireAVCLibUnitFactoryID CFUUIDGetConstantUUIDWithBytes(NULL, \ 380x3F, 0x40, 0x57, 0xBC, 0xD4, 0x79, 0x11, 0xD5, 0x9F, 0x05, 0x00, 0x03, 0x93, 0x4B, 0x81, 0xA0) 39 40// IOFireWireAVCUnitInterface UUID 41/* FC65C030-D498-11D5-878D-0003934B81A0 */ 42#define kIOFireWireAVCLibUnitInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 430xFC, 0x65, 0xC0, 0x30, 0xD4, 0x98, 0x11, 0xD5, 0x87, 0x8D, 0x00, 0x03, 0x93, 0x4B, 0x81, 0xA0) 44 45// kIOFireWireAVCLibUnitInterfaceID_v2 UUID - No Throttling of AVC Commands 46/* 85B5E954-0AEF-11D8-8D19-000393914ABA */ 47#define kIOFireWireAVCLibUnitInterfaceID_v2 CFUUIDGetConstantUUIDWithBytes(NULL, \ 480x85, 0xB5, 0xE9, 0x54, 0x0A, 0xEF, 0x11, 0xD8, 0x8D, 0x19, 0x00, 0x03, 0x93, 0x91, 0x4A, 0xBA) 49 50// Protocol type UUID 51/* B54BC8F8-D53B-11D5-A1A1-0003934B81A0 */ 52#define kIOFireWireAVCLibProtocolTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 530xB5, 0x4B, 0xC8, 0xF8, 0xD5, 0x3B, 0x11, 0xD5, 0xA1, 0xA1, 0x00, 0x03, 0x93, 0x4B, 0x81, 0xA0) 54 55// Protocol Factory UUID 56/* 8E9AD5AC-D55E-11D5-B7D2-0003934B81A0 */ 57#define kIOFireWireAVCLibProtocolFactoryID CFUUIDGetConstantUUIDWithBytes(NULL, \ 580x8E, 0x9A, 0xD5, 0xAC, 0xD5, 0x5E, 0x11, 0xD5, 0xB7, 0xD2, 0x00, 0x03, 0x93, 0x4B, 0x81, 0xA0) 59 60// IOFireWireAVCProtocolInterface UUID 61/* CC85D421-D55E-11D5-8A10-0003934B81A0 */ 62#define kIOFireWireAVCLibProtocolInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 630xCC, 0x85, 0xD4, 0x21, 0xD5, 0x5E, 0x11, 0xD5, 0x8A, 0x10, 0x00, 0x03, 0x93, 0x4B, 0x81, 0xA0) 64 65// IOFireWireAVCLibConsumerInterfaceID 66/* 7FB7A454-226F-11D6-B889-000A277E7234 */ 67#define kIOFireWireAVCLibConsumerInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 680x7F, 0xB7, 0xA4, 0x54, 0x22, 0x6F, 0x11, 0xD6, 0xB8, 0x89, 0x00, 0x0A, 0x27, 0x7E, 0x72, 0x34) 69 70typedef void (*IOFWAVCMessageCallback)( void * refCon, UInt32 type, void * arg ); 71 72/*! @typedef IOFWAVCRequestCallback 73 @abstract This Callback has been deprecated. Use installAVCCommandHandler instead. 74*/ 75typedef IOReturn (*IOFWAVCRequestCallback)( void *refCon, UInt32 generation, UInt16 srcNodeID, 76 const UInt8 * command, UInt32 cmdLen, UInt8 * response, UInt32 *responseLen); 77 78/*! 79 @typedef IOFWAVCPCRCallback 80 @abstract Callback called after a successful lock transaction to a CMP plug. 81 @param refcon refcon supplied when a client is registered 82 @param generation Bus generation command was received in 83 @param nodeID is the node originating the request 84 @param plug is the plug number 85 @param oldVal is the value the plug used to contain 86 @param newVal is the quad written into the plug 87 */ 88typedef void (*IOFWAVCPCRCallback)(void *refcon, UInt32 generation, UInt16 nodeID, UInt32 plug, 89 UInt32 oldVal, UInt32 newVal); 90 91/*! 92 @typedef IOFWAVCCommandHandlerCallback 93 @abstract Callback called when a incoming AVC command matching a registered command handler is received. 94 @param refCon The refcon supplied when a client is registered 95 @param generation The FireWire bus generation value at the time the command was received 96 @param srcNodeID The node ID of the device who sent us this command 97 @param speed The speed the AVC command packet 98 @param command A pointer to the command bytes 99 @param cmdLen The length of the AVC command bytes buffer in bytes 100 @result The callback handler should return success if it will send the AVC response, or an error if it doesn't want to handle the command 101 */ 102typedef IOReturn (*IOFWAVCCommandHandlerCallback)( void *refCon, UInt32 generation, UInt16 srcNodeID, IOFWSpeed speed, const UInt8 * command, UInt32 cmdLen); 103 104/*! 105 @typedef IOFWAVCSubunitPlugHandlerCallback 106 @abstract Callback called when a incoming AVC command matching a registered command handler is received. 107 @param refCon The refcon supplied when a client is registered 108 @param subunitTypeAndID The subunit type and id of this plug 109 @param plugType The type of plug receiving the message 110 @param plugNum The number of the plug receiving the message 111 @param plugMessage The plug message 112 @param messageParams The parameters associated with the plug message 113 @result The return value is only pertinent for the kIOFWAVCSubunitPlugMsgSignalFormatModified message. Return an error if not accepting the sig format change. 114 */ 115typedef IOReturn (*IOFWAVCSubunitPlugHandlerCallback)(void *refCon, 116 UInt32 subunitTypeAndID, 117 IOFWAVCPlugTypes plugType, 118 UInt32 plugNum, 119 IOFWAVCSubunitPlugMessages plugMessage, 120 UInt32 messageParams); 121 122typedef struct _IOFireWireAVCLibProtocolInterface IOFireWireAVCLibProtocolInterface; 123 124typedef struct _IOFireWireAVCLibAsynchronousCommand 125{ 126 IOFWAVCAsyncCommandState cmdState; 127 void *pRefCon; 128 UInt8 *pCommandBuf; 129 UInt32 cmdLen; 130 UInt8 *pInterimResponseBuf; 131 UInt32 interimResponseLen; 132 UInt8 *pFinalResponseBuf; 133 UInt32 finalResponseLen; 134}IOFireWireAVCLibAsynchronousCommand; 135 136typedef void (*IOFireWireAVCLibAsynchronousCommandCallback)(void *pRefCon, IOFireWireAVCLibAsynchronousCommand *pCommandObject); 137 138/*! 139 @class IOFireWireAVCLibUnitInterface 140 @abstract Initial interface discovered for all AVC Unit drivers. 141 @discussion The IOFireWireAVCLibUnitInterface is the initial interface discovered by most drivers. It supplies the methods that control the operation of the AVC unit as a whole. 142 Finally, the Unit can supply a reference to the IOFireWireUnit. This can be useful if a driver wishes to access the standard FireWire APIs. 143*/ 144 145typedef struct 146 { 147 148 IUNKNOWN_C_GUTS; 149 150 UInt16 version; 151 UInt16 revision; 152 153 /*! 154 @function open 155 @abstract Exclusively opens a connection to the in-kernel device. 156 @discussion Exclusively opens a connection to the in-kernel device. As long as the in-kernel 157 device object is open, no other drivers will be able to open a connection to the device. When 158 open, the device on the bus may disappear, but the in-kernel object representing it will stay 159 instantiated and can begin communicating with the device again if it ever reappears. 160 @param self Pointer to IOFireWireAVCLibUnitInterface. 161 @result Returns kIOReturnSuccess on success. 162 */ 163 164 IOReturn (*open)( void * self ); 165 166 /*! 167 @function openWithSessionRef 168 @abstract Opens a connection to a device that is not already open. 169 @discussion Sometimes it is desirable to open multiple user clients on a device. In the case 170 of FireWire sometimes we wish to have both the FireWire User Client and the AVC User Client 171 open at the same time. The technique to arbitrate this is as follows:<br>First open normally 172 the device furthest from the root in the I/O Registry.<br>Second, get its sessionRef with the 173 getSessionRef call.<br>Third, open the device further up the chain by calling this method and 174 passing the sessionRef returned from the call in step 2. 175 @param sessionRef SessionRef returned from getSessionRef call. 176 @param self Pointer to IOFireWireAVCLibUnitInterface. 177 @result Returns kIOReturnSuccess on success. 178 */ 179 180 IOReturn (*openWithSessionRef)( void * self, IOFireWireSessionRef sessionRef ); 181 182 /*! 183 @function getSessionRef 184 @abstract Get the session reference. 185 @discussion Gets the sessionRef to be used with openWithSessionRef. 186 @param self Pointer to IOFireWireAVCLibUnitInterface. 187 @result Returns a sessionRef on success. 188 */ 189 190 IOFireWireSessionRef (*getSessionRef)(void * self); 191 192 /*! 193 @function close 194 @abstract Closes an exclusive access to the device. 195 @discussion Closes an exclusive access to the device. When a device is closed it may be 196 unloaded by the kernel. If it is unloaded and then later reappears it will be represented 197 by a different object. You won't be able to use this user client on the new object. The 198 new object will have to be looked up in the I/O Registry and a new user client will have to 199 be opened on it. 200 @param self Pointer to IOFireWireAVCLibUnitInterface. 201 */ 202 203 void (*close)( void * self ); 204 205 /*! 206 @function addCallbackDispatcherToRunLoop 207 @abstract Adds a dispatcher for kernel callbacks to the specified runloop. 208 @discussion The user space portions of the AVC API communicate with the in-kernel services by 209 messaging the kernel. Similarly, the kernel messages the user space services in response. 210 These responses need to be picked up by a piece of code. This call adds that code to the specified 211 run loop. Most drivers will call this method on the run loop that was created when your task was 212 created. To avoid deadlock you must avoid sleeping (or spin waiting) the run loop to wait for 213 AVC response. If you do this the dispatcher will never get to run and you will wait forever. 214 @param self Pointer to IOFireWireAVCLibUnitInterface. 215 @param cfRunLoopRef Reference to a run loop. 216 @result Returns kIOReturnSuccess on success. 217 */ 218 219 IOReturn (*addCallbackDispatcherToRunLoop)( void *self, CFRunLoopRef cfRunLoopRef ); 220 221 /*! 222 @function removeCallbackDispatcherFromRunLoop 223 @abstract Removes a dispatcher for kernel callbacks to the specified run loop. 224 @discussion Undoes the work of addCallbackDispatcherToRunLoop. 225 @param self Pointer to IOFireWireAVCLibUnitInterface. 226 */ 227 228 void (*removeCallbackDispatcherFromRunLoop)( void * self ); 229 230 /*! 231 @function setMessageCallback 232 @abstract Sets callback for user space message routine. 233 @discussion In FireWire and AVC, bus status messages are delivered via IOKit's message routine. 234 This routine is emulated in user space for AVC and FireWire messages via this callback. You should 235 register here for bus reset and reconnect messages. 236 @param self Pointer to IOFireWireAVCLibUnitInterface. 237 @param refCon RefCon to be returned as first argument of completion routine. 238 @param callback Address of completion routine. 239 */ 240 241 void (*setMessageCallback)( void *self, void * refCon, IOFWAVCMessageCallback callback); 242 243 /*! 244 @function AVCCommand 245 @abstract Sends an AVC command to the device and returns the response. 246 @discussion This function will block until the device returns a response or the kernel driver times out. 247 @param self Pointer to IOFireWireAVCLibUnitInterface. 248 @param command Pointer to command to send. 249 @param cmdLen Length (in bytes) of command. 250 @param response Pointer to place to store the response sent by the device. 251 @param responseLen Pointer to place to store the length of the response. 252 */ 253 254 IOReturn (*AVCCommand)( void * self, 255 const UInt8 * command, UInt32 cmdLen, UInt8 * response, UInt32 *responseLen); 256 257 /*! 258 @function AVCCommandInGeneration 259 @abstract Sends an AVC command to the device and returns the response. 260 @discussion Sends an AVC command to the device and returns the response. The command must complete in the specified bus generation. This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?). This function will block until the device returns a response or the kernel driver times out. 261 @param self Pointer to IOFireWireAVCLibUnitInterface. 262 @param busGeneration FireWire bus generation that the command is valid in. 263 @param command Pointer to command to send. 264 @param cmdLen Length (in bytes) of command. 265 @param response Pointer to place to store the response sent by the device. 266 @param responseLen Pointer to place to store the length of the response. 267 */ 268 269 IOReturn (*AVCCommandInGeneration)( void * self, UInt32 busGeneration, 270 const UInt8 * command, UInt32 cmdLen, UInt8 * response, UInt32 *responseLen); 271 272 /*! 273 @function getAncestorInterface 274 @abstract Creates a plug-in object for an ancestor (in the I/O Registry) of the AVC unit and returns an interface to it. 275 @discussion This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?). 276 @param self Pointer to IOFireWireAVCLibUnitInterface. 277 @param object_class Class name of ancestor of the device to get an interface for. 278 @param pluginType An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of plug-in service to be returned for the ancestor. 279 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created plug-in object. 280 @result Returns a COM-style interface pointer. Returns 0 upon failure. 281 */ 282 void * (*getAncestorInterface)( void * self, char * object_class, REFIID pluginType, REFIID iid) ; 283 284 /*! 285 @function getProtocolInterface 286 @abstract Creates a plug-in object for a protocol driver for the FireWire bus the AVC unit 287 is connected to and returns an interface to it. 288 @discussion This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?). 289 @param self Pointer to IOFireWireAVCLibUnitInterface. 290 @param pluginType An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of plug-in service to be returned for the created protocol object. 291 @param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created protocol device object. 292 @result Returns a COM-style interface pointer. Returns 0 upon failure. 293 */ 294 void * (*getProtocolInterface)( void * self, REFIID pluginType, REFIID iid) ; 295 296 /* 297 */ 298 IOReturn (*getAsyncConnectionPlugCounts) 299 ( void *self, UInt8 * inputPlugCount, UInt8 * outputPlugCount ); 300 301 /* 302 */ 303 IUnknownVTbl ** (*createConsumerPlug)( void *self, UInt8 plugNumber, REFIID iid ); 304 305 /*! 306 @function updateAVCCommandTimeout 307 @abstract Updates an AVCCommand's timeout back to 10 seconds. 308 @discussion AVCCommands will time out after 10 seconds unless this function is called (from another thread) to update the command's timeout back to 10 seconds. 309 This function is only available if the interface version is > 2. 310 */ 311 IOReturn (*updateAVCCommandTimeout)(void * self); 312 313 /*! 314 @function makeP2PInputConnection 315 @abstract Increments the point-to-point connection count of a unit input plug. 316 @discussion This function is only available if the interface version is > 3. 317 */ 318 IOReturn (*makeP2PInputConnection)(void * self, UInt32 inputPlug, UInt32 chan); 319 320 /*! 321 @function breakP2PInputConnection 322 @abstract Decrements the point-to-point connection count of a unit input plug. 323 @discussion This function is only available if the interface version is > 3. 324 */ 325 IOReturn (*breakP2PInputConnection)(void * self, UInt32 inputPlug); 326 327 /*! 328 @function makeP2POutputConnection 329 @abstract Increments the point-to-point connection count of a unit output plug. 330 @discussion This function is only available if the interface version is > 3. 331 */ 332 IOReturn (*makeP2POutputConnection)(void * self, UInt32 outputPlug, UInt32 chan, IOFWSpeed speed); 333 334 /*! 335 @function breakP2POutputConnection 336 @abstract Decrements the point-to-point connection count of a unit output plug. 337 @discussion This function is only available if the interface version is > 3. 338 */ 339 IOReturn (*breakP2POutputConnection)(void * self, UInt32 outputPlug); 340 341 /*! 342 @function createAVCAsynchronousCommand 343 */ 344 345 IOReturn (*createAVCAsynchronousCommand)(void * self, 346 const UInt8 * command, 347 UInt32 cmdLen, 348 IOFireWireAVCLibAsynchronousCommandCallback completionCallback, 349 void *pRefCon, 350 IOFireWireAVCLibAsynchronousCommand **ppCommandObject); 351 352 /*! 353 @function AVCAsynchronousCommandSubmit 354 */ 355 356 IOReturn (*AVCAsynchronousCommandSubmit)(void * self, IOFireWireAVCLibAsynchronousCommand *pCommandObject); 357 358 /*! 359 @function AVCAsynchronousCommandReinit 360 */ 361 362 IOReturn (*AVCAsynchronousCommandReinit)(void * self, IOFireWireAVCLibAsynchronousCommand *pCommandObject); 363 364 /*! 365 @function AVCAsynchronousCommandCancel 366 */ 367 368 IOReturn (*AVCAsynchronousCommandCancel)(void * self, IOFireWireAVCLibAsynchronousCommand *pCommandObject); 369 370 /*! 371 @function AVCAsynchronousCommandRelease 372 */ 373 374 IOReturn (*AVCAsynchronousCommandRelease)(void * self, IOFireWireAVCLibAsynchronousCommand *pCommandObject); 375 376 /*! 377 @function AVCAsynchronousCommandReinitWithCommandBytes 378 */ 379 380 IOReturn (*AVCAsynchronousCommandReinitWithCommandBytes)(void * self, 381 IOFireWireAVCLibAsynchronousCommand *pCommandObject, 382 const UInt8 * command, 383 UInt32 cmdLen); 384 } IOFireWireAVCLibUnitInterface; 385 386/*! 387 @class IOFireWireAVCLibProtocolInterface 388 @abstract Initial interface discovered for all AVC protocol drivers. 389 @discussion The IOFireWireAVCLibProtocolInterface is used to set up local plug control registers and to receive AVC requests. 390*/ 391 392typedef struct _IOFireWireAVCLibProtocolInterface 393 { 394 IUNKNOWN_C_GUTS; 395 396 UInt16 version; 397 UInt16 revision; 398 /*! 399 @function addCallbackDispatcherToRunLoop 400 @abstract Adds a dispatcher for kernel callbacks to the specified run loop. 401 @discussion The user space portions of the AVC API communicate with the in-kernel services by 402 messaging the kernel. Similarly, the kernel messages the user space services in response. 403 These responses need to be picked up by a piece of code. This call adds that code to the specified 404 run loop. Most drivers will call this method on the run loop that was created when your task was 405 created. To avoid deadlock you must avoid sleeping (or spin waiting) the run loop to wait for 406 AVC response. If you do this the dispatcher will never get to run and you will wait forever. 407 @param self Pointer to IOFireWireAVCLibProtocolInterface. 408 @param cfRunLoopRef Reference to a run loop. 409 @result Returns kIOReturnSuccess on success. 410 */ 411 412 IOReturn (*addCallbackDispatcherToRunLoop)( void *self, CFRunLoopRef cfRunLoopRef ); 413 414 /*! 415 @function removeCallbackDispatcherFromRunLoop 416 @abstract Removes a dispatcher for kernel callbacks to the specified run loop. 417 @discussion Undoes the work of addCallbackDispatcherToRunLoop. 418 @param self Pointer to IOFireWireAVCLibProtocolInterface. 419 */ 420 421 void (*removeCallbackDispatcherFromRunLoop)( void * self ); 422 423 /*! 424 @function setMessageCallback 425 @abstract Sets callback for user space message routine. 426 @discussion In FireWire and AVC, bus status messages are delivered via IOKit's message routine. 427 This routine is emulated in user space for AVC and FireWire messages via this callback. You should 428 register here for bus reset and reconnect messages. 429 @param self Pointer to IOFireWireAVCLibProtocolInterface. 430 @param refCon RefCon to be returned as first argument of completion routine. 431 @param callback Address of completion routine. 432 */ 433 434 void (*setMessageCallback)( void *self, void * refCon, IOFWAVCMessageCallback callback); 435 436 /*! 437 @function setAVCRequestCallback 438 @abstract This function has been deprecated. Use installAVCCommandHandler instead. 439 */ 440 441 IOReturn (*setAVCRequestCallback)( void *self, UInt32 subUnitType, UInt32 subUnitID, 442 void *refCon, IOFWAVCRequestCallback callback); 443 444/*! 445 @function allocateInputPlug 446 @abstract Allocates an input plug. 447 @param self Pointer to IOFireWireAVCLibProtocolInterface. 448 @param refcon Arbitrary value passed back as first argument of callback. 449 @param func Callback function when a successful lock transaction to the plug has been performed. 450 @param plug Set to the plug number if a plug is successfully allocated. 451*/ 452 IOReturn (*allocateInputPlug)( void *self, void *refcon, IOFWAVCPCRCallback func, UInt32 *plug); 453/*! 454 @function freeInputPlug 455 @abstract Deallocates an input plug. 456 @param self Pointer to IOFireWireAVCLibProtocolInterface. 457 @param plug Value returned by allocateInputPlug. 458*/ 459 void (*freeInputPlug)( void *self, UInt32 plug); 460/*! 461 @function readInputPlug 462 @abstract Returns the current value of an input plug. 463 @param self Pointer to IOFireWireAVCLibProtocolInterface. 464 @param plug Value returned by allocateInputPlug. 465*/ 466 UInt32 (*readInputPlug)( void *self, UInt32 plug); 467/*! 468 @function updateInputPlug 469 @abstract Updates the value of an input plug (simulating a lock transaction). 470 @param self Pointer to IOFireWireAVCLibProtocolInterface. 471 @param plug Value returned by allocateInputPlug. 472 @param oldVal Value returned by readInputPlug. 473 @param newVal New value to store in plug if its current value is oldVal. 474*/ 475 IOReturn (*updateInputPlug)( void *self, UInt32 plug, UInt32 oldVal, UInt32 newVal); 476/*! 477 @function allocateOutputPlug 478 @abstract Allocates an output plug. 479 @param self Pointer to IOFireWireAVCLibProtocolInterface. 480 @param refcon Arbitrary value passed back as first argument of callback. 481 @param func Callback function when a successful lock transaction to the plug has been performed. 482 @param plug Set to the plug number if a plug is successfully allocated. 483*/ 484 IOReturn (*allocateOutputPlug)( void *self, void *refcon, IOFWAVCPCRCallback func, UInt32 *plug); 485/*! 486 @function freeOutputPlug 487 @abstract Deallocates an output plug. 488 @param self Pointer to IOFireWireAVCLibProtocolInterface. 489 @param plug Value returned by allocateOutputPlug. 490*/ 491 void (*freeOutputPlug)( void *self, UInt32 plug); 492/*! 493 @function readOutputPlug 494 @abstract Returns the current value of an output plug. 495 @param self Pointer to IOFireWireAVCLibProtocolInterface. 496 @param plug Value returned by allocateOutputPlug. 497*/ 498 UInt32 (*readOutputPlug)( void *self, UInt32 plug); 499/*! 500 @function updateOutputPlug 501 @abstract Updates the value of an output plug (simulating a lock transaction). 502 @param self Pointer to IOFireWireAVCLibProtocolInterface. 503 @param plug Value returned by allocateOutputPlug. 504 @param oldVal Value returned by readOutputPlug. 505 @param newVal New value to store in plug if its current value is oldVal. 506*/ 507 IOReturn (*updateOutputPlug)( void *self, UInt32 plug, UInt32 oldVal, UInt32 newVal); 508/*! 509 @function readOutputMasterPlug 510 @abstract Returns the current value of the output master plug. 511 @param self Pointer to IOFireWireAVCLibProtocolInterface. 512*/ 513 UInt32 (*readOutputMasterPlug)( void *self); 514/*! 515 @function updateOutputMasterPlug 516 @abstract Updates the value of the master output plug (simulating a lock transaction). 517 @param self Pointer to IOFireWireAVCLibProtocolInterface. 518 @param oldVal Value returned by readOutputMasterPlug. 519 @param newVal New value to store in plug if its current value is oldVal. 520*/ 521 IOReturn (*updateOutputMasterPlug)( void *self, UInt32 oldVal, UInt32 newVal); 522/*! 523 @function readInputMasterPlug 524 @abstract Returns the current value of the input master plug. 525 @param self Pointer to IOFireWireAVCLibProtocolInterface. 526 527*/ 528 UInt32 (*readInputMasterPlug)( void *self); 529/*! 530 @function updateInputMasterPlug 531 @abstract Updates the value of the master input plug (simulating a lock transaction). 532 @param self Pointer to IOFireWireAVCLibProtocolInterface. 533 @param oldVal Value returned by readInputMasterPlug. 534 @param newVal New value to store in plug if its current value is oldVal. 535*/ 536 IOReturn (*updateInputMasterPlug)( void *self, UInt32 oldVal, UInt32 newVal); 537 538/*! 539 @function publishAVCUnitDirectory 540 @abstract Publishes an AVC unit directory in the config ROM. 541 @param self Pointer to IOFireWireAVCLibProtocolInterface. 542*/ 543 IOReturn (*publishAVCUnitDirectory)(void *self); 544 545/*! 546 @function installAVCCommandHandler 547 @abstract Installs a command handler for handling specific incoming AVC commands. 548 @param self Pointer to IOFireWireAVCLibProtocolInterface. 549 @param subUnitTypeAndID The subunit type and ID for this command handler. 550 @param opCode The opcode for this command handler. 551 @param refCon Arbitrary value passed back as first argument of callback. 552 @param callback A pointer to the callback function 553*/ 554 IOReturn (*installAVCCommandHandler)(void *self, 555 UInt32 subUnitTypeAndID, 556 UInt32 opCode, 557 void *refCon, 558 IOFWAVCCommandHandlerCallback callback); 559 560/*! 561 @function sendAVCResponse 562 @abstract Sends an AVC response packet. 563 @param self Pointer to IOFireWireAVCLibProtocolInterface. 564 @param generation The Firewire bus generation that this response should be sent in. 565 @param nodeID The node ID of the device we are sending this response to. 566 @param response A pointer to the response bytes. 567 @param responseLen The number of response bytes. 568*/ 569 IOReturn (*sendAVCResponse)(void *self, 570 UInt32 generation, 571 UInt16 nodeID, 572 const char *response, 573 UInt32 responseLen); 574 575/*! 576 @function addSubunit 577 @abstract Installs a virtual AVC subunit. 578 @param self Pointer to IOFireWireAVCLibProtocolInterface. 579 @param subunitType The type of subunit to create. 580 @param numSourcePlugs The number of source plugs for this subunit. 581 @param numDestPlugs The number of destination plugs for this subunit. 582 @param refCon Arbitrary value passed back as first argument of callback. 583 @param callback A pointer to the callback to receive plug management messages. 584 @param pSubunitTypeAndID A pointer to a byte to hold the returned subunit address for the new subunit. 585 */ 586 IOReturn (*addSubunit)(void *self, 587 UInt32 subunitType, 588 UInt32 numSourcePlugs, 589 UInt32 numDestPlugs, 590 void *refCon, 591 IOFWAVCSubunitPlugHandlerCallback callback, 592 UInt32 *pSubunitTypeAndID); 593 594/*! 595 @function setSubunitPlugSignalFormat 596 @abstract Sets the signal format of the specifed plug. 597 @param self Pointer to IOFireWireAVCLibProtocolInterface. 598 @param subunitTypeAndID The subunit type and ID of the plug. 599 @param plugType The plug type. 600 @param plugNum The plug number. 601 @param signalFormat The 32-bit signal format value. 602*/ 603 IOReturn (*setSubunitPlugSignalFormat)(void *self, 604 UInt32 subunitTypeAndID, 605 IOFWAVCPlugTypes plugType, 606 UInt32 plugNum, 607 UInt32 signalFormat); 608 609/*! 610 @function getSubunitPlugSignalFormat 611 @abstract Gets the signal format of the specifed plug. 612 @param self Pointer to IOFireWireAVCLibProtocolInterface. 613 @param subunitTypeAndID The subunit type and ID of the plug. 614 @param plugType The plug type. 615 @param plugNum The plug number. 616 @param pSignalFormat A pointer to the location to return the signal format value. 617*/ 618 IOReturn (*getSubunitPlugSignalFormat)(void *self, 619 UInt32 subunitTypeAndID, 620 IOFWAVCPlugTypes plugType, 621 UInt32 plugNum, 622 UInt32 *pSignalFormat); 623 624/*! 625 @function connectTargetPlugs 626 @abstract Establishes an internal AVC plug connection between subunit/unit plugs. 627 @param self Pointer to IOFireWireAVCLibProtocolInterface. 628 @param sourceSubunitTypeAndID The subunit type and ID for the source plug 629 @param sourcePlugType The source plug type. 630 @param pSourcePlugNum A pointer to the source plug num. Will return the actual source plug num here. 631 @param destSubunitTypeAndID The subunit type and ID for the destination plug. 632 @param destPlugType The dest plug type. 633 @param pDestPlugNum A pointer to the dest plug num. Will return the actual dest plug num here. 634 @param lockConnection A flag to specify if this connection should be locked. 635 @param permConnection A flag to specify if this connection is permanent. 636*/ 637 IOReturn (*connectTargetPlugs)(void *self, 638 UInt32 sourceSubunitTypeAndID, 639 IOFWAVCPlugTypes sourcePlugType, 640 UInt32 *pSourcePlugNum, 641 UInt32 destSubunitTypeAndID, 642 IOFWAVCPlugTypes destPlugType, 643 UInt32 *pDestPlugNum, 644 bool lockConnection, 645 bool permConnection); 646 647/*! 648 @function disconnectTargetPlugs 649 @abstract Breaks an internal AVC plug connection between subunit/unit plugs. 650 @param self Pointer to IOFireWireAVCLibProtocolInterface. 651 @param sourceSubunitTypeAndID The subunit type and ID for the source plug. 652 @param sourcePlugType The source plug type. 653 @param sourcePlugNum The source plug num. 654 @param destSubunitTypeAndID The subunit type and ID for the destination plug. 655 @param destPlugType The dest plug type. 656 @param destPlugNum The dest plug num. 657*/ 658 IOReturn (*disconnectTargetPlugs)(void *self, 659 UInt32 sourceSubunitTypeAndID, 660 IOFWAVCPlugTypes sourcePlugType, 661 UInt32 sourcePlugNum, 662 UInt32 destSubunitTypeAndID, 663 IOFWAVCPlugTypes destPlugType, 664 UInt32 destPlugNum); 665 666/*! 667 @function getTargetPlugConnection 668 @abstract Gets the connection details for a specific plug. 669 @param self Pointer to IOFireWireAVCLibProtocolInterface. 670 @param subunitTypeAndID The subunit type and ID of the plug. 671 @param plugType The plug type. 672 @param plugNum The plug number. 673 @param pConnectedSubunitTypeAndID The subunit type and ID of the connected plug. 674 @param pConnectedPlugType The type of the connected plug. 675 @param pConnectedPlugNum The number of the connected plug. 676 @param pLockConnection A pointer for returning the lock status of the connection. 677 @param pPermConnection A pointer for returning the perm status of the connection. 678*/ 679 IOReturn (*getTargetPlugConnection)(void *self, 680 UInt32 subunitTypeAndID, 681 IOFWAVCPlugTypes plugType, 682 UInt32 plugNum, 683 UInt32 *pConnectedSubunitTypeAndID, 684 IOFWAVCPlugTypes *pConnectedPlugType, 685 UInt32 *pConnectedPlugNum, 686 bool *pLockConnection, 687 bool *pPermConnection); 688} IOFireWireAVCLibProtocolInterface; 689 690 691typedef void (*IOFireWireAVCPortStateHandler)( void * refcon, UInt32 state ); 692typedef void (*IOFireWireAVCFrameStatusHandler)( void * refcon, UInt32 mode, UInt32 count ); 693 694 695 696/*! 697 @class IOFireWireAVCLibConsumerInterface 698 @abstract Interface for an asynchronous connection consumer. 699 @discussion Used to receive data from an asynchronous connection producer. 700*/ 701 702typedef struct 703{ 704 705 IUNKNOWN_C_GUTS; 706 707 UInt16 version; 708 UInt16 revision; 709 710 void (*setSubunit)( void * self, UInt8 subunit ); 711 void (*setRemotePlug)( void * self, UInt8 plugNumber ); 712 713 IOReturn (*connectToRemotePlug)( void * self ); 714 IOReturn (*disconnectFromRemotePlug)( void * self ); 715 716 void (*setFrameStatusHandler)( void * self, void * refcon, IOFireWireAVCFrameStatusHandler handler ); 717 void (*frameProcessed)( void * self, UInt32 mode ); 718 719 void (*setMaxPayloadSize)( void * self, UInt32 size ); 720 721 IOReturn (*setSegmentSize)( void * self, UInt32 size ); 722 UInt32 (*getSegmentSize)( void * self ); 723 char * (*getSegmentBuffer)( void * self ); 724 725 void (*setPortStateHandler)( void * self, void * refcon, IOFireWireAVCPortStateHandler handler ); 726 727 728 void (*setPortFlags)( void * self, UInt32 flags ); 729 void (*clearPortFlags)( void * self, UInt32 flags ); 730 UInt32 (*getPortFlags)( void * self ); 731 732} IOFireWireAVCLibConsumerInterface; 733 734#endif 735