1/* 2 * Copyright (c) 1998-2002 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * The contents of this file constitute Original Code as defined in and 7 * are subject to the Apple Public Source License Version 1.1 (the 8 * "License"). You may not use this file except in compliance with the 9 * License. Please obtain a copy of the License at 10 * http://www.apple.com/publicsource and read it before using this file. 11 * 12 * This Original Code and all software distributed under the License are 13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 17 * License for the specific language governing rights and limitations 18 * under the License. 19 * 20 * @APPLE_LICENSE_HEADER_END@ 21 */ 22/* 23 * IOFireWireLibIsoch.h 24 * IOFireWireFamily 25 * 26 * Created on Mon Mar 19 2001. 27 * Copyright (c) 2001-2002 Apple Computer, Inc. All rights reserved. 28 * 29 */ 30 31#ifndef __IOFireWireLibIsoch_H__ 32#define __IOFireWireLibIsoch_H__ 33 34#include <CoreFoundation/CoreFoundation.h> 35#include <IOKit/IOCFPlugIn.h> 36 37#include <IOKit/firewire/IOFireWireFamilyCommon.h> 38#include <IOKit/firewire/IOFireWireLib.h> 39 40// 41// local isoch port 42// 43 44// uuid string: 541971C6-CE72-11D7-809D-000393C0B9D8 45#define kIOFireWireLocalIsochPortInterfaceID_v5 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault \ 46 , 0x54, 0x19, 0x71, 0xC6, 0xCE, 0x72, 0x11, 0xD7\ 47 , 0x80, 0x9D, 0x00, 0x03, 0x93, 0xC0, 0xB9, 0xD8 ) 48 49// uuid string: FECAA2F6-4E84-11D7-B6FD-0003938BEB0A 50#define kIOFireWireLocalIsochPortInterfaceID_v4 CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault \ 51 ,0xFE, 0xCA, 0xA2, 0xF6, 0x4E, 0x84, 0x11, 0xD7\ 52 ,0xB6, 0xFD, 0x00, 0x03, 0x93, 0x8B, 0xEB, 0x0A ) 53 54// uuid string: A0AD095E-6D2F-11D6-AC82-0003933F84F0 55#define kIOFireWireLocalIsochPortInterfaceID_v3 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 56 0xA0, 0xAD, 0x09, 0x5E, 0x6D, 0x2F, 0x11, 0xD6,\ 57 0xAC, 0x82, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 58 59// Availability: Mac OS X "Jaguar" and later 60// uuid string: 73C76D09-6D2F-11D6-AF7F-0003933F84F0 61#define kIOFireWireLocalIsochPortInterfaceID_v2 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 62 0x73, 0xC7, 0x6D, 0x09, 0x6D, 0x2F, 0x11, 0xD6,\ 63 0xAF, 0x7F, 0x00, 0x03, 0x93, 0x3F, 0x84, 0xF0 ) 64 65// uuid string: 0F5E33C8-1350-11D5-9BE7-003065AF75CC 66#define kIOFireWireLocalIsochPortInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 67 0x0F, 0x5E, 0x33, 0xC8, 0x13, 0x50, 0x11, 0xD5,\ 68 0x9B, 0xE7, 0x00, 0x30, 0x65, 0xAF, 0x75, 0xCC) 69 70// 71// remote isoch port 72// 73 74// uuid string: AAFDBDB0-489F-11D5-BC9B-003065423456 75#define kIOFireWireRemoteIsochPortInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 76 0xAA, 0xFD, 0xBD, 0xB0, 0x48, 0x9F, 0x11, 0xD5,\ 77 0xBC, 0x9B, 0x00, 0x30, 0x65, 0x42, 0x34, 0x56) 78 79 80// 81// isoch channel 82// 83 84// uuid string: 2EC1E404-1350-11D5-89B5-003065AF75CC 85#define kIOFireWireIsochChannelInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 86 0x2E, 0xC1, 0xE4, 0x04, 0x13, 0x50, 0x11, 0xD5,\ 87 0x89, 0xB5, 0x00, 0x30, 0x65, 0xAF, 0x75, 0xCC) 88 89// 90// DCL command pool 91// 92 93// uuid string: 4A4B1710-1350-11D5-9B12-003065AF75CC 94#define kIOFireWireDCLCommandPoolInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 95 0x4A, 0x4B, 0x17, 0x10, 0x13, 0x50, 0x11, 0xD5,\ 96 0x9B, 0x12, 0x00, 0x30, 0x65, 0xAF, 0x75, 0xCC) 97 98// 99// NuDCL pool 100// 101 102// uuid string: D3837670-4463-11D7-B79A-0003938BEB0A 103#define kIOFireWireNuDCLPoolInterfaceID CFUUIDGetConstantUUIDWithBytes( kCFAllocatorDefault,\ 104 0xD3, 0x83, 0x76, 0x70, 0x44, 0x63, 0x11, 0xD7,\ 105 0xB7, 0x9A, 0x00, 0x03, 0x93, 0x8B, 0xEB, 0x0A) 106 107// uuid string: 6D1FDE59-50CE-4ED4-880A-9D13A4624038 108#define kIOFireWireAsyncStreamListenerInterfaceID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault,\ 109 0x6D, 0x1F, 0xDE, 0x59, 0x50, 0xCE, 0x4E, 0xD4,\ 110 0x88, 0x0A, 0x90, 0x13, 0xA4, 0x62, 0x40, 0x38) 111 112 113typedef void (*IOFireWireIsochChannelForceStopHandler)( 114 IOFireWireLibIsochChannelRef interface, 115 UInt32 stopCondition); 116 117typedef IOReturn (*IOFireWireLibIsochPortCallback)( 118 IOFireWireLibIsochPortRef interface) ; 119 120typedef IOReturn (*IOFireWireLibIsochPortAllocateCallback)( 121 IOFireWireLibIsochPortRef interface, 122 IOFWSpeed maxSpeed, 123 UInt32 channel) ; 124 125typedef IOReturn (*IOFireWireLibIsochPortGetSupportedCallback)( 126 IOFireWireLibIsochPortRef interface, 127 IOFWSpeed* outMaxSpeed, 128 UInt64* outChanSupported) ; 129 130typedef IOReturn (*IOFireWireLibIsochPortFinalizeCallback)( void* refcon ) ; 131 132// ============================================================ 133// 134// IOFireWireIsochPort 135// 136// ============================================================ 137 138/*! @parseOnly */ 139#define IOFIREWIRELIBISOCHPORT_C_GUTS \ 140 /*! @function GetSupported \ 141 @abstract The method is called to determine which FireWire isochronous \ 142 channels and speed this port supports. \ 143 @discussion This method is called by the channel object to which a port \ 144 has been added. Subclasses of IOFireWireIsochPortInterface override \ 145 this method to support specific hardware. Do not call this method \ 146 directly. \ 147 @param self The isoch port interface to use. \ 148 @param maxSpeed A pointer to an IOFWSpeed which should be filled with \ 149 the maximum speed this port can talk or listen. \ 150 @param chanSupported A pointer to a UInt64 which should be filled with \ 151 a bitmask representing the FireWire bus isochonous channels on \ 152 which the port can talk or listen. Set '1' for supported, '0' for \ 153 unsupported. \ 154 @result Return kIOReturnSuccess on success, other return any other \ 155 IOReturn error code.*/ \ 156 IOReturn (*GetSupported) ( IOFireWireLibIsochPortRef self, IOFWSpeed* maxSpeed, UInt64* chanSupported ) ; \ 157 /*! @function AllocatePort \ 158 @abstract The method is called when the port should configure its \ 159 associated hardware to prepare to send or receive isochronous data \ 160 on the channel number and at the speed specified. \ 161 @discussion This method is called by the channel object to which a port \ 162 has been added. Subclasses of IOFireWireIsochPortInterface override \ 163 this method to support specific hardware. Do not call this method \ 164 directly. \ 165 @param self The isoch port interface to use. \ 166 @param speed Channel speed \ 167 @param chan Channel number (0-63) \ 168 @result Return kIOReturnSuccess on success, other return any other \ 169 IOReturn error code.*/ \ 170 IOReturn (*AllocatePort) ( IOFireWireLibIsochPortRef self, IOFWSpeed speed, UInt32 chan ) ; \ 171 /*! @function ReleasePort \ 172 @abstract The method is called to release the hardware after the \ 173 channel has been stopped. \ 174 @discussion This method is called by the channel object to which a port \ 175 has been added. Subclasses of IOFireWireIsochPortInterface override \ 176 this method to support specific hardware. Do not call this method \ 177 directly. \ 178 @param self The isoch port interface to use. \ 179 @result Return kIOReturnSuccess on success, other return any other IOReturn error code.*/ \ 180 IOReturn (*ReleasePort) ( IOFireWireLibIsochPortRef self ) ; \ 181 /*! @function Start \ 182 @abstract The method is called when the port is to begin talking or listening. \ 183 @discussion This method is called by the channel object to which a port \ 184 has been added. Subclasses of IOFireWireIsochPortInterface override \ 185 this method to support specific hardware. Do not call this method \ 186 directly. \ 187 @param self The isoch port interface to use. \ 188 @result Return kIOReturnSuccess on success, other return any other IOReturn error code.*/ \ 189 IOReturn (*Start) ( IOFireWireLibIsochPortRef self ) ; \ 190 /*! @function Stop \ 191 @abstract The method is called when the port is to stop talking or listening. \ 192 @discussion This method is called by the channel object to which a port \ 193 has been added. Subclasses of IOFireWireIsochPortInterface override \ 194 this method to support specific hardware. Do not call this method \ 195 directly. \ 196 @param self The isoch port interface to use. \ 197 @result Return kIOReturnSuccess on success, other return any \ 198 other IOReturn error code.*/ \ 199 IOReturn (*Stop) ( IOFireWireLibIsochPortRef self ) ; \ 200 /*! @function SetRefCon \ 201 @abstract Set reference value associated with this port. \ 202 @discussion Retrieve the reference value with GetRefCon() \ 203 @param self The isoch port interface to use. \ 204 @param inRefCon The new reference value.*/ \ 205 void (*SetRefCon) ( IOFireWireLibIsochPortRef self, void* inRefCon) ; \ 206 /*! @function GetRefCon \ 207 @abstract Get reference value associated with this port. \ 208 @discussion Set the reference value with SetRefCon() \ 209 @param self The isoch port interface to use. \ 210 @result The port refcon value.*/ \ 211 void* (*GetRefCon) ( IOFireWireLibIsochPortRef self) 212 213/*! @class 214 @abstract FireWire user client isochronous port interface 215 @discussion Isochronous ports represent talkers or listeners on a 216 FireWire isochronous channel. This is a base class containing all 217 isochronous port functionality not specific to any type of port. 218 Ports are added to channel interfaces 219 (IOFireWireIsochChannelInterface) which coordinate the start and 220 stop of isochronous traffic on a FireWire bus isochronous channel. 221 */ 222typedef struct IOFireWireIsochPortInterface_t 223{ 224 IUNKNOWN_C_GUTS ; 225 /*! Interface revision. */ 226 UInt32 revision; 227 /*! Interface version. */ 228 UInt32 version; 229 230 IOFIREWIRELIBISOCHPORT_C_GUTS ; 231 232} IOFireWireIsochPortInterface ; 233 234/*! @class 235 Description forthcoming 236 */ 237typedef struct IOFireWireRemoteIsochPortInterface_t 238{ 239 IUNKNOWN_C_GUTS ; 240 /*! Interface revision. */ 241 UInt32 revision; 242 /*! Interface version. */ 243 UInt32 version; 244 245 IOFIREWIRELIBISOCHPORT_C_GUTS ; 246 247 /*! Description forthcoming */ 248 IOFireWireLibIsochPortGetSupportedCallback (*SetGetSupportedHandler) ( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortGetSupportedCallback inHandler) ; 249 /*! Description forthcoming */ 250 IOFireWireLibIsochPortAllocateCallback (*SetAllocatePortHandler) ( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortAllocateCallback inHandler) ; 251 /*! Description forthcoming */ 252 IOFireWireLibIsochPortCallback (*SetReleasePortHandler)( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortCallback inHandler) ; 253 /*! Description forthcoming */ 254 IOFireWireLibIsochPortCallback (*SetStartHandler)( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortCallback inHandler) ; 255 /*! Description forthcoming */ 256 IOFireWireLibIsochPortCallback (*SetStopHandler)( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortCallback inHandler) ; 257 258} IOFireWireRemoteIsochPortInterface ; 259 260/*! @class 261 @abstract FireWire user client local isochronous port object. 262 @discussion Represents a FireWire isochronous talker or listener 263 within the local machine. Isochronous transfer is controlled by 264 an associated DCL (Data Stream Control Language) program, which 265 is similar to a hardware DMA program but is hardware agnostic. 266 DCL programs can be written using the 267 IOFireWireDCLCommandPoolInterface object. 268 269 This interface contains all methods of IOFireWireIsochPortInterface 270 and IOFireWireLocalIsochPortInterface. This interface will 271 contain all v2 methods of IOFireWireLocalIsochPortInterface when 272 instantiated as v2 or newer. 273 274 Transfer buffers for the local isoch port must all come from a single allocation 275 made with vm_allocate() or mmap(..., MAP_ANON ). 276 277 Calling vm_deallocate() on the buffers before deallocating a local isoch port object 278 may result in a deadlock. 279 280 Note: Calling Release() on the local isoch port may not immediately release the isoch port; 281 so it may not be safe to call vm_deallocate() on your transfer buffers. To guarantee 282 the port has been release, run the isochronous runloop until the port is finalized (it has 283 processed any pending callbacks). The finalize callback will be called when 284 the port is finalized. Set the finalize callback using SetFinalizeCallback(). 285 */ 286typedef struct IOFireWireLocalIsochPortInterface_t { 287 288 IUNKNOWN_C_GUTS ; 289 /*! Interface revision */ 290 UInt32 revision; 291 /*! Interface revision */ 292 UInt32 version; 293 294 IOFIREWIRELIBISOCHPORT_C_GUTS ; 295 296 /*! @function ModifyJumpDCL 297 @abstract Change the jump target label of a jump DCL. 298 @discussion Use this function to change the flow of a DCL 299 program. Works whether the DCL program is currently running 300 or not. 301 @param self The local isoch port interface to use. 302 @param inJump The jump DCL to modify. 303 @param inLabel The label to jump to. 304 @result kIOReturnSuccess on success. Will return an error if 'inJump' 305 does not point to a valid jump DCL or 'inLabel' does not point to a 306 valid label DCL.*/ 307 IOReturn (*ModifyJumpDCL)( IOFireWireLibLocalIsochPortRef self, DCLJump* inJump, DCLLabel* inLabel) ; 308 309 // --- utility functions ---------- 310 /*! @function PrintDCLProgram 311 @abstract Display the contents of a DCL program. 312 @param self The local isoch port interface to use. 313 @param inProgram A pointer to the first DCL of the program to display. 314 @param inLength The length (in DCLs) of the program.*/ 315 void (*PrintDCLProgram)( IOFireWireLibLocalIsochPortRef self, const DCLCommand* inProgram, UInt32 inLength) ; 316 317 // 318 // --- v2 319 // 320 321 /*! @function ModifyTransferPacketDCLSize 322 @abstract Modify the transfer size of a transfer packet DCL (send or 323 receive) 324 @discussion Allows you to modify transfer packet DCLs after they have 325 been compiled and while the DCL program is still running. The 326 transfer size can be set to any size less than or equal to the size 327 set when the DCL program was compiled (including 0). 328 329 Availability: IOFireWireLocalIsochPortInterface_v2 and newer. 330 331 @param self The local isoch port interface to use. 332 @param inDCL A pointer to the DCL to modify. 333 @param size The new size of data to be transferred. 334 @result Returns kIOReturnSuccess on success. Will return an 335 error if 'size' is too large for this program.*/ 336 IOReturn (*ModifyTransferPacketDCLSize)( IOFireWireLibLocalIsochPortRef self, DCLTransferPacket* inDCL, IOByteCount size ) ; 337 338 // 339 // --- v3 340 // 341 342 /*! @function ModifyTransferPacketDCLBuffer 343 @abstract NOT IMPLEMENTED. Modify the transfer size of a 344 transfer packet DCL (send or receive) 345 @discussion NOT IMPLEMENTED. Allows you to modify transfer packet DCLs 346 after they have been compiled and while the DCL program is still 347 running. The buffer can be set to be any location within the range 348 of buffers specified when the DCL program was compiled (including 349 0). 350 351 Availability: IOFireWireLocalIsochPortInterface_v3 and newer. 352 353 @param self The local isoch port interface to use. 354 @param inDCL A pointer to the DCL to modify. 355 @param buffer The new buffer to or from data will be transferred. 356 @result Returns kIOReturnSuccess on success. Will return an 357 error if the range specified by [buffer, buffer+size] is not 358 in the range of memory locked down for this program.*/ 359 IOReturn (*ModifyTransferPacketDCLBuffer)( IOFireWireLibLocalIsochPortRef self, DCLTransferPacket* inDCL, void* buffer ) ; 360 361 /*! @function ModifyTransferPacketDCL 362 @abstract Modify the transfer size of a transfer packet DCL (send or receive) 363 @discussion Allows you to modify transfer packet DCLs after they 364 have been compiled and while the DCL program is still 365 running. The transfer size can be set to any size less than 366 or equal to the size set when the DCL program was compiled 367 (including 0). 368 369 Availability: IOFireWireLocalIsochPortInterface_v3 and newer. 370 371 @param self The local isoch port interface to use. 372 @param inDCL A pointer to the DCL to modify. 373 @param buffer The new buffer to or from data will be transferred. 374 @param size The new size of data to be transferred. 375 @result Returns kIOReturnSuccess on success. Will return an 376 error if 'size' is too large or 'inDCL' does not point to a 377 valid transfer packet DCL, or the range specified by 378 [buffer, buffer+size] is not in the range of memory locked 379 down for this program.*/ 380 IOReturn (*ModifyTransferPacketDCL)( IOFireWireLibLocalIsochPortRef self, DCLTransferPacket* inDCL, void* buffer, IOByteCount size ) ; 381 382 // 383 // v4 384 // 385 386 /*! @function SetFinalizeCallback 387 @abstract Set the finalize callback for a local isoch port 388 @discussion When Stop() is called on a LocalIsochPortInterface, there may or 389 may not be isoch callbacks still pending for this isoch port. The port must be allowed 390 to handle any pending callbacks, so the isoch runloop should not be stopped until a port 391 has handled all pending callbacks. The finalize callback is called after the final 392 callback has been made on the isoch runloop. After this callback is sent, it is safe 393 to stop the isoch runloop. 394 395 You should not access the isoch port after the finalize callback has been made; it may 396 be released immediately after this callback is sent. 397 398 Availability: IOFireWireLocalIsochPortInterface_v4 and newer. 399 400 @param self The local isoch port interface to use. 401 @param finalizeCallback The finalize callback. 402 @result Returns true if this isoch port has no more pending callbacks and does not 403 need any more runloop time.*/ 404 IOReturn (*SetFinalizeCallback)( IOFireWireLibLocalIsochPortRef self, IOFireWireLibIsochPortFinalizeCallback finalizeCallback ) ; 405 406 // 407 // v5 408 // 409 410 IOReturn (*SetResourceUsageFlags)( IOFireWireLibLocalIsochPortRef self, IOFWIsochResourceFlags flags ) ; 411 IOReturn (*Notify)( IOFireWireLibLocalIsochPortRef self, IOFWDCLNotificationType notificationType, void ** inDCLList, UInt32 numDCLs ) ; 412 413} IOFireWireLocalIsochPortInterface ; 414 415// ============================================================ 416// 417// IOFireWireIsochChannelInterface 418// 419// ============================================================ 420 421 /*! @class 422 @abstract FireWire user client isochronous channel object. 423 @discussion IOFireWireIsochChannelInterface is an abstract 424 representataion of a FireWire bus isochronous channel. This 425 interface coordinates starting and stopping traffic on a 426 FireWire bus isochronous channel and can optionally 427 communicate with the IRM to automatically allocate bandwidth 428 and channel numbers. When using automatic IRM allocation, 429 the channel interface reallocates its bandwidth and channel 430 reservation after each bus reset. 431 432 Isochronous port interfaces representing FireWire isochronous talkers 433 and listeners must be added to the channel using SetTalker() and 434 AddListener() 435 */ 436typedef struct IOFireWireIsochChannelInterface_t 437{ 438 IUNKNOWN_C_GUTS ; 439 /*! Interface revision. */ 440 UInt32 revision; 441 /*! Interface version. */ 442 UInt32 version; 443 444 /*! @function SetTalker 445 @abstract Set the talker port for this channel. 446 @param self The isoch channel interface to use. 447 @param talker The new talker. 448 @result Returns an IOReturn error code. */ 449 IOReturn (*SetTalker) ( IOFireWireLibIsochChannelRef self, IOFireWireLibIsochPortRef talker ) ; 450 451 /*! @function AddListener 452 @abstract Modify the transfer size of a transfer packet DCL (send or receive) 453 @discussion Allows you to modify transfer packet DCLs after they have 454 been compiled and while the DCL program is still running. The 455 transfer size can be set to any size less than or equal to the size 456 set when the DCL program was compiled (including 0). 457 458 Availability: IOFireWireLocalIsochPortInterface_v3 and newer. 459 460 @param self The isoch channel interface to use. 461 @param listener The listener to add. 462 @result Returns an IOReturn error code. */ 463 IOReturn (*AddListener) ( IOFireWireLibIsochChannelRef self, IOFireWireLibIsochPortRef listener ) ; 464 465 /*! @function AllocateChannel 466 @abstract Prepare all hardware to begin sending or receiving isochronous data. 467 @discussion Calling this function will result in all listener and talker ports on this 468 isochronous channel having their AllocatePort method called. 469 @param self The isoch channel interface to use. 470 @result Returns an IOReturn error code. */ 471 IOReturn (*AllocateChannel) ( IOFireWireLibIsochChannelRef self ) ; 472 473 /*! @function ReleaseChannel 474 @abstract Release all hardware after stopping the isochronous channel. 475 @discussion Calling this function will result in all listener and talker ports on this 476 isochronous channel having their ReleasePort method called. 477 @param self The isoch channel interface to use. 478 @result Returns an IOReturn error code. */ 479 IOReturn (*ReleaseChannel) ( IOFireWireLibIsochChannelRef self ) ; 480 481 /*! @function Start 482 @abstract Start the channel. 483 @discussion Calling this function will result in all listener and talker ports on this 484 isochronous channel having their Start method called. 485 @param self The isoch channel interface to use. 486 @result Returns an IOReturn error code. */ 487 IOReturn (*Start) ( IOFireWireLibIsochChannelRef self ) ; 488 489 /*! @function Stop 490 @abstract Stop the channel. 491 @discussion Calling this function will result in all listener and talker ports on this 492 isochronous channel having their Stop method called. 493 @param self The isoch channel interface to use. 494 @result Returns an IOReturn error code. */ 495 IOReturn (*Stop) ( IOFireWireLibIsochChannelRef self ) ; 496 497 // --- notification 498 /*! @function SetChannelForceStopHandler 499 @abstract Set the channel force stop handler. 500 @discussion The specified callback is called when the channel is stopped and cannot be 501 restarted automatically. 502 @param self The isoch channel interface to use. 503 @param stopProc The handler to set. 504 @result Returns the previously set handler or NULL is no handler was set.*/ 505 IOFireWireIsochChannelForceStopHandler (*SetChannelForceStopHandler) 506 ( IOFireWireLibIsochChannelRef self, IOFireWireIsochChannelForceStopHandler stopProc) ; 507 508 /*! @function SetRefCon 509 @abstract Set reference value associated with this channel. 510 @discussion Retrieve the reference value with GetRefCon() 511 @param self The isoch channel interface to use. 512 @param stopProcRefCon The new reference value.*/ 513 void (*SetRefCon) ( IOFireWireLibIsochChannelRef self, void* stopProcRefCon) ; 514 515 /*! @function GetRefCon 516 @abstract Set reference value associated with this channel. 517 @discussion Retrieve the reference value with SetRefCon() 518 @param self The isoch channel interface to use.*/ 519 void* (*GetRefCon) ( IOFireWireLibIsochChannelRef self) ; 520 521 /*! Description forthcoming */ 522 Boolean (*NotificationIsOn) ( IOFireWireLibIsochChannelRef self) ; 523 /*! Description forthcoming */ 524 Boolean (*TurnOnNotification) ( IOFireWireLibIsochChannelRef self) ; 525 /*! Description forthcoming */ 526 void (*TurnOffNotification) ( IOFireWireLibIsochChannelRef self) ; 527 /*! Description forthcoming */ 528 void (*ClientCommandIsComplete) ( IOFireWireLibIsochChannelRef self, FWClientCommandID commandID, IOReturn status) ; 529 530} IOFireWireIsochChannelInterface ; 531 532// ============================================================ 533// 534// IOFireWireDCLCommandPoolInterface 535// 536// ============================================================ 537 538/*! @class IOFireWireDCLCommandPoolInterface 539 Description forthcoming. 540*/ 541typedef struct IOFireWireDCLCommandPoolInterface_t 542{ 543 IUNKNOWN_C_GUTS ; 544 /*! Interface revision. */ 545 UInt32 revision; 546 /*! Interface version. */ 547 UInt32 version; 548 549 /*! Description forthcoming */ 550 DCLCommand* (*Allocate) ( IOFireWireLibDCLCommandPoolRef self, IOByteCount inSize ) ; 551 /*! Description forthcoming */ 552 IOReturn (*AllocateWithOpcode) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, DCLCommand** outDCL, UInt32 opcode, ... ) ; 553 554 /*! Description forthcoming */ 555 DCLCommand* (*AllocateTransferPacketDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, UInt32 inOpcode, void* inBuffer, IOByteCount inSize) ; 556 /*! Description forthcoming */ 557 DCLCommand* (*AllocateTransferBufferDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, UInt32 inOpcode, void* inBuffer, IOByteCount inSize, IOByteCount inPacketSize, UInt32 inBufferOffset) ; 558 559 /*! Description forthcoming */ 560 DCLCommand* (*AllocateSendPacketStartDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, void* inBuffer, IOByteCount inSize) ; 561 562 // AllocateSendPacketWithHeaderStartDCL has been deprecated! If you need this functionality, you should be using NuDCL! 563 /*! Description forthcoming */ 564 DCLCommand* (*AllocateSendPacketWithHeaderStartDCL)( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, void* inBuffer, IOByteCount inSize) ; 565 566 /*! Description forthcoming */ 567 DCLCommand* (*AllocateSendBufferDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, void* inBuffer, IOByteCount inSize, IOByteCount inPacketSize, UInt32 inBufferOffset) ; 568 /*! Description forthcoming */ 569 DCLCommand* (*AllocateSendPacketDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, void* inBuffer, IOByteCount inSize) ; 570 571 /*! Description forthcoming */ 572 DCLCommand* (*AllocateReceivePacketStartDCL)( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, void* inBuffer, IOByteCount inSize) ; 573 /*! Description forthcoming */ 574 DCLCommand* (*AllocateReceivePacketDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, void* inBuffer, IOByteCount inSize) ; 575 /*! Description forthcoming */ 576 DCLCommand* (*AllocateReceiveBufferDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, void* inBuffer, IOByteCount inSize, IOByteCount inPacketSize, UInt32 inBufferOffset) ; 577 578 /*! Description forthcoming */ 579 DCLCommand* (*AllocateCallProcDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, DCLCallCommandProc* inProc, DCLCallProcDataType inProcData) ; 580 /*! Description forthcoming */ 581 DCLCommand* (*AllocateLabelDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL) ; 582 /*! Description forthcoming */ 583 DCLCommand* (*AllocateJumpDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, DCLLabel* pInJumpDCLLabel) ; 584 /*! Description forthcoming */ 585 DCLCommand* (*AllocateSetTagSyncBitsDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, UInt16 inTagBits, UInt16 inSyncBits) ; 586 /*! Description forthcoming */ 587 DCLCommand* (*AllocateUpdateDCLListDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, DCLCommand** inDCLCommandList, UInt32 inNumCommands) ; 588 /*! Description forthcoming */ 589 DCLCommand* (*AllocatePtrTimeStampDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL, UInt32* inTimeStampPtr) ; 590 591 /*! Description forthcoming */ 592 void (*Free) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand* inDCL ) ; 593 594 /*! Description forthcoming */ 595 IOByteCount (*GetSize) ( IOFireWireLibDCLCommandPoolRef self ) ; 596 /*! Description forthcoming */ 597 Boolean (*SetSize) ( IOFireWireLibDCLCommandPoolRef self, IOByteCount inSize ) ; 598 /*! Description forthcoming */ 599 IOByteCount (*GetBytesRemaining) ( IOFireWireLibDCLCommandPoolRef self ) ; 600} IOFireWireDCLCommandPoolInterface ; 601 602/*! @class IOFireWireNuDCLPoolInterface 603 @discussion Use this interface to build NuDCL-based DCL programs. 604*/ 605typedef struct IOFireWireNuDCLPoolInterface_t 606{ 607 IUNKNOWN_C_GUTS ; 608 609 /*! Interface version */ 610 UInt32 revision; 611 /*! Interface version */ 612 UInt32 version; 613 614 // Command pool management: 615 616 /*! @function GetProgram 617 @abstract Finds the first DCL in the pool not preceeded by any other DCL. 618 @discussion Returns a backwards-compatible DCL program pointer. This can be passed 619 to IOFireWireLibDeviceRef::CreateLocalIsochPort. 620 @param self The NuDCL pool to use. 621 @result A DCLCommand pointer.*/ 622 DCLCommand* (*GetProgram)( IOFireWireLibNuDCLPoolRef self ) ; 623 624 /*! @function GetDCLs 625 @abstract Returns the pool's DCL program as a CFArray of NuDCLRef's. 626 @param self The NuDCL pool to use. 627 @result A CFArrayRef.*/ 628 CFArrayRef (*GetDCLs)( IOFireWireLibNuDCLPoolRef self ) ; 629 630 /*! Description forthcoming */ 631 void (*PrintProgram)( IOFireWireLibNuDCLPoolRef self ) ; 632 /*! Description forthcoming */ 633 void (*PrintDCL)( NuDCLRef dcl ) ; 634 635 // Allocating transmit NuDCLs: 636 637 /*! @function SetCurrentTagAndSync 638 @abstract Set current tag and sync bits 639 @discussion Sets the DCL pool's current tag and sync bits. All send DCLs allocated after calling 640 this function will transmit the specified tag and sync values. These fields can also be 641 set on each DCL using SetDCLTagBits() and SetDCLSyncBits(). 642 @param self The NuDCL pool to use. 643 @param tag Tag field value for subsequently allocated send DCLs 644 @param sync Sync field value for subsequently allocated send DCLs */ 645 void (*SetCurrentTagAndSync)( IOFireWireLibNuDCLPoolRef self, UInt8 tag, UInt8 sync ) ; 646 647 /*! @function AllocateSendPacket 648 @abstract Allocate a SendPacket NuDCL and append it to the program. 649 @discussion The SendPacket DCL sends an isochronous packet on the bus. One DCL runs per bus cycle. 650 The isochronous header is automatically generated, but can be overriden. An update must be run to 651 regenerate the isochronous header. The sync and tag fields of allocated DCLs default to 0, unless 652 If SetCurrentTagAndSync has been called. 653 654 Send DCLs can be modified using other functions of IOFireWireLibNuDCLPool. 655 @param self The NuDCL pool to use. 656 @param saveBag The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated 657 DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure. 658 @param numBuffers The number of virtual ranges in 'buffers'. 659 @param buffers An array of virtual memory ranges containing the packet contents. The array is copied 660 into the DCL. 661 @result Returns an NuDCLSendPacketRef on success or 0 on failure. */ 662 NuDCLSendPacketRef (*AllocateSendPacket)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, UInt32 numBuffers, IOVirtualRange* buffers ) ; 663 664 /*! @function AllocateSendPacket_v 665 @abstract Allocate a SendPacket NuDCL and append it to the program. 666 @discussion Same as AllocateSendPacket but ranges are passed as a NULL-terminated vector of IOVirtualRange's 667 @param self The NuDCL pool to use. 668 @param saveBag The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated 669 DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure. 670 @param firstRange The first buffer to be transmitted. Follow with additional ranges; terminate with NULL. 671 @result Returns an NuDCLSendPacketRef on success or 0 on failure. */ 672 NuDCLSendPacketRef (*AllocateSendPacket_v)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, IOVirtualRange* firstRange, ... ) ; 673 674 /*! @function AllocateSkipCycle 675 @abstract Allocate a SkipCycle NuDCL and append it to the program. 676 @discussion The SkipCycle DCL causes the DCL program to "sends" an empty cycle. 677 @param self The NuDCL pool to use. 678 @result Returns an NuDCLSkipCycleRef on success or 0 on failure. */ 679 NuDCLSkipCycleRef (*AllocateSkipCycle)( IOFireWireLibNuDCLPoolRef self ) ; 680 681 // Allocating receive NuDCLs: 682 683 /*! @function AllocateReceivePacket 684 @abstract Allocate a ReceivePacket NuDCL and append it to the program 685 @discussion The ReceivePacket DCL receives an isochronous packet from the bus. One DCL runs per bus cycle. 686 If receiving isochronous headers, an update must be run before the isochronous header is valid. 687 688 Receive DCLs can be modified using other functions of IOFireWireLibNuDCLPool. 689 690 @param self The NuDCL pool to use. 691 @param headerBytes Number of bytes of isochronous header to receive with the data. Valid values are 0, 4, and 8. 692 @param saveBag The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated 693 DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure. 694 @param numBuffers The number of virtual ranges in 'buffers'. 695 @param buffers An array of virtual memory ranges containing the packet contents. The array is copied 696 into the DCL. 697 @result Returns an NuDCLReceivePacketRef on success or 0 on failure. */ 698 NuDCLReceivePacketRef (*AllocateReceivePacket)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, UInt8 headerBytes, UInt32 numBuffers, IOVirtualRange* buffers ) ; 699 700 /*! @function AllocateReceivePacket_v 701 @abstract Allocate a ReceivePacket NuDCL and append it to the program 702 @discussion Same as AllocateReceivePacket but ranges are passed as a NULL-terminated vector of IOVirtualRange's 703 @param self The NuDCL pool to use. 704 @param saveBag The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated 705 DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure. 706 @param headerBytes Number of bytes of isochronous header to receive with the data. Valid values are 0, 4, and 8. 707 @param firstRange The first buffer to be transmitted. Follow with additional ranges; terminate with NULL. 708 @result Returns an NuDCLReceivePacketRef on success or 0 on failure. */ 709 NuDCLReceivePacketRef (*AllocateReceivePacket_v)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, UInt8 headerBytes, IOVirtualRange* firstRange, ... ) ; 710 711 // NuDCL configuration 712 713 /*! @function FindDCLNextDCL 714 @abstract Get the next pointer for a NuDCL 715 @discussion Applies: Any NuDCLRef 716 @param dcl The dcl whose next pointer will be returned 717 @result Returns the DCL immediately following this DCL in program order (ignoring branches) or 0 for none.*/ 718 NuDCLRef (*FindDCLNextDCL)( IOFireWireLibNuDCLPoolRef self, NuDCLRef dcl ) ; 719 720 /*! @function SetDCLBranch 721 @abstract Set the branch pointer for a NuDCL 722 @discussion Program execution will jump to the DCL pointed to by 'branchDCL', after the DCL is executed. If set to 0, 723 execution will stop after this DCL. 724 725 This change will apply immediately to a non-running DCL program. To apply the change to a running program 726 use IOFireWireLocalIsochPortInterface::Notify() 727 728 Applies: Any NuDCLRef. 729 @result Returns an IOReturn error code.*/ 730 IOReturn (*SetDCLBranch)( NuDCLRef dcl, NuDCLRef branchDCL ) ; 731 732 /*! @function GetDCLBranch 733 @abstract Get the branch pointer for a NuDCL 734 @discussion Applies: Any NuDCLRef. 735 @param dcl The dcl whose branch pointer will be returned. 736 @result Returns the branch pointer of 'dcl' or 0 for none is set.*/ 737 NuDCLRef (*GetDCLBranch)( NuDCLRef dcl ) ; 738 739 /*! @function SetDCLTimeStampPtr 740 @abstract Set the time stamp pointer for a NuDCL 741 @discussion Setting a the time stamp pointer for a NuDCL causes a time stamp to be recorded when a DCL executes. 742 This DCL must be updated after it has executed for the timestamp to be valid. 743 744 This change will apply immediately to a non-running DCL program. To apply the change to a running program 745 use IOFireWireLocalIsochPortInterface::Notify() 746 747 Applies: Any NuDCLRef. 748 749 @param dcl The DCL for which time stamp pointer will be set 750 @param timeStampPtr A pointer to a quadlet which will hold the timestamp after 'dcl' is updated. 751 @result Returns an IOReturn error code.*/ 752 IOReturn (*SetDCLTimeStampPtr)( NuDCLRef dcl, UInt32* timeStampPtr ) ; 753 754 /*! @function GetDCLTimeStampPtr 755 @abstract Get the time stamp pointer for a NuDCL. 756 @discussion Applies: Any NuDCLRef. 757 758 @param dcl The DCL whose timestamp pointer will be returned. 759 @result Returns a UInt32 time stamp pointer.*/ 760 UInt32* (*GetDCLTimeStampPtr)( NuDCLRef dcl ) ; 761 762 /*! @function SetDCLStatusPtr 763 @abstract Set the status pointer for a NuDCL 764 @discussion Setting a the status pointer for a NuDCL causes the packet transmit/receive hardware status to be recorded when the DCL executes. 765 This DCL must be updated after it has executed for the status to be valid. 766 767 This change will apply immediately to a non-running DCL program. To apply the change to a running program 768 use IOFireWireLocalIsochPortInterface::Notify() 769 770 Status values are as follows: (from the OHCI spec, section 3.1.1) 771 772 <dfn><table bgcolor="#EBEBEB"> 773 <tr> 774 <td><b>5'h00</b></td> <td>No event status. </td> 775 </tr> 776 <tr> 777 <td><b>5'h02</b></td> <td>evt_long_packet (receive)</td> <td>The received data length was greater than the buffer's data_length. </td> 778 </tr> 779 <tr> 780 <td><b>5'h05</b></td> <td>evt_overrun (receive)</td> <td>A receive FIFO overflowed during the reception of an isochronous packet. </td> 781 </tr> 782 <tr> 783 <td><b>5'h06</b></td> <td>evt_descriptor_read (receive/transmit)</td> <td>An unrecoverable error occurred while the Host Controller was reading a descriptor block. </td> 784 </tr> 785 <tr> 786 <td><b>5'h07</b></td> <td>evt_data_read (transmit)</td> <td>An error occurred while the Host Controller was attempting to read from host memory in the data stage of descriptor processing. </td> 787 </tr> 788 <tr> 789 <td><b>5'h08</b></td> <td>evt_data_write (receive/transmit)</td> <td>An error occurred while the Host Controller was attempting to write to host memory either in the data stage of descriptor processing (AR, IR), or when processing a single 16-bit host memory write (IT). </td> 790 </tr> 791 <tr> 792 <td><b>5'h0A</b></td> <td>evt_timeout (transmit)</td> <td>Indicates that the asynchronous transmit response packet expired and was not transmitted, or that an IT DMA context experienced a skip processing overflow (See section9.3.4). </td> 793 </tr> 794 <tr> 795 <td><b>5'h0B</b></td> <td>evt_tcode_err (transmit)</td> <td>A bad tCode is associated with this packet. The packet was flushed. </td> 796 </tr> 797 <tr> 798 <td><b>5'h0E</b></td> <td>evt_unknown (receive/transmit)</td> <td>An error condition has occurred that cannot be represented by any other event codes defined herein. </td> 799 </tr> 800 <tr> 801 <td><b>5'h11</b></td> <td>ack_complete (receive/transmit)</td> <td>No event occurred. (Success)</td> 802 </tr> 803 <tr> 804 <td><b>5'h1D</b></td> <td>ack_data_error (receive)</td> <td>A data field CRC or data_length error.</td> 805 </tr> 806 </table> 807 </dfn> 808 809 Applies: Any NuDCLRef. 810 811 @param dcl The DCL for which status pointer will be set 812 @param statusPtr A pointer to a quadlet which will hold the status after 'dcl' is updated. 813 @result Returns an IOReturn error code.*/ 814 IOReturn (*SetDCLStatusPtr)( NuDCLRef dcl, UInt32* statusPtr ) ; 815 816 /*! @function GetDCLStatusPtr 817 @abstract Get the status pointer for a NuDCL. 818 @discussion Applies: Any NuDCLRef. 819 @param dcl The DCL whose status pointer will be returned. 820 @result Returns a UInt32 status pointer.*/ 821 UInt32* (*GetDCLStatusPtr)( NuDCLRef dcl ) ; 822 823 824 /*! @function AppendDCLRanges 825 @abstract Add a memory range to the scatter gather list of a NuDCL 826 @discussion This change will apply immediately to a non-running DCL program. To apply the change to a running program 827 use IOFireWireLocalIsochPortInterface::Notify() 828 829 Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef 830 831 @param dcl The DCL to modify 832 @param range A IOVirtualRange to add to this DCL buffer list. Do not pass NULL. 833 @result Returns an IOReturn error code.*/ 834 IOReturn (*AppendDCLRanges) ( NuDCLRef dcl, UInt32 numRanges, IOVirtualRange* range ) ; 835 836 /*! @function SetDCLRanges 837 @abstract Set the scatter gather list for a NuDCL 838 @discussion Set the list of data buffers for a DCL. Setting too many ranges may result in a memory region 839 with too many discontinous physical segments for the hardware to send or receive in a single packet. 840 This will result in an error when the program is compiled. 841 842 This change will apply immediately to a non-running DCL program. To apply the change to a running program 843 use IOFireWireLocalIsochPortInterface::Notify() 844 845 Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef 846 847 @param dcl The DCL to modify 848 @param numRanges number of ranges in 'ranges'. 849 @param ranges An array of virtual ranges 850 @result Returns an IOReturn error code.*/ 851 IOReturn (*SetDCLRanges) ( NuDCLRef dcl, UInt32 numRanges, IOVirtualRange* ranges ) ; 852 853 IOReturn (*SetDCLRanges_v) ( NuDCLRef dcl, IOVirtualRange* firstRange, ... ) ; 854 855 /*! @function GetDCLRanges 856 @abstract Get the scatter-gather list for a NuDCL 857 @discussion 858 859 Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef 860 861 @param dcl The DCL to query 862 @param maxRanges Description forthcoming. 863 @param outRanges Description forthcoming. 864 @result Returns the previously set handler or NULL is no handler was set.*/ 865 UInt32 (*GetDCLRanges) ( NuDCLRef dcl, UInt32 maxRanges, IOVirtualRange* outRanges ) ; 866 867 /*! @function CountDCLRanges 868 @abstract Returns number of buffers for a NuDCL 869 @discussion 870 871 Applies: NuDCLSendPacketRef, NuDCLReceivePacket 872 873 @param dcl The DCL to query 874 @result Returns number of ranges in DCLs scatter-gather list*/ 875 UInt32 (*CountDCLRanges) ( NuDCLRef dcl ) ; 876 877 /*! @function GetDCLSpan 878 @abstract Returns a virtual range spanning lowest referenced buffer address to highest 879 @discussion 880 881 Applies: NuDCLSendPacketRef, NuDCLReceivePacket 882 883 @param dcl The DCL to query 884 @result Returns an IOVirtualRange.*/ 885 IOReturn (*GetDCLSpan) ( NuDCLRef dcl, IOVirtualRange* spanRange ) ; 886 887 /*! @function GetDCLSize 888 @abstract Returns number of bytes to be transferred by a NuDCL 889 @discussion 890 891 Applies: NuDCLSendPacketRef, NuDCLReceivePacket 892 893 @param dcl The DCL to query 894 @result Returns an IOByteCount.*/ 895 IOByteCount (*GetDCLSize) ( NuDCLRef dcl ) ; 896 897 /*! @function SetDCLCallback 898 @abstract Set the callback for a NuDCL 899 @discussion A callback can be called each time a NuDCL is run. Use SetDCLCallback() to set the 900 callback for a NuDCL. If the update option is also set, the callback will be called after the update 901 has run. 902 903 This change will apply immediately to a non-running DCL program. To apply the change to a running program 904 use IOFireWireLocalIsochPortInterface::Notify() 905 906 Applies: Any NuDCLRef 907 908 @param dcl The DCL to modify 909 @param callback The callback function. 910 @result Returns an IOReturn error code.*/ 911 IOReturn (*SetDCLCallback) ( NuDCLRef dcl, NuDCLCallback callback ) ; 912 913 /*! @function GetDCLCallback 914 @abstract Get callback for a NuDCL 915 @discussion Returns the callback function for a DCL 916 917 Applies: Any NuDCLRef 918 919 @param dcl The DCL to query 920 @result Returns the DCLs callback function or NULL if none is set.*/ 921 NuDCLCallback (*GetDCLCallback)( NuDCLRef dcl ) ; 922 923 /*! @function SetDCLUserHeaderPtr 924 @abstract Set a user specified header for a send NuDCL 925 @discussion Allows the client to create a custom header for a transmitted isochronous packet. The header is masked with 'mask', 926 and the FireWire system software fills in the masked out bits. 927 928 This change will apply immediately to a non-running DCL program. 929 An update must be run on the DCL for changes to take effect in a running program. 930 931 Applies: NuDCLSendPacketRef 932 933 @param dcl The DCL to modify 934 @param headerPtr A pointer to a two-quadlet header. See section 9.6 of the the OHCI specification. 935 @param mask A pointer to a two-quadlet mask. The quadlets in headerPtr are masked with 'mask' and the masked-out bits 936 are replaced by the FireWire system software. 937 @result Returns an IOReturn error code.*/ 938 IOReturn (*SetDCLUserHeaderPtr)( NuDCLRef dcl, UInt32 * headerPtr, UInt32 * mask ) ; 939 940 /*! Description forthcoming */ 941 UInt32 * (*GetDCLUserHeaderPtr)( NuDCLRef dcl ) ; 942 943 /*! Description forthcoming */ 944 UInt32 * (*GetUserHeaderMaskPtr)( NuDCLRef dcl ) ; 945 946 /*! Description forthcoming */ 947 void (*SetDCLRefcon)( NuDCLRef dcl, void* refcon ) ; 948 /*! Description forthcoming */ 949 void* (*GetDCLRefcon)( NuDCLRef dcl ) ; 950 951 /*! Description forthcoming */ 952 IOReturn (*AppendDCLUpdateList)( NuDCLRef dcl, NuDCLRef updateDCL ) ; 953 954 // consumes a reference on dclList.. 955 /*! Description forthcoming */ 956 IOReturn (*SetDCLUpdateList)( NuDCLRef dcl, CFSetRef dclList ) ; 957 /*! Description forthcoming */ 958 CFSetRef (*CopyDCLUpdateList)( NuDCLRef dcl ) ; 959 /*! Description forthcoming */ 960 IOReturn (*RemoveDCLUpdateList)( NuDCLRef dcl ) ; 961 962 /*! Description forthcoming */ 963 IOReturn (*SetDCLWaitControl)( NuDCLRef dcl, Boolean wait ) ; 964 965 /*! Description forthcoming */ 966 void (*SetDCLFlags)( NuDCLRef dcl, UInt32 flags ) ; 967 /*! Description forthcoming */ 968 UInt32 (*GetDCLFlags)( NuDCLRef dcl ) ; 969 /*! Description forthcoming */ 970 IOReturn (*SetDCLSkipBranch)( NuDCLRef dcl, NuDCLRef skipCycleDCL ) ; 971 /*! Description forthcoming */ 972 NuDCLRef (*GetDCLSkipBranch)( NuDCLRef dcl ) ; 973 /*! Description forthcoming */ 974 IOReturn (*SetDCLSkipCallback)( NuDCLRef dcl, NuDCLCallback callback ) ; 975 /*! Description forthcoming */ 976 NuDCLCallback (*GetDCLSkipCallback)( NuDCLRef dcl ) ; 977 /*! Description forthcoming */ 978 IOReturn (*SetDCLSkipRefcon)( NuDCLRef dcl, void * refcon ) ; 979 /*! Description forthcoming */ 980 void * (*GetDCLSkipRefcon)( NuDCLRef dcl ) ; 981 /*! Description forthcoming */ 982 IOReturn (*SetDCLSyncBits)( NuDCLRef dcl, UInt8 syncBits ) ; 983 /*! Description forthcoming */ 984 UInt8 (*GetDCLSyncBits)( NuDCLRef dcl ) ; 985 /*! Description forthcoming */ 986 IOReturn (*SetDCLTagBits)( NuDCLRef dcl, UInt8 tagBits ) ; 987 /*! Description forthcoming */ 988 UInt8 (*GetDCLTagBits)( NuDCLRef dcl ) ; 989 990} IOFireWireNuDCLPoolInterface ; 991 992#pragma mark - 993#pragma mark ASYNCSTREAM LISTENER INTERFACE 994// ============================================================ 995// IOFWAsyncStreamListener Interface 996// ============================================================ 997 998/*! @class 999 @discussion Represents and provides management functions for a asyn stream listener object. 1000*/ 1001typedef struct IOFWAsyncStreamListenerInterface_t 1002{ 1003 IUNKNOWN_C_GUTS ; 1004 1005 /*! Interface version. */ 1006 UInt16 version; 1007 /*! Interface revision. */ 1008 UInt16 revision; 1009 1010 /*! @function SetListenerHandler 1011 @abstract Set the callback that should be called to handle incoming async stream packets 1012 @param self The async stream interface to use. 1013 @param inReceiver The callback to set. 1014 @result Returns the callback that was previously set or nil for none.*/ 1015 const IOFWAsyncStreamListenerHandler (*SetListenerHandler)( IOFWAsyncStreamListenerInterfaceRef self, IOFWAsyncStreamListenerHandler inReceiver) ; 1016 1017 /*! @function SetSkippedPacketHandler 1018 @abstract Set the callback that should be called when incoming packets are 1019 dropped by the address space. 1020 @param self The address space interface to use. 1021 @param inHandler The callback to set. 1022 @result Returns the callback that was previously set or nil for none.*/ 1023 const IOFWAsyncStreamListenerSkippedPacketHandler (*SetSkippedPacketHandler)( IOFWAsyncStreamListenerInterfaceRef self, IOFWAsyncStreamListenerSkippedPacketHandler inHandler) ; 1024 1025 /*! @function NotificationIsOn 1026 @abstract Is notification on? 1027 @param self The async stream interface to use. 1028 @result Returns true if packet notifications for this channel are active */ 1029 Boolean (*NotificationIsOn)(IOFWAsyncStreamListenerInterfaceRef self) ; 1030 1031 /*! @function TurnOnNotification 1032 @abstract Try to turn on packet notifications for this channel. 1033 @param self The async stream interface to use. 1034 @result Returns true upon success */ 1035 Boolean (*TurnOnNotification)(IOFWAsyncStreamListenerInterfaceRef self) ; 1036 1037 /*! @function TurnOffNotification 1038 @abstract Force packet notification off. 1039 @param self The async stream interface to use. */ 1040 void (*TurnOffNotification)(IOFWAsyncStreamListenerInterfaceRef self) ; 1041 1042 /*! @function ClientCommandIsComplete 1043 @abstract Notify the async stream object that a packet notification handler has completed. 1044 @discussion Packet notifications are received one at a time, in order. This function 1045 must be called after a packet handler has completed its work. 1046 @param self The async stream interface to use. 1047 @param commandID The ID of the packet notification being completed. This is the same 1048 ID that was passed when a packet notification handler is called. 1049 @param status The completion status of the packet handler */ 1050 void (*ClientCommandIsComplete)(IOFWAsyncStreamListenerInterfaceRef self, FWClientCommandID commandID, IOReturn status) ; 1051 1052 // --- accessors ---------- 1053 1054 /*! @function GetRefCon 1055 @abstract Returns the user refCon value for this async stream interface. 1056 @param self The async stream interface to use. 1057 @result returns the callback object.*/ 1058 void* (*GetRefCon)(IOFWAsyncStreamListenerInterfaceRef self) ; 1059 1060 /*! @function SetFlags 1061 @abstract set flags for the listener. 1062 @param self The async stream interface to use. 1063 @param flags indicate performance metrics. 1064 @result none. */ 1065 void (*SetFlags)( IOFWAsyncStreamListenerInterfaceRef self, UInt32 flags ); 1066 1067 /*! @function GetFlags 1068 @abstract get the flags of listener. 1069 @param self The async stream interface to use. 1070 @result flags. */ 1071 UInt32 (*GetFlags)(IOFWAsyncStreamListenerInterfaceRef self); 1072 1073 1074 /*! @function GetOverrunCounter 1075 @abstract get overrun counter from the DCL program. 1076 @param self The async stream interface to use. 1077 @result returns the counter value. */ 1078 UInt32 (*GetOverrunCounter)(IOFWAsyncStreamListenerInterfaceRef self); 1079 1080} IOFWAsyncStreamListenerInterface ; 1081 1082#endif //__IOFireWireLibIsoch_H__ 1083