/*
* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
*
* @APPLE_LICENSE_HEADER_START@
*
* The contents of this file constitute Original Code as defined in and
* are subject to the Apple Public Source License Version 1.1 (the
* "License"). You may not use this file except in compliance with the
* License. Please obtain a copy of the License at
* http://www.apple.com/publicsource and read it before using this file.
*
* This Original Code and all software distributed under the License are
* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
* License for the specific language governing rights and limitations
* under the License.
*
* @APPLE_LICENSE_HEADER_END@
*/
/*
* IOFireWireLib.h
* IOFireWireLib
*
* Created on Thu Apr 27 2000.
* Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved.
*
*/
/*! @header IOFireWireLib.h
IOFireWireLib is the software used by user space software to communicate with FireWire
devices and control the FireWire bus. IOFireWireLib is the lowest-level FireWire interface available
in user space.
To communicate with a device on the FireWire bus, an instance of IOFireWireDeviceInterface (a struct
which is defined below) is created. The methods of IOFireWireDeviceInterface allow you
to communicate with the device and create instances of other interfaces which provide extended
functionality (for example, creation of unit directories on the local machine).
References to interfaces should be kept using the interface reference typedefs defined herein.
For example, you should use IOFireWireLibDeviceRef to refer to instances of IOFireWireDeviceInterface,
IOFireWireLibCommandRef to refer to instances of IOFireWireCommandInterface, and so on.
To obtain an IOFireWireDeviceInterface for a device on the FireWire bus, use the function
IOCreatePlugInInterfaceForService() defined in IOKit/IOCFPlugIn.h. (Note the "i" in "PlugIn" is
always upper-case.) Quick usage reference:

'service' is a reference to the IOKit registry entry of the kernel object
(usually of type IOFireWireDevice) representing the device
of interest. This reference can be obtained using the functions defined in
IOKit/IOKitLib.h.

'plugInType' should be CFUUIDGetUUIDBytes(kIOCFPlugInInterfaceID)

'interfaceType' should be CFUUIDGetUUIDBytes(kIOFireWireLibTypeID) when using IOFireWireLib

*/
/* headerdoc parse workaround
class IOFireWireDeviceInterface: public IUnknown {
public:
*/
IUNKNOWN_C_GUTS ;
UInt32 version, revision ; // version/revision
// --- maintenance methods -------------
/*!
@function InterfaceIsInited
@abstract Determine whether interface has been properly inited.
@param self The device interface to use.
@result Returns true if interface is inited and false if is it not.
*/
Boolean (*InterfaceIsInited)(IOFireWireLibDeviceRef self) ;
/*!
@function GetDevice
@abstract Get the IOKit service to which this interface is connected.
@param self The device interface to use.
@result Returns an io_object_t corresponding to the device the interface is
using
*/
io_object_t (*GetDevice)(IOFireWireLibDeviceRef self) ;
/*!
@function Open
@abstract Open the connected device for exclusive access. When you have
the device open using this method, all accesses by other clients of
this device will be denied until Close() is called.
@param self The device interface to use.
@result An IOReturn error code
*/
IOReturn (*Open)(IOFireWireLibDeviceRef self) ;
/*!
@function OpenWithSessionRef
@abstract An open function which allows this interface to have access
to the device when already opened. The service which has already opened
the device must be able to provide an IOFireWireSessionRef.
@param self The device interface to use
@param IOFireWireSessionRef The sessionRef returned from the client who has
the device open
@result An IOReturn error code
*/
IOReturn (*OpenWithSessionRef)(IOFireWireLibDeviceRef self, IOFireWireSessionRef sessionRef) ;
/*!
@function Close
@abstract Release exclusive access to the device
@param self The device interface to use
*/
void (*Close)(IOFireWireLibDeviceRef self) ;
// --- notification --------------------
/*!
@function NotificationIsOn
@abstract Determine whether callback notifications for this interface are currently active
@param self The device interface to use
@result A Boolean value where true indicates notifications are active
*/
const Boolean (*NotificationIsOn)(IOFireWireLibDeviceRef self) ;
/*!
@function AddCallbackDispatcherToRunLoop
@abstract Installs the proper run loop event source to allow callbacks to function. This method
must be called before callback notifications for this interface or any interfaces
created using this interface can function.
@param self The device interface to use.
@param inRunLoop The run loop on which to install the event source
*/
const IOReturn (*AddCallbackDispatcherToRunLoop)(IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop) ;
/*!
@function RemoveCallbackDispatcherFromRunLoop
@abstract Reverses the effects of AddCallbackDispatcherToRunLoop(). This method removes
the run loop event source that was added to the specified run loop preventing any
future callbacks from being called
@param self The device interface to use.
*/
const void (*RemoveCallbackDispatcherFromRunLoop)(IOFireWireLibDeviceRef self) ;
/*!
@function TurnOnNotification
@abstract Activates any callbacks specified for this device interface. Only works after
AddCallbackDispatcherToRunLoop has been called. See also AddIsochCallbackDispatcherToRunLoop().
@param self The device interface to use.
@result A Boolean value. Returns true on success.
*/
const Boolean (*TurnOnNotification)(IOFireWireLibDeviceRef self) ;
/*!
@function TurnOffNotification
@abstract Deactivates and callbacks specified for this device interface. Reverses the
effects of TurnOnNotification()
@param self The device interface to use.
*/
void (*TurnOffNotification)(IOFireWireLibDeviceRef self) ;
/*!
@function SetBusResetHandler
@abstract Sets the callback that should be called when a bus reset occurs. Note that this callback
can be called multiple times before the bus reset done handler is called. (f.ex., multiple bus
resets might occur before bus reconfiguration has completed.)
@param self The device interface to use.
@param handler Function pointer to the handler to install
@result Returns an IOFireWireBusResetHandler function pointer to the previously installed
bus reset handler. Returns 0 if none was set.
*/
const IOFireWireBusResetHandler
(*SetBusResetHandler)(IOFireWireLibDeviceRef self, IOFireWireBusResetHandler handler) ;
/*!
@function SetBusResetDoneHandler
@abstract Sets the callback that should be called after a bus reset has occurred and reconfiguration
of the bus has been completed. This function will only be called once per bus reset.
@param self The device interface to use.
@param handler Function pointer to the handler to install
@result Returns on IOFireWireBusResetDoneHandler function pointer to the previously installed
bus reset handler. Returns 0 if none was set.
*/
const IOFireWireBusResetDoneHandler
(*SetBusResetDoneHandler)(IOFireWireLibDeviceRef self, IOFireWireBusResetDoneHandler handler) ;
/*!
@function ClientCommandIsComplete
@abstract This function must be called from callback routines once they have completed processing
a callback. This function only applies to callbacks which take an IOFireWireLibDeviceRef (i.e. bus reset),
parameter.
@param commandID The command ID passed to the callback function when it was called
@param status An IOReturn value indicating the completion status of the callback function
*/
void (*ClientCommandIsComplete)(IOFireWireLibDeviceRef self, FWClientCommandID commandID, IOReturn status) ;
// --- read/write/lock operations -------
/*!
@function Read
@abstract Perform synchronous block read
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to read.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported.
@param addr Command target address
@param buf A pointer to a buffer where the results will be stored
@param size Number of bytes to read
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in generation. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOReturn error code
*/
IOReturn (*Read)(IOFireWireLibDeviceRef self,
io_object_t device,
const FWAddress* addr,
void* buf,
UInt32* size,
Boolean failOnReset,
UInt32 generation) ;
/*!
@function ReadQuadlet
@abstract Perform synchronous quadlet read
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to read.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported.
@param addr Command target address
@param value A pointer to where to data should be stored
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in generation. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration()
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOReturn error code
*/
IOReturn (*ReadQuadlet)( IOFireWireLibDeviceRef self,
io_object_t device,
const FWAddress* addr,
UInt32* val,
Boolean failOnReset,
UInt32 generation) ;
/*!
@function Write
@abstract Perform synchronous block write
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported.
@param addr Command target address
@param buf A pointer to a buffer where the results will be stored
@param size Number of bytes to read
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOReturn error code
*/
IOReturn (*Write)( IOFireWireLibDeviceRef self,
io_object_t device,
const FWAddress* addr,
const void* buf,
UInt32* size,
Boolean failOnReset,
UInt32 generation) ;
/*!
@function WriteQuadlet
@abstract Perform synchronous quadlet write
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported.
@param addr Command target address
@param val The value to write
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOReturn error code
*/
IOReturn (*WriteQuadlet)(IOFireWireLibDeviceRef self, io_object_t device, const FWAddress* addr, const UInt32 val, Boolean failOnReset, UInt32 generation) ;
/*!
@function CompareSwap
@abstract Perform synchronous lock operation
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported.
@param addr Command target address
@param cmpVal The check/compare value
@param newVal Value to set
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOReturn error code
*/
IOReturn (*CompareSwap)(IOFireWireLibDeviceRef self, io_object_t device, const FWAddress* addr, UInt32 cmpVal, UInt32 newVal, Boolean failOnReset, UInt32 generation) ;
// --- FireWire command object methods ---------
/*!
@function CreateReadCommand
@abstract Create a block read command object.
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported. Setting the callback value to nil defaults to synchronous execution.
@param addr Command target address
@param buf A pointer to a buffer where the results will be stored
@param size Number of bytes to read
@param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution.
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.
*/
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) ;
/*! @function CreateReadQuadletCommand
@abstract Create a quadlet read command object.
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported. Setting the callback value to nil defaults to synchronous execution.
@param addr Command target address
@param quads An array of quadlets where results should be stored
@param numQuads Number of quadlets to read
@param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution.
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.*/
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) ;
/*! @function CreateWriteCommand
@abstract Create a block write command object.
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported. Setting the callback value to nil defaults to synchronous execution.
@param addr Command target address
@param buf A pointer to the buffer containing the data to be written
@param size Number of bytes to write
@param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution.
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.*/
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) ;
/*!
@function CreateWriteQuadletCommand
@abstract Create a quadlet write command object.
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported. Setting the callback value to nil defaults to synchronous execution.
@param addr Command target address
@param quads An array of quadlets containing quadlets to be written
@param numQuads Number of quadlets to write
@param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution.
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.
*/
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) ;
/*!
@function CreateCompareSwapCommand
@abstract Create a quadlet compare/swap command object.
@param self The device interface to use.
@param device The service (representing an attached FireWire device) to which to write.
For 48-bit, device relative addressing, pass the service used to create the device interface. This
can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are
unsupported. Setting the callback value to nil defaults to synchronous execution.
@param addr Command target address
@param cmpVal 32-bit value expected at target address
@param newVal 32-bit value to be set at target address
@param callback Command completion callback. Setting the callback value to nil defaults to synchronous execution.
@param failOnReset Pass true if the command should only be executed during the FireWire bus generation
specified in 'generation'. Pass false to ignore the generation parameter. The generation can be
obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
@param generation The FireWire bus generation during which the command should be executed. Ignored
if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.
@result An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef. */
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) ;
// --- other methods ---------------------------
/*! @function BusReset
@abstract Cause a bus reset
@param self The device interface to use. */
IOReturn (*BusReset)( IOFireWireLibDeviceRef self) ;
/*! @function GetCycleTime
@abstract Get bus cycle time.
@param self The device interface to use.
@param outCycleTime A pointer to a UInt32 to hold the result
@result An IOReturn error code. */
IOReturn (*GetCycleTime)( IOFireWireLibDeviceRef self, UInt32* outCycleTime) ;
/*! @function GetGenerationAndNodeID
@abstract (Obsolete) Get bus generation and remote device node ID.
@discussion Obsolete -- Please use GetBusGeneration() and/or GetRemoteNodeID() in
interface v4.
@param self The device interface to use.
@param outGeneration A pointer to a UInt32 to hold the generation result
@param outNodeID A pointer to a UInt16 to hold the remote device node ID
@result An IOReturn error code. */
IOReturn (*GetGenerationAndNodeID)( IOFireWireLibDeviceRef self, UInt32* outGeneration, UInt16* outNodeID) ;
/*! @function GetLocalNodeID
@abstract (Obsolete) Get local node ID.
@discussion Obsolete -- Please use GetBusGeneration() and GetLocalNodeIDWithGeneration() in
interface v4.
@param self The device interface to use.
@param outNodeID A pointer to a UInt16 to hold the local device node ID
@result An IOReturn error code. */
IOReturn (*GetLocalNodeID)( IOFireWireLibDeviceRef self, UInt16* outLocalNodeID) ;
/*! @function GetResetTime
@abstract Get time since last bus reset.
@param self The device interface to use.
@param outResetTime A pointer to an AbsolutTime to hold the result.
@result An IOReturn error code. */
IOReturn (*GetResetTime)(
IOFireWireLibDeviceRef self,
AbsoluteTime* outResetTime) ;
// --- unit directory support ------------------
/*! @function CreateLocalUnitDirectory
@abstract Creates a local unit directory object and returns an interface to it. An
instance of a unit directory object corresponds to an instance of a unit
directory in the local machine's configuration ROM.
@param self The device interface to use.
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created unit directory object.
@result An IOFireWireLibLocalUnitDirectoryRef. Returns 0 upon failure */
IOFireWireLibLocalUnitDirectoryRef (*CreateLocalUnitDirectory)( IOFireWireLibDeviceRef self, REFIID iid) ;
// --- config directory support ----------------
/*! @function GetConfigDirectory
@abstract Creates a config directory object and returns an interface to it. The
created config directory object represents the config directory in the remote
device or unit to which the creating device interface is attached.
@param self The device interface to use.
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created config directory object.
@result An IOFireWireLibConfigDirectoryRef which should be released using Release().
Returns 0 upon failure. */
IOFireWireLibConfigDirectoryRef (*GetConfigDirectory)( IOFireWireLibDeviceRef self, REFIID iid) ;
/*! @function CreateConfigDirectoryWithIOObject
@abstract This function can be used to create a config directory object and a
corresponding interface from an opaque IOObject reference. Some configuration
directory interface methods may return an io_object_t instead of an
IOFireWireLibConfigDirectoryRef. Use this function to obtain an
IOFireWireLibConfigDirectoryRef from an io_object_t.
@param self The device interface to use.
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created config directory object.
@result An IOFireWireLibConfigDirectoryRef. Returns 0 upon failure */
IOFireWireLibConfigDirectoryRef (*CreateConfigDirectoryWithIOObject)( IOFireWireLibDeviceRef self, io_object_t inObject, REFIID iid) ;
// --- address space support -------------------
/*! @function CreatePseudoAddressSpace
@abstract Creates a pseudo address space object and returns an interface to it. This
will create a pseudo address space (software-backed) on the local machine.
@param self The device interface to use.
@param inSize The size in bytes of this address space
@param inRefCon A user specified reference value. This will be passed to all callback functions.
@param inQueueBufferSize The size of the queue which receives packets from the bus before they are handed to
the client and/or put in the backing store. A larger queue can help eliminate dropped packets
when receiving large bursts of data. When a packet is received which can not fit into the queue,
the packet dropped callback will be called.
@param inBackingStore An optional block of allocated memory representing the contents of the address space.
@param inFlags A UInt32 with bits set corresponding to the flags that should be set
for this address space.

kFWAddressSpaceNoFlags -- All flags off

kFWAddressSpaceNoWriteAccess -- Write access to this address space will be disallowed.
Setting this flag also disables compare/swap transactions on this address space.

kFWAddressSpaceNoReadAccess -- Read access access to this address space will be disallowed.
Setting this flag also disables compare/swap transactions on this address space.

kFWAddressSpaceAutoWriteReply -- Writes will be made automatically, directly modifying the contents
of the backing store. The user process will not be notified of writes.

kFWAddressSpaceAutoReadReply -- Reads to this address space will be answered automagically
using the contents of the backing store. The user process will not be notified of reads.

kFWAddressSpaceAutoCopyOnWrite -- Writes to this address space will be made directly
to the backing store at the same time the user process is notified of a write.

@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created pseudo address space object.
@result An IOFireWireLibPseudoAddressSpaceRef. Returns 0 upon failure */
IOFireWireLibPseudoAddressSpaceRef (*CreatePseudoAddressSpace)(
IOFireWireLibDeviceRef self,
UInt32 inSize,
void* inRefCon,
UInt32 inQueueBufferSize,
void* inBackingStore,
UInt32 inFlags,
REFIID iid) ;
/*! @function CreatePhysicalAddressSpace
@abstract Creates a physical address space object and returns an interface to it. This
will create a physical address space on the local machine.
@param self The device interface to use.
@param inBackingStore An block of allocated memory representing the contents of the address space.
@param inSize The size in bytes of this address space
@param inFlags A UInt32 with bits set corresponding to the flags that should be set
for this address space. For future use -- always pass 0.
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created physical address space object.
@result An IOFireWireLibPhysicalAddressSpaceRef. Returns 0 upon failure */
IOFireWireLibPhysicalAddressSpaceRef (*CreatePhysicalAddressSpace)( IOFireWireLibDeviceRef self, UInt32 inSize, void* inBackingStore, UInt32 inFlags, REFIID iid) ;
// --- debugging -------------------------------
IOReturn (*FireBugMsg)( IOFireWireLibDeviceRef self, const char* msg) ;
//
// NOTE: the following methods available only in interface v2 and later
//
// --- eye-sock-run-U.S. -----------------------
/*! @function AddIsochCallbackDispatcherToRunLoop
@abstract This function adds an event source for the isochronous callback dispatcher
to the specified CFRunLoop. Isochronous related callbacks will not function
before this function is called. This functions is similar to
AddCallbackDispatcherToRunLoop. The passed CFRunLoop can be different
from that passed to AddCallbackDispatcherToRunLoop.
@param self The device interface to use.
@param inRunLoop A CFRunLoopRef for the run loop to which the event loop source
should be added
@result An IOReturn error code. */
IOReturn (*AddIsochCallbackDispatcherToRunLoop)(
IOFireWireLibDeviceRef self,
CFRunLoopRef inRunLoop) ;
/*! @function CreateRemoteIsochPort
@abstract Creates a remote isochronous port object and returns an interface to it. A
remote isochronous port object is an abstract entity used to represent a remote
talker or listener device on an isochronous channel.
@param self The device interface to use.
@param inTalking Pass true if this port represents an isochronous talker. Pass
false if this port represents an isochronous listener.
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created remote isochronous port object.
@result An IOFireWireLibRemoteIsochPortRef. Returns 0 upon failure */
IOFireWireLibRemoteIsochPortRef
(*CreateRemoteIsochPort)(
IOFireWireLibDeviceRef self,
Boolean inTalking,
REFIID iid) ;
/*! @function CreateLocalIsochPort
@abstract Creates a local isochronous port object and returns an interface to it. A
local isochronous port object is an abstract entity used to represent a
talking or listening endpoint in the local machine.
@param self The device interface to use.
@param inTalking Pass true if this port represents an isochronous talker. Pass
false if this port represents an isochronous listener.
@param inDCLProgram A pointer to the first DCL command struct of the DCL program
to be compiled and used to send or receive data on this port.
@param inStartEvent Start event: 0 or kFWDCLCycleEvent or kFWDCLSyBitsEvent
@param inStartState Start state bits. For kFWDCLCycleEvent specifies the cycle to start the DMA on.
For kFWDCLSyBitsEvent specifies the packet sync field value for the first packet to receive.
@param inStartMask Start mask bits. For kFWDCLCycleEvent specifies a mask for the start cycle:
the DMA will start when currentCycle & inStartMask == inStartEvent & inStartMask.
For kFWDCLSyBitsEvent specifies a mask for the sync field:
the DMA will start when packet sync == inStartEvent & inStartMask.
@param inDCLProgramRanges This is an optional optimization parameter which can be used
to decrease the time the local port object spends determining which set of virtual
ranges the passed DCL program occupies. Pass a pointer to an array of IOVirtualRange
structs or nil to ignore this parameter.
@param inDCLProgramRangeCount The number of virtual ranges passed to inDCLProgramRanges.
Pass 0 for none.
@param inBufferRanges This is an optional optimization parameter which can be used
to decrease the time the local port object spends determining which set of virtual
ranges the data buffers referenced by the passed DCL program occupy. Pass a pointer
to an array of IOVirtualRange structs or nil to ignore this parameter.
@param inBufferRangeCount The number of virtual ranges passed to inBufferRanges.
Pass 0 for none.
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created object.
@result An IOFireWireLibLocalIsochPortRef. Returns 0 upon failure */
IOFireWireLibLocalIsochPortRef
(*CreateLocalIsochPort)(
IOFireWireLibDeviceRef self,
Boolean inTalking,
DCLCommand* inDCLProgram,
UInt32 inStartEvent,
UInt32 inStartState,
UInt32 inStartMask,
IOVirtualRange inDCLProgramRanges[], // optional optimization parameters
UInt32 inDCLProgramRangeCount,
IOVirtualRange inBufferRanges[],
UInt32 inBufferRangeCount,
REFIID iid) ;
/*! @function CreateIsochChannel
@abstract Creates an isochronous channel object and returns an interface to it. An
isochronous channel object is an abstract entity used to represent a
FireWire isochronous channel.
@param self The device interface to use.
@param doIRM Controls whether the channel automatically performs IRM operations.
Pass true if the channel should allocate its channel and bandwidth with
the IRM. Pass false to ignore the IRM.
@param packetSize Size of payload in bytes of packets being sent or received with this channel,
excluding headers. This is automatically translated into a bandwidth allocation appropriate
for the speed passed in prefSpeed.
@param prefSpeed The preferred bus speed of this channel.
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created object.
@result An IOFireWireLibIsochChannelRef. Returns 0 upon failure */
IOFireWireLibIsochChannelRef
(*CreateIsochChannel)(
IOFireWireLibDeviceRef self,
Boolean doIrm,
UInt32 packetSize,
IOFWSpeed prefSpeed,
REFIID iid ) ;
/*! @function CreateDCLCommandPool
@abstract Creates a command pool object and returns an interface to it. The command
pool can be used to build DCL programs.
@param self The device interface to use.
@param size Starting size of command pool
@param iid An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the
type of interface to be returned for the created object.
@result An IOFireWireLibDCLCommandPoolRef. Returns 0 upon failure */
IOFireWireLibDCLCommandPoolRef
(*CreateDCLCommandPool)(
IOFireWireLibDeviceRef self,
IOByteCount size,
REFIID iid ) ;
// --- refcons ---------------------------------
/*! @function GetRefCon
@abstract Get user reference value set on this interface
@param self The device interface to use.
@result Returns the user's reference value set on this interface. */
void* (*GetRefCon)(
IOFireWireLibDeviceRef self) ;
/*! @function SetRefCon
@abstract Set user reference value on this interface
@param self The device interface to use.
@param refCon The reference value to set. */
void (*SetRefCon)(
IOFireWireLibDeviceRef self,
const void* refCon) ;
// --- debugging -------------------------------
// do not use this function
CFTypeRef (*GetDebugProperty)(
IOFireWireLibDeviceRef self,
void* interface,
CFStringRef inPropertyName,
CFTypeID* outPropertyType) ;
/*! @function PrintDCLProgram
@abstract Walk a DCL program linked list and print its contents
@param self The device interface to use.
@param inProgram A pointer to the first DCL of the program to print
@param inLength Number of DCLs expected in the program. PrintDCLProgram() will
report an error if this number does not match the number of DCLs found
in the program. */
void (*PrintDCLProgram)(
IOFireWireLibDeviceRef self,
const DCLCommand* inProgram,
UInt32 inLength) ;
//
// NOTE: the following methods available only in interface v3 and later
//
// --- v3 functions ----------
/*! @function CreateInitialUnitsPseudoAddressSpace
@abstract Creates a pseudo address space in initial units space.
@discussion Creates a pseudo address space object in initial units space and returns an interface to it. This
will create a pseudo address space (software-backed) on the local machine.
Availablilty: IOFireWireDeviceInterface_v3, and newer
@param self The device interface to use.
@param inAddressLo The lower 32 bits of the base address of the address space to be created. The address is always
in initial units space.
@param inSize The size in bytes of this address space
@param inRefCon A user specified reference value. This will be passed to all callback functions.
@param inQueueBufferSize The size of the queue which receives packets from the bus before they are handed to
the client and/or put in the backing store. A larger queue can help eliminate dropped packets
when receiving large bursts of data. When a packet is received which can not fit into the queue,
the packet dropped callback will be called.
@param inBackingStore An optional block of allocated memory representing the contents of the address space.
@param inFlags A UInt32 with bits set corresponding to the flags that should be set
for this address space.

kFWAddressSpaceNoFlags -- All flags off

kFWAddressSpaceNoWriteAccess -- Write access to this address space will be disallowed.
Setting this flag also disables compare/swap transactions on this address space.

kFWAddressSpaceNoReadAccess -- Read access access to this address space will be disallowed.
Setting this flag also disables compare/swap transactions on this address space.

kFWAddressSpaceAutoWriteReply -- Writes will be made automatically, directly modifying the contents
of the backing store. The user process will not be notified of writes.

kFWAddressSpaceAutoReadReply -- Reads to this address space will be answered automagically
using the contents of the backing store. The user process will not be notified of reads.

kFWAddressSpaceAutoCopyOnWrite -- Writes to this address space will be made directly
to the backing store at the same time the user process is notified of a write. Clients
will only be notified of a write if kFWAddressSpaceAutoWriteReply is not set.

kFWAddressSpaceShareIfExists -- Allows creation of this address space even if another client
already has an address space at the requested address. All clients will be notified of writes to
covered addresses.

kFWAddressSpaceExclusive -- Ensures that the allocation of this address space will fail if any portion
of this address range is already allocated. If the allocation is successful this flag ensures that any
future allocations overlapping this range will fail even if allocted with kFWAddressSpaceShareIfExists.

@param self The command object interface of interest
@param addr A pointer to an FWAddress. */
/*
void (*SetTarget)(IOFireWireLibCommandRef self, const FWAddress* addr) ;
*/
/*! @function SetGeneration
@abstract Set FireWire bus generation for which the command object shall be valid.
If the failOnReset attribute has been set, the command will only be considered for
execution during the bus generation specified by this function.
@discussion Availability: (for interfaces obtained with ID)

@param self The command object interface of interest
@param maxPacketSize Size in bytes of largest packet that should be transferred
by this command.
@result An IOReturn result code indicating whether or not the command was successfully
submitted */
/*
IOReturn (*SetMaxPacket)(IOFireWireLibCommandRef self, IOByteCount maxPacketSize) ;
*/
/*! @function SetFlags
@abstract Set flags governing this command's execution.
@discussion Availability: (for interfaces obtained with ID)

kIOFireWireReadCommandInterfaceID

NO

kIOFireWireReadCommandInterfaceID_v2

YES

kIOFireWireWriteCommandInterfaceID

NO

kIOFireWireWriteCommandInterfaceID_v2

YES

kIOFireWireReadQuadletCommandInterfaceID

NO

kIOFireWireWriteQuadletCommandInterfaceID

NO

kIOFireWireCompareSwapCommandInterfaceID

NO

kIOFireWireAsyncStreamCommandInterfaceID

YES

@param self The command object interface of interest
@param inFlags A UInt32 with bits set corresponding to the flags that should be set
for this command object. The following values may be used:

kFWCommandNoFlags -- all flags off

kFWCommandInterfaceForceNoCopy -- data sent by this command should always be
received/sent directly from the buffer set with SetBuffer(). Whatever data
is in the buffer when the command is submitted will be used.

kFWCommandInterfaceForceCopyAlways -- data will always be copied out of the
command object data buffer when SetBuffer() is called, up to a maximum
allowed size (kFWUserCommandSubmitWithCopyMaxBufferBytes). This can result
in faster data transfer. Changes made to the data buffer contents after
calling SetBuffer() will be ignored; SetBuffer() should be called whenever
the data buffer contents change.

kFWCommandInterfaceSyncExecute -- Setting this flag causes the command object
to execute synchronously. The calling context will block until the command
object has completed execution or an error occurs. Using synchronous execution
can avoid kernel transitions associated with asynchronous completion and often
remove the need for a state machine.

kFWCommandInterfaceForceBlockRequest -- Setting this flag causes read and write
transactions to use block request packets even if the payload is 4 bytes. If this
flag is not set 4 byte transactions will occur using quadlet transactions.

kFWCommandInterfaceSyncExecute -- Setting this flag causes the command object
to execute synchronously. The calling context will block until the command
object has completed execution or an error occurs. Using synchronous execution
can avoid kernel transitions associated with asynchronous completion and often
remove the need for a state machine.

kFWVectorCommandInterfaceOrdered - Normally all commands in a vector are executed
simultaneously. Setting this flag will dispatch a command only after the prior
command has completed.