Application programming interface for managing and automating data transfer operations between applications over a bus structure

An applications programming interface implements and manages isochronous and asynchronous data transfer operations between an application and a bus structure. During an asyncronous transfer the API includes the ability to transfer any amount of data between one or more local data buffers within the application and a range of addresses over the bus structure using one or more asynchronous transactions. An automatic transaction generator may be used to automatically generate the transactions necessary to complete the data transfer. The API also includes the ability to transfer data between the application and another node on the bus structure isochronously over a dedicated channel. During an isochronous data transfer, a buffer management scheme is used to manage a linked list of data buffer descriptors. This linked descriptor list can form a circular list of buffers and include a forward pointer to the next buffer in the list and a backward pointer to the previous buffer in the list for each buffer. The linked descriptor list may also form a linear list to which the application can append additional buffers or remove existing buffers from the list. During isochronous transfers of data, the API provides implementation of a resynchronization event in the stream of data allowing for resynchronization by the application to a specific point within the data. Implementation is also provided for a callback routine for each buffer in the list which calls the application at a predetermined point during the transfer of data.

FIELD OF THE INVENTION 
The present invention relates to the field of providing an interface for 
applications to communicate over a bus structure. More particularly, the 
present invention relates to the field of controlling bus management and 
data transfer operations between applications over a bus structure in both 
asynchronous and isochronous formats. 
BACKGROUND OF THE INVENTION 
The IEEE 1394 standard, "P1394 Standard For A High Performance Serial Bus," 
Draft 8.01 v1, Jun. 16, 1995, is an international standard for 
implementing an inexpensive high-speed serial bus architecture which 
supports both asynchronous and isochronous format data transfers. 
Isochronous data transfers are real-time transfers which take place such 
that the time intervals between significant instances have the same 
duration at both the transmitting and receiving applications. Each packet 
of data transferred isochronously is transferred in its own time period. 
An example of an ideal application for the transfer of data isochronously 
would be from a video recorder to a television set. The video recorder 
records images and sounds and saves the data in discrete chunks or 
packets. The video recorder then transfers each packet, representing the 
image and sound recorded over a limited time period, during that time 
period, for display by the television set. The IEEE 1394 standard bus 
architecture provides multiple channels for isochronous data transfer 
between applications. A six bit channel number is broadcast with the data 
to ensure reception by the appropriate application. This allows multiple 
applications to simultaneously transmit isochronous data across the bus 
structure. Asynchronous transfers are traditional data transfer operations 
which take place as soon as possible and transfer an amount of data from a 
source to a destination. 
The IEEE 1394 standard provides a high-speed serial bus for interconnecting 
digital devices thereby providing a universal I/O connection. The IEEE 
1394 standard defines a digital interface for the applications thereby 
eliminating the need for an application to convert digital data to analog 
data before it is transmitted across the bus. Correspondingly, a receiving 
application will receive digital data from the bus, not analog data, and 
will therefore not be required to convert analog data to digital data. The 
cable required by the IEEE 1394 standard is very thin in size compared to 
other bulkier cables used to connect such devices. Devices can be added 
and removed from an IEEE 1394 bus while the bus is active. If a device is 
so added or removed the bus will then automatically reconfigure itself for 
transmitting data between the then existing nodes. A node is considered a 
logical entity with a unique address on the bus structure. Each node 
provides an identification ROM, a standardized set of control registers 
and its own address space. 
The IEEE 1394 standard defines a protocol as illustrated in FIG. 1. This 
protocol includes a serial bus management block 10 coupled to a 
transaction layer 12, a link layer 14 and a physical layer 16. The 
physical layer 16 provides the electrical and mechanical connection 
between a device or application and the IEEE 1394 cable. The physical 
layer 16 also provides arbitration to ensure that all devices coupled to 
the IEEE 1394 bus have access to the bus as well as actual data 
transmission and reception. The link layer 14 provides data packet 
delivery service for both asynchronous and isochronous data packet 
transport. This supports both asynchronous data transport, using an 
acknowledgement protocol, and isochronous data transport, providing 
real-time guaranteed bandwidth protocol for just-in-time data delivery. 
The transaction layer 12 supports the commands necessary to complete 
asynchronous data transfers, including read, write and lock. The serial 
bus management block 10 contains an isochronous resource manager for 
managing isochronous data transfers. The serial bus management block 10 
also provides overall configuration control of the serial bus in the form 
of optimizing arbitration timing, guarantee of adequate electrical power 
for all devices on the bus, assignment of the cycle master, assignment of 
isochronous channel and bandwidth resources and basic notification of 
errors. 
An application programming interface (API) for applications using the IEEE 
1394 standard serial bus has been developed by Skipstone for enabling the 
application to use the IEEE 1394 bus for data transfers. With their API, 
Skipstone includes a manual entitled "The SerialSoft IEEE 1394 Developer 
Toolkit," available from Skipstone, Inc., 3925 West Braker Lane, #425, 
Austin, Tex. 78759. Skipstone defines their API as a collection of 
programming calls to be used by the application to manage data being 
written to and obtained from a device over an IEEE 1394 bus. To initialize 
an isochronous transfer, several asynchronous data transfers may be 
required to configure the applications and to determine the specific 
channel which will be used for transmission of the data. Once the channel 
has been determined, buffers are used at the transmitting application to 
store the data before it is sent and at the receiving application to store 
the data before it is processed. In a transmitting application, the 
Skipstone API actively manages the transfer of data from the appropriate 
portion of the appropriate buffer onto the bus structure, during the 
appropriate time period. In a receiving application, the Skipstone API 
actively manages the reception of data from the bus structure, storing the 
data in the appropriate portion of the appropriate buffer and the 
processing of the data in the appropriate time period. 
During asynchronous data transfers, the Skipstone API actively manages the 
required transactions to complete the data transfer. During an 
asynchronous incoming write transaction, the application provides a buffer 
to the API, mapped to a certain area of the 1394 bus address space. As 
write transactions arrive at the API, their data is written to the buffer. 
During an asynchronous incoming read transaction the application is 
responsible for making sure that the buffer contains useful information. 
The 1394 bus driver then reads the data from the buffer at the requested 
address when the read transaction arrives. For both write and read 
transactions, the Skipstone API actively manages and generates each 
necessary transaction. For example, if a block of data is being 
transferred to the application, of a size requiring multiple transactions, 
the Skipstone API requires the application to describe each 1394 
transaction necessary to complete the transfer of the block of data. This 
consumes significant overhead by the processor of the application as well 
as the full attention of the API during an asynchronous data transfer 
operation. 
The Skipstone API supports isochronous data transfer operations in a 
similar way. Specifically, the application must describe each isochronous 
packet to the Skipstone API. The Skipstone API then transmits each packet 
at the proper time. This requires significant processor overhead and 
thereby prohibits efficient processing of the isochronous data by the 
application. 
What is needed is an API that provides automated generation of transactions 
necessary to complete a data transfer, without requiring supervision by 
the API and the processor of an application. What is further needed is an 
API which implements isochronous transfer features of the IEEE 1394 
standard bus structure very efficiently, permitting a high degree of 
hardware automation, if needed by the application. 
SUMMARY OF THE INVENTION 
An applications programming interface implements and manages isochronous 
and asynchronous data transfer operations between an application and a bus 
structure. During an asyncronous transfer the API includes the ability to 
transfer any amount of data between one or more local data buffers within 
the application and a range of addresses over the bus structure using one 
or more asynchronous transactions. An automatic transaction generator may 
be used to automatically generate the transactions necessary to complete 
the data transfer without direct processor control or supervision by the 
applications programming interface. The API also includes the ability to 
transfer data between the application and another node on the bus 
structure isochronously over a dedicated channel. During an isochronous 
data transfer, a buffer management scheme is used to manage a linked list 
of data buffer descriptors provided by the application. The linked list of 
buffer descriptors is maintained by the API to ensure the uninterrupted 
flow of the continuous stream of isochronous data. This linked descriptor 
list can form a circular list of buffers and include a forward pointer to 
the next buffer in the list and a backward pointer to the previous buffer 
in the list for each buffer. The linked descriptor list may also form a 
linear list to which the application can append additional buffers or 
remove existing buffers from the list. During isochronous transfers of 
data, the API provides implementation of a resynchronization event in the 
stream of data allowing for resynchronization by the application to a 
specific point within the data. Implementation is also provided for a 
callback routine for each buffer in the list which calls the application 
at a predetermined point during the transfer of data.

DETAILED DESCRIPTION OF THE PREFERRED EMBODIMENT 
FIG. 3 illustrates a system including a video camera 50, a video cassette 
recorder 52 and a computer 54 connected together by the input/output (I/O) 
busses 56 and 58. The I/O bus 56 couples the video camera 50 to the video 
cassette recorder 52, allowing the video camera 50 to send data to the 
video cassette recorder 52 for recording. The I/O bus 58 couples the video 
cassette recorder 52 to the computer 54, allowing the video cassette 
recorder 52 to send data to the computer 54 for display. 
An applications programming interface (API) according to the present 
invention could be implemented within any one or all of the connected 
subsystems including the video camera 50, the video cassette recorder 52 
or the computer 54, for controlling data transfer operations communicated 
across the bus structures 56 and 58. In the preferred embodiment of the 
present invention the bus structures 56 and 58 are IEEE 1394 standard 
cables. 
A block diagram of a hardware system resident in each system for 
implementing the applications programming interface of the present 
invention is illustrated in FIG. 4. In the hardware system illustrated in 
FIG. 4, a printed circuit board 60 is coupled to a user interface 70. The 
printed circuit board 60 includes a central processing unit (CPU) 62 
coupled to system memory 64 and to an I/O bus interface 66 by the system 
bus 68. The user interface 70 is also coupled to the system bus 68. The 
user interface 70 is subsystem specific, but can include a keyboard, 
display or other I/O devices for communicating with a user of the 
subsystem. 
Each of the subsystems including the video camera 50, the video cassette 
recorder 52 and the computer 54, in order to implement the applications 
programming interface of the present invention, will include a hardware 
system such as the system illustrated in FIG. 4. The CPU 62 within each of 
these devices is used to execute the application program instructions. The 
API of the present invention will then manage both isochronous and 
asynchronous data transfer operations between the resident subsystem and 
one of the other subsystems over an appropriate one of the busses 56 or 
58. 
An applications programming interface according to the present invention 
implements isochronous and asynchronous data transfers to and from an 
application over a bus structure. An application as used herein will refer 
to either an application or a device driver. The bus structure over which 
the data transfer operations are completed is preferably an IEEE 1394 
standard bus structure. However, as will be apparent to those skilled in 
the art, the applications programming interface of the present invention 
will also be applicable for use in managing data transfers over other 
types of bus structures. The applications programming interface includes 
the ability to transfer any amount of data between a local data buffer 
provided by the application and a range of addresses over the bus 
structure using one or more asynchronous transactions. When an 
asynchronous transfer of a block of data is initiated, the applications 
programming interface sends a command to an automatic transaction 
generator. The automatic transaction generator then automatically 
generates the read or write transactions necessary to transfer the 
complete block of data asynchronously without direct processor control or 
requiring supervision by the applications programming interface. 
The applications programming interface also includes the ability to 
transfer data between the application and another node on the bus 
structure isochronously over a dedicated channel. During an isochronous 
data transfer, a buffer management scheme is used to manage data buffers 
within the application. The application may use one, more than one or a 
linked list of buffers depending on the type and amount of data to be 
transferred. A linked list of buffer descriptors that point to the buffers 
is maintained by the API to ensure the uninterrupted flow of the 
continuous stream of isochronous data. This linked descriptor list may 
implement a linear or a circular list of buffers and includes a forward 
pointer to the descriptor for the next buffer in the list and a backward 
pointer to the descriptor for the previous buffer in the list for each 
buffer. When a linear list is implemented, the application can dynamically 
append buffers to the list or remove existing buffers from the list, as 
necessary, for the processing of the data. 
During an isochronous transfer of data, the applications programming 
interface of the present invention provides implementation of a 
resynchronization event in the stream of data allowing for 
resynchronization to a specific point within the data. Implementation is 
also provided for a callback routine for each buffer which calls the 
application at a predetermined specific point during the data transfer 
operation. Both the resynchronization event and the callback routine are 
supported by the IEEE 1394 standard. 
The applications programming interface of the present invention also 
includes the ability to perform bus management operations, as necessary, 
over the bus structure. Such bus management operations include allocating 
and deallocating isochronous channel numbers, as necessary, and allocating 
and deallocating isochronous bandwidth. If the bus structure is an IEEE 
1394 standard bus structure, then the applications programming interface 
also performs other bus management operations as required by the IEEE 1394 
standard. 
A block diagram schematic of an applications programming interface, 
according to the present invention, within a system including a bus 
structure is illustrated in FIG. 2. The API 20 serves as an interface 
between the applications 22 and 24 and the bus structure 28, managing the 
transfer of data between the bus structure 28 and the applications 22 and 
24. As illustrated in FIG. 2, a single API 20 may serve as an interface 
between multiple applications and the bus structure 28. For example, 
within the computer system 54, illustrated in FIG. 3, a single API 20 
could serve as an interface between one or more applications being run by 
the computer system 54. 
A hardware and physical interface 26 is included between the API 20 and the 
bus structure 28. The hardware and physical interface 26 includes an 
automatic transaction generator 38 for automatically generating the 
necessary transactions for completion of an asynchronous data transfer 
between one of the applications 22 or 24 and another node on the bus 
structure 28. The hardware and physical interface 26 also includes a bus 
interface 40 for monitoring and managing the flow of data to and from the 
bus structure 28. The hardware and physical interface 26 is shown coupled 
to a set of memory buffers 30, as controlled by the API 20. The set of 
memory buffers 30 includes the memory buffers 32, 34 and 36. As will be 
described below, the memory buffers 32, 34 and 36 are dedicated to the API 
20 by the application 22 for use in sustaining isochronous data transfers 
to and from the application 22. 
ISOCHRONOUS DATA TRANSFERS 
To initialize an isochronous data transfer operation an application first 
requests an isochronous channel from the API 20. The application may 
either request a specific channel number or any currently available 
channel number. The API 20 then obtains a channel for the isochronous 
transfer per the requirements of the IEEE 1394 standard. The IEEE 1394 
standard supports a six bit channel number which is broadcast with a 
stream of data across the bus structure 28. Once a channel is allocated 
for an isochronous data transfer between an application and another node 
on the bus structure 28, no other nodes may use that specific channel 
number. After a channel is allocated, data buffers must be assigned by the 
application to the API 20 to be used for the data transfer. The API 20 
allows the application to assign one, more than one or a list of data 
buffers to use for receiving or transmitting the isochronous stream of 
data. Each buffer assigned to the API 20 may be contiguous or fragmented 
and logical or physical. The list of data buffers may be circular or 
linear. If a linear list of data buffers is assigned to the API 20 the 
application 22 can add additional buffers or remove buffers from the list 
as necessary to process the data. 
In the system illustrated in FIG. 2, the application 22 has assigned three 
buffers 30, including the buffers 32, 34 and 36 to the API 20 for 
isochronous data transfers. The application has also assigned a linked 
list of three buffer descriptors to the API, one for each of the buffers 
32, 34 and 36. The API 20 maintains a buffer descriptor for each buffer 
within the linked list and manages the flow of the isochronous data 
between the application, the assigned buffers and the bus structure 28. 
Within the list of descriptors managed by the API 20, each buffer is 
represented by a buffer descriptor, including a forward pointer to the 
descriptor for the next buffer in the list and a backward pointer to the 
descriptor for the previous buffer in the list. A list of buffer 
descriptors corresponding to buffers assigned to an API 20 by an 
application is illustrated in FIG. 5. Each of the buffer descriptors 1-n 
correspond to a memory buffer 1-n. Specifically, the buffer descriptor 80 
corresponds to the memory buffer 84 and the buffer descriptor 82 
corresponds to the memory buffer 86. 
The buffer descriptors each include an address and length of the 
corresponding buffer. The buffer descriptor also includes a callback 
completion routine to call after the buffer has been filled or emptied, 
depending on the direction of the current data transfer operation. The 
buffer descriptors further include an optional synchronization event field 
which is programmed by the application and is how the buffer is 
synchronized to a specific event or time. Specifically, the buffer 
descriptor 80 corresponding to the memory buffer 84, includes an address 
80a and a length 80b for the memory buffer 84. A completion routine 80c 
and a synchronization event 80d are also included, if necessary. 
This use of buffer descriptors and memory buffers allows great flexibility 
to an application using the API of the present invention, since the 
descriptors, buffers, completion routines and synchronization events are 
all set up by the application according to its specific needs. As an 
example, for an application that is running in a digital video camera 
transferring data isochronously to a digital video monitor, data is loaded 
in memory buffers, for which the API maintains buffer descriptors. The API 
then manages the transfer of each packet of data from the buffers to the 
video monitor. The video camera is able to implement a 2.times. 
compression feature in the vertical dimension by having pairs of 
descriptors point to the same memory buffer. That is, the descriptors 1 
and 2 will point to the memory buffer 1, the descriptors 3 and 4 will 
point to the memory buffer 2, and so on. A completion routine in the 
second descriptor of each pair notifies the video monitor that data in the 
memory buffer is ready to be read. This means that as the video camera 
outputs first and second scan line data, the second scan line data 
overwrites the first scan line data in the memory buffer with the second 
scan line data. The video monitor does not read the memory buffer until 
after the second scan line is written so the monitor never sees the first 
scan line data. In this manner, every other scan line is skipped. 
The descriptors allow the list to be circular in nature and thereby 
maintain the continuous stream of data to or from the buffers 32, 34 and 
36. During an isochronous data transfer from the application 22 to another 
node along the bus structure 28, the application 22 fills the buffers 32, 
34 and 36, in turn, with the data. The API 20 then manages the 
transferring of the data from the appropriate buffer to the bus structure 
28 during an appropriate time period. The bus interface 40 within the 
hardware and physical interface 26 controls transferring the data from the 
buffers 32, 34 and 36 onto the bus structure 28. During an isochronous 
data transfer from another node along the bus structure 28 to the 
application 22, the API 20 manages transferring the data from the bus 
structure 28, through the bus interface 40, to the appropriate buffer 32, 
34 and 36. As one allocated buffer is filled up, the data is stored in the 
next buffer in the linked list. The application 22 then reads the data 
from the appropriate one of the buffers 32, 34 and 36 during the 
appropriate time period. Once the application 22 has finished reading the 
data from a buffer, the buffer is provided back to the API 20 and the 
application 22 processes the data from the next buffer. 
The buffer descriptors will also implement a linear list of buffers which 
allows the application to assign buffers to or remove buffers from the API 
20, as necessary to complete a data transfer operation. For example, 
during an isochronous receive operation, as the application is finished 
processing each buffer it can then reassign it to the API for receiving 
more data. Correspondingly, if additional buffers are necessary to 
complete a data transfer operation, the application can assign more 
buffers to the API. 
The API 20 will execute a resynchronization event and/or a callback routine 
during the transfer of isochronous data if requested by the application 
22. A resynchronization event allows for resynchronization by the 
application to a predetermined specific point in time within the data 
during the transfer. Because the data is being transferred isochronously, 
this resynchronization event will also synchronize the application to an 
appropriate point in time relative to the data flow. The transfer of video 
data provides an ideal example for the implementation of a 
resynchronization event. During the transfer of video data from an 
application such as a video recorder, the data is transferred in blocks 
representing the data necessary to display one horizontal line on a 
monitor or television. After the display of each horizontal line, the 
monitor must reset itself to be ready to display the next horizontal line. 
A resynchronization event could be employed by the monitor at the end of 
the data for each horizontal line, allowing the monitor to resynchronize 
itself to the beginning of the next horizontal line. 
In the preferred embodiment of the API of the present invention an 
isochronous operation may be synchronized or scheduled to be performed 
immediately, at a specific bus time, when a specific value appears in the 
isochronous data block packet header, or when isochronous data appears on 
a specific channel of the bus for start operations or ends on a specific 
channel of the bus for stop operations. 
Each buffer assigned to the API 20 can have a resynchronization event and a 
callback routine. A callback routine could be employed during the transfer 
of video data at the end of the transfer of a block of data representing a 
frame. A monitor or television groups horizontal lines into a frame and at 
the end of each frame resets itself to the top of the screen to be ready 
for the beginning of the next frame. A callback routine could be used at 
the end of the stream of data representing each frame. Such a scheme would 
allow a buffer to be filled with the data representing a video frame from 
a source coupled to the bus structure 28. After the data representing the 
video frame has been transferred, the callback routine can be used to 
notify the application that the data representing the next frame has been 
transferred and is available for processing. The application could then 
process the data for this frame of data while the data for the next frame 
is being loaded into the next buffer. 
A flow chart illustrating API buffer processing for isochronous send and 
receive operations is shown in FIG. 6. It is assumed that at the start 102 
of an isochronous receive operation that the application has set up the 
buffers/descriptors, completion routine calls and synchronization events. 
The flowchart 100 is entered at step 102 for each isochronous stream that 
requires processing in the bus system. The API 20 keeps track of a current 
descriptor for processing the incoming data. In other words, the API 
maintains a pointer to the next buffer, and location within the next 
buffer where data can be stored. 
At step 104 the next buffer descriptor is obtained from the linked list. At 
step 106 a check is made to determine if any more descriptors are included 
within the linked list. If there are no more descriptors in the linked 
list then the processing is stopped at the step 108. If there are 
additional descriptors then the routine moves to the step 112 where it 
waits until the synchronization event for the current buffer is reached. 
Once the synchronization event is reached, then at the step 114 the 
current buffer is either filled with the incoming data for a receive 
operation or the data from the buffer is transmitted for a send operation. 
After the buffer has been processed, then at the step 116 it is determined 
if a callback routine was included for this buffer. If a callback routine 
was included, then, at the step 118 the callback routine is called. 
Otherwise, the routine goes back to the step 104 and obtains the next 
descriptor. Whether a callback routine is provided or not, the API and 
hardware subsystem 26 assure that the next buffer descriptor is obtained 
such that no isochronous data is lost. 
The steps of the flowchart 100 may be performed by a CPU and related 
subsystems such as found in a typical personal computer (PC), embedded 
processing system, etc. as discussed above in connection with FIGS. 3 and 
4. In general, the steps of flowcharts presented in this specification may 
be implemented in any suitable programming language such as "C", PASCAL, 
FORTRAN, BASIC, assembly language, etc., or in a combination of such 
languages. Any suitable computer programming technique may be used for a 
software design to implement the steps, such as procedural or object 
oriented programming, parallel or distributed processing, interrupt driven 
or polled event processing, etc. Steps may be modified, added to, or taken 
away from, those shown in the flowcharts while still achieving the method 
steps and apparatus elements described in this specification and recited 
in the claims. The processing in a single step may be broken into two or 
more steps. Also, in some embodiments, two or more steps may be 
accomplished at the same time, or their tasks interleaved. The sequencing, 
or routing, of the steps may also be changed. Each flowchart is but one 
instance of a primitive example of the logic used to achieve a function in 
a preferred embodiment of the present invention. 
For purposes of discussion, the cumulative steps of a flowchart are 
referred to as constituting a single "routine," or program, although they 
may be implemented in two or more routines, programs, processes, etc. 
Flowchart steps may also be distributed among processors residing in the 
same or different devices. 
As an example of an isochronous data transfer operation, if the application 
22 is a video monitor which is receiving data isochronously from a video 
recorder at a node coupled to the bus structure 28, the API 20 will manage 
the flow of data from the bus structure to the buffers 32, 34 and 36, each 
represented by a buffer descriptor in the linked list. A first buffer 32 
is filled with the data received from the video recorder. When the first 
buffer 32 is filled, it is processed and displayed by the video monitor 22 
while the next buffer 34 in the linked list is filled. If the first buffer 
32 included a callback routine at the end of the data for a frame, then 
the callback routine could be used to notify the video monitor 22 that it 
could process the data in the first buffer 32, representing the first 
frame. When the video monitor 22 is finished processing the data within 
the first buffer 32 it can then provide the buffer 32 back to the API 20 
for storing additional data received from the bus structure 28. 
If the application 22 is a video recorder transmitting isochronous data to 
another node coupled to the bus structure, then the application loads the 
buffers 32, 34 and 36, in turn, with data. The API 20 will then manage the 
transmission of the data from the buffers 32, 34 and 36 onto the bus 
structure 28 with the appropriate channel number at the appropriate time. 
In this manner the API 20 of the present invention manages isochronous 
data transfers to and from an application 22. 
ASYNCHRONOUS DATA TRANSFERS 
To execute an asynchronous data transfer operation between an application 
24 and another node coupled to the bus structure 28, the API 20 defines 
essentially a direct memory access (DMA) model, utilizing a level of 
hardware automation to automatically generate the requests necessary to 
complete the transfer and allowing the application and the API 20 to 
perform other functions while the data transfer operation is being 
completed. The API 20 provides a memory-mapped interface to the 
application for asynchronous data transfers. To initiate an asynchronous 
data transfer, an application 24 transmits a descriptor to the API 20 
including an address of a buffer within the application's address space, a 
starting address in the address space of the bus structure at which the 
transfer is to take place, a length of the block of data to be transferred 
and a code representing whether the transfer is to be a read or write 
operation. The API 20 provides the necessary data to the hardware 
automatic transfer generator 38 which then generates the one or more 
transactions necessary to complete the transfer of the entire block of 
data across the bus structure 28. The automatic transfer generator 38 then 
generates the necessary read or write transactions to complete the 
transfer of data between the buffer assigned by the application 24 and the 
appropriate addresses across the bus structure 28. This automation does 
not require the attention of the API 20 or the application 24 to complete 
an asynchronous data transfer operation. While in the preferred embodiment 
of the present invention the automatic transaction generator 38 is 
implemented in hardware, it should be apparent to those skilled in the art 
that the automatic transaction generator could also be implemented in 
software within the API 20. If the application does not require this level 
of hardware automation, the API 20 can also generate the transactions 
necessary to complete a data transfer operation, without using the 
automatic transaction generator 38. 
As is known to those skilled in the art each read or write transaction can 
only transfer a certain amount of data depending on the system and the 
capabilities of the bus structure 28. Therefore, to transfer a block of 
data it may be necessary to generate multiple read or write transactions. 
In contrast to the systems of the prior art, the API 20 of the present 
invention sends a single command to the automatic transaction generator 
block 38. The automatic transaction generator block 38 then generates the 
read or write transactions necessary to transfer the complete block of 
data over the bus structure 28, without requiring further attention by the 
API 20. This allows the system to be more efficient, as the API 20 and the 
application 24 can perform other tasks while the transfer is taking place. 
Because the transfer is asynchronous, once the transfer of the entire 
block of data is complete, the API 20 will notify the application 24. 
As discussed above, in the preferred embodiment of the present invention, 
the bus structure 28 is an IEEE 1394 standard bus structure. For 
asynchronous data transfers the bus structure 28 therefore provides a 64 
bit address space. Within the descriptor provided to the automatic 
transaction generator 38, the remote address at which the data transfer is 
to take place is specified by a 64 bit address. 
To initiate an asynchronous read operation, the application 24 transmits a 
descriptor to the API 20 including the address of the buffer within the 
application's address space to which the data is to be transferred, a 64 
bit starting address in the address space of the bus structure 28 from 
which the data is to be read, the length of the block of data to be 
transferred and a code representing that the transfer is a read operation. 
The API 20 then transmits the required information to the automatic 
transaction generator 38. The automatic transaction generator 38 then 
generates the necessary read commands to transfer the data to the 
application's buffer from the proper node on the bus structure 28. The 
application is responsible for ensuring that the specified buffer is 
available before the read transactions are generated. The data is then 
read in response to the transactions generated by the automatic 
transaction generator 38, in a known manner. 
To initiate an asynchronous write operation, the application 24 transmits a 
descriptor to the API 20 including the address of the buffer within the 
application's address space from which the data is to be transferred, a 64 
bit starting address in the address space of the bus structure 28 to which 
the data is to be written, the length of the block of data to be 
transferred and a code representing that the transfer is a write 
operation. The API 20 then transmits the required information to the 
automatic transaction generator 38. The automatic transaction generator 38 
then generates the necessary write commands to transfer the data to the 
proper node on the bus structure 28 from the application's buffer. The 
data is then transferred from the application's buffer in response to the 
transactions generated by the automatic transaction generator 38 in a 
known manner. When the buffer is transferred the application 24 is 
notified. 
API CONVENTIONS AND BUS MANAGEMENT OPERATIONS 
An application calls a routine in the API 20 either synchronously or 
asynchronously. If an application calls a routine synchronously, then at 
the time that the routine returns to the application, the API has 
completed the requested operation or the API returns a completion status 
indicating that the chosen request could not be completed. Alternatively, 
if an application calls a routine asynchronously, then the requested 
action is most likely not complete at the time that the routine returns 
control to the client. In order to call a routine asynchronously, the 
application provides a completion callback routine. The API may call this 
completion routine before returning from the original call. However, in 
most cases the API completes the requested operation after returning from 
the original call that initiated the operation, then calls the 
application's completion routine to indicate that the operation is done. 
Before using any of the services provided by the API, an application must 
first initialize the API. Each application must initialize the API 
separately. An application initializes the API by calling an 
ActivateSonyAPI subroutine. This subroutine establishes a connection 
between the API and the application. When calling the ActivateSonyAPI, the 
application may specify indication routines which the API calls when a bus 
reset or other bus event occurs. The ActivateSonyAPI subroutine returns a 
value to the application which the application then uses on subsequent 
calls to the routines of the API. 
Applications which expect a large number of indications during the course 
of their operation may call the AddIndBuffers routine in order to pass 
additional indication buffers to the API for its exclusive use. The client 
can first call the CountIndBuffers routine in order to check the number of 
buffers that the API currently owns. Prior to deactivating the API, the 
application may release the indication buffers previously given to the API 
by calling a RelIndBuffers routine. 
When an application is finished using the API, it calls a DeactivateSonyAPI 
routine. This routine breaks the connection between the application and 
the API and releases any indication buffers or other resources in use by 
the API on behalf of the application. Note that the API may not be able to 
disassociate from a given application immediately if some of the 
application's buffers are currently in use by the API. During the time 
that the API is active for a given application, that application has 
access to all of the services that the API provides. 
After initializing the API, an application may perform various IEEE 1394 
bus management functions, as defined in section 8 of the IEEE 1394 
standard, and described below. An application may allocate and deallocate 
isochronous channel numbers from the currently active isochronous resource 
manager using the MGMTAllocateChannel and MGMTDeAllocateChannel routines, 
respectively. Using these applications, the application may request to 
allocate a specific channel number, if it is available. Alternatively, an 
application may request to allocate any currently available channel 
number. These API routines follow the requirements of the IEEE 1394 
standard with regard to allocating and deallocating isochronous channel 
numbers. When using isochronous channel numbers, the application is 
responsible for following any other requirements which may apply in the 
IEEE 1394 standard or any other governing protocol document. 
An application may allocate and deallocate isochronous bandwidth from the 
currently active isochronous resource manager using the 
MGMTAllocateBandwidth and MGMTDeAllocateBandwidth routines, respectively. 
These API routines follow the requirements of the IEEE 1394 standard with 
regard to allocating and deallocating isochronous bandwidth. When using 
these routines, the application is responsible for calculating the correct 
amount of isochronous bandwidth needed and allocating exactly that much. 
The application is also responsible for following any applicable rules as 
documented in the IEEE 1394 standard and any other governing protocol 
documents, with regard to allocating, deallocating or owning any 
isochronous bandwidth. 
When an application deactivates the API, the API does not attempt to 
deallocate any bus resources that the application previously allocated. 
This permits the application to relinquish ownership of these resources 
easily, as required in the IEC AV protocols standard. However, this places 
complete responsibility on the application to follow the governing 
protocols when allocating and deallocating isochronous bus resources. 
An application may retrieve the current topology map and speed map 
information from the active bus manager, if present, and any other 
available bus information using the MGMTBusInfo routine. This routine 
retrieves the most current information from the bus manager, whether or 
not the node on which the application is running is the active bus 
manager. Note that this routine will fail if there is no currently active 
bus manager. Section 8 of the IEEE 1394 standard defines the format of the 
topology map and speed map, and the conditions under which a bus manager 
exists or does not exist. 
After initializing the API, the application may call the ASYNDataRequest 
routine to initiate asynchronous data transfer requests over the IEEE 1394 
serial bus. The application may use this routine to initiate any 
asynchronous transaction that is defined in the IEEE 1394 standard, 
including data block read or write requests, quadlet read or write 
requests or any lock request. When the application calls the 
ASYNDataRequest routine, the routine passes a descriptor for a buffer in 
the application's address space, a starting address in the 64 bit IEEE 
1394 address space, a data transfer length and a transaction code. The 
ASYNDataRequest routine then generates one or more IEEE 1394 transactions 
to satisfy the request. When the API finishes the requested data transfer 
operation, or if it encounters an error, the API returns to the 
application or calls the application's callback routine, depending on 
whether the application called this routine synchronously or 
asynchronously. 
In order to perform a lock transaction over the IEEE 1394 serial bus, the 
application calls the ASYNDataRequest routine and passes an argument 
value, a data value, and a lock operation code. The API generates the 
requested lock operation and returns to the application or calls the 
application's callback routine, as determined by the type of call, e.g., 
synchronously or asynchronously. 
After initializing the API, the application may source or sink a channel of 
isochronous data on the IEEE 1394 serial bus. Before transferring 
isochronous data, the application must first open an isochronous port 
using the ISOCHOpen routine. When calling this routine, the application 
specifies the direction and other information about the stream of 
isochronous data that the application intends to transfer. The ISOCHOpen 
routine determines if the necessary system resources are available then 
returns to the application. When this routine completes successfully, the 
application then has all necessary system resources reserved for its 
exclusive use to transfer a stream of isochronous data. 
When an application talks or listens on an isochronous channel, the source 
or destination of the isochronous data in the host system is one or more 
data buffers owned by the application and described in a data structure. 
The application passes these buffers to the API by calling the ISOCHAttach 
routine. This routine "attaches" the application buffers to the 
isochronous stream in preparation for transferring application data into 
or out of these buffers. If the application wishes to reclaim its buffers 
before the API has finished with them, the application may call the 
ISOCHDetach routine, specifying those buffers that the application wishes 
to reclaim. 
The API defined buffer descriptor which the application uses to describe 
its isochronous data buffers permits the application to specify one, more 
than one, or a list of data buffers to use for receiving or transmitting 
isochronous data. Each buffer may be contiguous or fragmented, logical or 
physical and the application may specify callback routines on a buffer by 
buffer basis. This permits extremely flexible buffer handling in the API 
on behalf of the application, thereby supporting a wide range of 
application requirements. 
When the application has opened an isochronous port and has attached 
buffers to this port, then the application may control its stream of 
isochronous data. It does this by calling the ISOCHControl routine. This 
routine permits the application to start or stop an isochronous stream 
into or out of the application buffers. When calling this routine, the 
application may specify an event on which to start or stop the stream, 
e.g., immediately, on a particular isochronous cycle or other event. When 
the application is finished transferring a stream of isochronous data, it 
releases the system resources associated with the open port by calling the 
ISOCHClose routine. 
The ActivateSonyAPI and DeactivateSonyApi routines provide the 
initialization mechanism which makes the IEEE 1394 specific services 
provided by the API available to the calling application. The 
ActivateSonyAPI routine establishes a connection to the services provided 
by the API. The DeactivateSonyAPI routine removes the specified connection 
to the services provided by the API. The result of an activation is a 
valid activateReq structure. The calling application passes a pointer to 
this structure as part of all subsequent calls to the API. As part of 
activating the API for an application, the application may provide 
indication routines which the API uses to inform the caller that something 
has happened on the associated IEEE 1394 bus, such as a bus reset or 
request indication from a remote node. The result of deactivation is that 
the indication routines, if any, which were registered at activation time 
are de-registered. Following deactivation, the caller may not use any of 
the API services, unless the API is first reactivated. 
The following function activates the API for further operations: 
STATUS ActivateSonyAPI(ActivateReqPtr activateReq); 
This routine takes one parameter and returns a status value. The caller 
fills in the activateReq data structure, as defined below, and passes a 
pointer to the ActivateSonyAPI routine. After this routine returns with a 
GOOD status, the caller saves the resulting activateReq data structure. 
This data structure represents the connection between the application and 
the API. In order to identify this connection, the caller passes a pointer 
to the activateReq data structure on subsequent calls to the API. The 
possible status return values are GOOD, signalling that the API is now 
activated and the activateReq data structure is valid to use for further 
operations, PENDING, signalling that the API has accepted the request, but 
is not active at this time, and UNDEFINEDERROR, signalling that an 
unexpected error was encountered while attempting to activate the API and 
that the API is not activated. After a PENDING value is returned, the API 
calls the AsyncCompletion routine when the activation request is complete. 
At that time the request status field will contain the completion status 
for the activate request. 
The single parameter contains the address of an activatReq data structure. 
This data structure provides information necessary to activate the API, as 
defined in Table I below: 
TABLE I 
__________________________________________________________________________ 
typedef struct ActivateReq { 
void (*BusResetHandler)(BusResetPtr); 
/* Bus Reset Handler */ 
STATUS (*IndicationHandler)(IndicationPtr); 
/* Indication Handler */ 
void *RefPtr; / * for use by above routines * / 
void *SonyApIPrivate; /* the cookie */ 
void (*AsyncCompletion)(struct ActivateReq *req); 
/* completion routine */ 
void *UserPtr; /* for use by completion routine*/ 
STATUS Status; /* completion status */ 
} ActivateReq, *ActivateReqPtr; 
__________________________________________________________________________ 
When the BusResetHandler filed is not equal to null, it contains the 
address of the routine to call upon receiving a bus reset event. When a 
bus reset occurs on the IEEE 1394 bus, the API calls the BusResetHandler 
routine, passing the address of a data structure containing bus reset 
information. When the IndicationHandler field is not equal to null, it 
contains the address of the routine to call upon the occurrence of an 
indication that is not handled by the API. When the API receives a request 
subaction from a remote node, it calls the IndicationHandler routine, 
passing the address of a data structure which describes the request. The 
API fills in the SonyAPIPrivate field as part of the activation process. 
The API uses the value in this field on subsequent calls. The calling 
application shall not modify the value in this field. When the 
AsyncCompletion field is not equal to null, it contains the address of the 
routine to call when the API is active and available for use by the 
invoking application. Note that the calling application may specify a 
completion routine whether the request is asynchronous or synchronous. The 
UserPtr field is available for use by the calling application's completion 
routine. The API does not modify this field. The Status field contains the 
status of the activation request. 
The following function terminates the instantiation of the API represented 
by request: 
status DeactivateSonyAPI(ActivateReqPtr request); 
The possible status return values for this function are GOOD, signalling 
that the API is now deactivated and the activateReq data structure is 
invalid to use for further operations, INVALIDCONNECTION, PENDING, 
signalling that the API has accepted the deactivate request, but is still 
active at this time, and UNDEFINEDERROR, signalling that an unexpected 
error was encountered while attempting to deactivate the API and that the 
API may be active. After a PENDING value is returned, the API calls the 
AsyncCompletion routine when the deactivation request is complete. At that 
time, the request status field will contain the completion status for the 
activate request. 
The single parameter contains the address of the activateReq data structure 
used to activate the API previously. The section above defines this data 
structure and describes its fields. Note that when deactivating the caller 
must use the same data structure that was used to activate the API 
previously. The caller may modify the values in the AsyncCompletion field 
and the UserPtr field. The caller should not modify any other field in the 
activateReq data structure following the initial call to the 
ActivateSonyAPI routine and prior to the call to the DeactivateSonyAPI 
routine. In addition to deactivating the API for a specific application, 
this routine also releases any indication buffers that the application 
previously passed to the API. If there are outstanding indication buffers 
owned by the application and the application attempts to call this routine 
synchronously, this routine will return an error. If this happens, the 
application may call this routine again specifying a completion routine. 
The API will complete the deactivate request and call the application's 
indication routine when all of the application's indication buffers have 
been released. 
The API calls the indication handling routines, BusResetHandler and 
IndicationHandler, asynchronously, and they may have limited system 
services available to them. Depending on the environment and possibly some 
other circumstances, the API may call these routines at interrupt level. 
In the BusResetHandler routine, the handler is passed a pointer to bus 
reset information. In the IndicationHandler routine, the handler is passed 
a pointer to indication information. The application passes the address of 
one or both of these indication routines to the API at the time that it 
activates the API. The application may provide either one of these 
handlers, both handlers or no handler routines at all. 
The bus reset handling routine has the following calling convention: 
void BusResetHandler(BusResetBlockPtr busResetBlock); 
The busResetBlock data structure contains the address of a data structure 
which describes the bus reset event, as defined in Table II below. 
TABLE II 
______________________________________ 
typedef struct { 
ActivatereqPtr 
activateReq; 
/* the session */ 
QUADLET generation; 
/* bus generation */ 
QUADLET numNodes; /* number of nodes on the bus */ 
TopologyMapPtr 
topology; /* bus topology */ 
. . . other? 
} BusResetBlock, *BusResetBlockPtr; 
______________________________________ 
The API calls the bus reset handling routine any time that a bus reset 
occurs on the IEEE 1394 bus while the API is active for the application 
that provided the bus reset handler routine. When a cluster of resets 
occurs due to the physical nature of bus connection and disconnection, the 
handler will be called once. The handler will not be re-entered, but may 
be called several times in succession. As the result of the bus reset, all 
asynchronous transactions which were pending at the time of the bus reset 
will be completed with an error status. Isochronous traffic will resume 
per the IEEE 1394 specification, and may produce indications during the 
execution of the bus reset handler. 
The asynchronous transaction request indication routine has the following 
calling convention: 
void IndicationHandler(IndicationBlockPtr indicationBlockPtr) 
The IndicationBlockPtr data structure contains the address of an indication 
block, defined in Table III below. 
TABLE III 
______________________________________ 
typedef struct { 
ActivateReqPtr 
activateReq; 
/* the session */ 
LocalBufferPtr 
indicationBuf; 
/* the info */ 
} IndicationBlock, *IndicationBlockPtr; 
______________________________________ 
The API calls the indication routine when it receives an asynchronous 
request subaction that is not handled by either the API itself, or by the 
IEEE 1394 interface hardware. For each such event, the API calls the 
indication routine of each application, beginning with the first 
application to activate the API and provide an indication handler. Each 
indication handler returns a value to the API to indicate whether or not 
it handled the indication. When the API receives a status from an 
indication routine indicating that it handled the indication, then the API 
does not call any other indication routines for this indication. 
The API does handle some request subactions itself. For these transactions, 
the API does not call any indication handler routine. The API passes all 
IEEE 1394 transaction information that caused the indication and the 
additional information necessary for the indication handler routine to 
generate a response subaction through the API. 
The application may contribute buffers to the Indication Handler. This 
facility allows the application to expand the default set of indication 
buffers in order to accommodate application specific requirements. A 
larger set of indication buffers allows more outstanding indications 
without causing a busy ack signal at the IEEE 1394 interface. The 
application is not guaranteed to receive a buffer belonging to it when it 
receives an indication from the API. Furthermore, the API may pass an 
application indication buffer to another application, if necessary, when 
reporting an indication. 
The Current Indication Buffer Count function returns the total count of 
indication buffers in the indication buffer pool. The returned value is 
the current count of indication buffers. 
The Add Indication Buffers function contributes buffers to the indication 
buffer pool. Buffer elements are described as a LocalBuffer. The caller of 
this function cedes ownership of the storage represented by this request 
to the API and must regain ownership prior to disposing of the storage. 
STATUS AddIndBuffers(ActivateReqPtr context, BufMgmtBlockPtr bufBlock); 
The possible status return values for an AddIndBuffers function are GOOD, 
signalling that the API has accepted the request and will complete it at a 
later time, INVALIDCONNECTION, PENDING, signalling that the API has 
accepted the request, UNSUPPORTEDOP, signalling that the buffers cannot be 
added on this platform, and UNDEFINEDERROR, signalling that an unexpected 
error was encountered while attempting to honor the request, even though 
some data may have been transferred. When a pending value is returned the 
API calls the AsyncCompletion completion routine when the request is 
complete. At that time, the status field of the BufMgmtBlock will contain 
the completion status for the request. 
The first parameter of an AddIndBuffers function contains the address of a 
valid ActivateReq data structure. The second parameter contains the 
address of a BufMgmtBlock data structure. This data structure describes 
the buffers, as defined in Table IV below. 
TABLE IV 
______________________________________ 
typedef struct BufMgmtBlock { 
BMIdata APIprivate; 
/* API private */ 
LocalBufferPtr buffs; 
/* the buffers to contribute */ 
void (*AsyncCompletion) (struct BufMgmtBlock *req); 
/*completion routine*/ 
void *UserPtr; /*for use by the completion routine*/ 
STATUS Status; /*completion status for operation*/ 
} BufMgmtBlock, *BufMgmtBlockPtr; 
______________________________________ 
The APIprivate field includes private data for management of the request. 
The LocalBufferPtr field contains descriptors for the buffer(s) to 
contribute. These buffers can be of any size. The API may use none, part 
or all of the contributed buffers at its discretion. When the 
AsyncCompletion field is not equal to null, it contains the address of the 
routine to call upon completing the operation. The UserPtr field is 
available for use by the calling completion routine. The API does not 
modify this field. The Status field contains the status of the requested 
data transfer operation. The Status field contains status "pending" until 
the asynchronous operation is completed. When the completion routine is 
invoked, the Status field will contain completion status. 
The Release Indication Buffers function returns previously added indication 
buffers to the invoker. Buffer elements are described as a LocalBuffer. 
The invoker of this function may specify a subset of the buffers added by 
an AddIndBuffers function request. When all of the requested buffers are 
released, the completion routine is invoked. 
STATUS RelIndBuffers(ActivateReqPtr context, BufMgmtBlockPtr bufblock); 
The possible status return values for a RelIndBuffers function are PENDING, 
signalling that the API has accepted the request and will complete it at a 
later time, INVALIDCONNECTION, UNSUPPORTEDOP, signalling that buffers 
cannot be added on this platform, and UNDEFINEDERROR, signalling that an 
unexpected error was encountered while attempting to honor the request, 
even though some data may have been transferred. 
The first parameter of a Release Indication Buffer contains the address of 
a valid activateReq data structure. The second parameter contains the 
address of a BufMgmtPtr data structure. This data structure describes the 
buffers, as defined above. When the application requests the API to 
release a buffer, it must describe that buffer using the same description 
as when the buffer was first given to the API. 
The Bus Management routines perform IEEE 1394 bus management functions. 
These functions include allocating and deallocating isochronous bus 
resources and retrieving information about the topology or configuration 
of the IEEE 1394 bus. 
The MGMTAllocateChannel routine uses the protocols defined in section 8 of 
the IEEE 1394 standard to allocate a single isochronous channel number. 
The MGMTAllocateChannel routine calling convention is as follows: 
status MGMTAllocatChannel (ActivateReqPtr context, MGMTAllocateChBlockPTr 
allocateChBlock); 
The possible status return values for a MGMTAllocateChannel routine are 
GOOD, signalling that the channel was successfully allocated, 
INVALIDCONNECTION, signalling that the context parameter does not contain 
the address of a currently active connection to the API, PENDING, 
signalling that the API has accepted the request, CHUNAVAILABLE, 
signalling that the requested channel number is currently not available, 
and UNDEFINEDERROR, signalling that an unexpected error was encountered. 
If a pending value was returned the API calls the MGMTCompletion routine 
when the allocation request is complete and at that time, the status field 
will contain the completion status for this request. 
The first calling parameter of a MGMTAllocateChannel routine is the address 
of an active ActivateReq data structure. The second parameter contains the 
address of a data structure as defined in Table V below. 
TABLE V 
__________________________________________________________________________ 
typedef struct MGMTAllocateChBlock { 
QUADLET channel; 
/* channel number to allocate, or all ones */ 
QUADLET allocateCh; 
/* actual channel number allocated*/ 
OCTLET chAvailable; 
/* bit mask of available channel numbers */ 
void (*MGMTCompletion) (struct MGMTAllocateChBlock *req); 
/* client completion routine */ 
void *UserPtr; 
/ *for use by the completion routine */ 
STATUS Status; 
/ *comptetion status */ 
} MGMTAllocateChBlock, *MGMTAllocateChBlockPtr 
__________________________________________________________________________ 
The channel field contains the channel number to allocate. If the channel 
number is in the range of 0 to 63, inclusive, then the routine attempts to 
allocate the specified channel number. If the channel number is equal to 
all ones, then the routine chooses a channel number to allocate. If the 
channel field contains any other value, then the routine fills in the 
chAvailable field and returns the chUnavailable status. Note that this can 
be used to determine the current value of the channels available bit mask 
from the currently active Isochronous Resource Manager. The allocatedCh 
field is filled with the actual allocated channel number, or all ones if a 
channel was not allocated as a result of calling this routine. The 
chAvailable field is filled with the current value of the channels.sub.-- 
available CSR at the Isochronous Resource Manager. Note that the value in 
the CSR may change at any time, so the value in this field is only a 
snapshot and may be different on subsequent calls. If the value in the 
MGMTCompletion field is not equal to NULL, then this field contains the 
address of the routine to call upon completion. The UserPtr field is 
available for use by the application's completion routine. The API does 
not modify this field. The Status field contains the completion status for 
this call. If the application calls this routine asynchronously, this 
field contains PENDING status until the completion routine is called. 
The MGMTAllocateBandwidth routine uses the protocols defined in section 8 
of the IEEE 1394 standard to allocate isochronous bandwidth. The 
MGMTAllocateBandwidth routine's calling convention is as follows: 
status MGMTAllocateBandwidth (ActivateReqPtr context, 
MGMTAllocateChBlockPtr allocateChBlock); 
The possible status return values of the MGMTAllocateBandwidth routine are 
GOOD, signalling that the bandwidth was successfully allocated, 
INVALIDCONNECTION, signalling that the context parameter does not contain 
the address of a currently active connection to the API, PENDING, 
signalling that the API has accepted the request, BWUNAVAILABLE, 
signalling that the requested bandwidth is currently not available, and 
UNDEFINEDERROR, signalling that an unexpected error was encountered. If a 
pending value was returned the API calls the MGMTCompletion routine when 
the allocation request is complete and at that time, the status field will 
contain the completion status for this request. 
The first calling parameter of a MGMTAllocateBandwidth routine is the 
address of an active ActivateReq data structure. The second parameter 
contains the address of a data structure as defined in Table VI below. 
TABLE VI 
__________________________________________________________________________ 
typedef struct MGMTAllocateBWBlock { 
QUADLET bandwidth; 
/*bandwidth to allocate, or all ones*/ 
QUADLET bwAvailable /*actual value of BWAvailable register in IRM*/ 
void (*MGMTCompletion) (struct MGMTAllocateBWBlock *req); 
/*client completion routine*/ 
void *UserPtr; 
/*for use by the completion routine*/ 
STATUS Status; 
/*completion status*/ 
} MGMTAllocateBWBlock, *MGMTAllocateBWBlockPtr; 
__________________________________________________________________________ 
The bandwidth field contains the amount of bandwidth to allocate. If this 
number is equal to all ones, then the routine fills in the bwAvailable 
field and returns the BWUNAVAILABLE status. Note that this can be used to 
determine the current value of the bwavailable field from the currently 
active Isochronous Resource Manager. The bwAvailable field is filled with 
the current value of the bandwidth/available CSR at the Isochronous 
Resource Manager. Note that the value in the CSR may change at any time, 
so the value in this field is only a snapshot and may be different on 
subsequent calls. If the value in the MGMTCompletion field is not equal to 
NULL, then it contains the address of the routine to call upon completion. 
The UserPtr field is available for use by the application's completion 
routine. The API does not modify this field. The Status field contains the 
completion status for this call. If the application calls this routine 
asynchronously, this field contains PENDING status until the completion 
routine is called. 
The MGMTDeAllocateChannel routine uses the protocols defined in section 8 
of the IEEE 1394 standard to deallocate a single isochronous channel 
number. The MGMTDeAllocateChannel routine's calling convention is as 
follows: 
status MGMTDeAllocateChannel (ActivateReqPtr context, 
MGMTAllocateChBlockPtr allocateChBlock); 
The routine takes two parameters and returns a status value. The possible 
status return values for the MGMTDeAllocateChannel are GOOD, signalling 
that the channel was successfully deallocated, INVALIDCONNECTION, 
signalling that the context parameter does not contain the address of a 
currently active connection to the API, PENDING, signalling that the API 
has accepted the request, CHUNAVAILABLE, signalling that the requested 
channel number was not allocated, and UNDEFINEDERROR, signalling that an 
unexpected error was encountered. If a pending value was returned the API 
calls the MGMTCompletion routine when the allocation request is complete 
and at that time, the status field will contain the completion status for 
this request. 
The first calling parameter of a MGMTDeAllocateChannel routine is the 
address of an active ActivateReq data structure. The second parameter 
contains the address of a MGMTAllocateChBlock data structure. This routine 
deallocates the channel specified in the channel field of that data 
structure and fills in the chAvailable field with the current value of the 
channels.sub.-- available bit mask from the currently active isochronous 
resource manager. 
The MGMTDeAllocateBandwidth routine uses the protocols defined in section 8 
of the IEEE 1394 standard to deallocate isochronous bandwidth. The 
MGMTDeAllocateBandwidth routine's calling convention is as follows: 
status MGMTDeAllocateBandwidth (ActivateReqPtr context, 
MGMTAllocateChBlockPtr allocateChBlock); 
The routine takes two parameters and returns a status value. The possible 
status return values for a MGMTDeAllocateBandwidth routine are GOOD, 
signalling that the bandwidth was successfully deallocated, 
INVALIDCONNECTION, signalling that the context parameter does not contain 
the address of a currently active connection to the API, PENDING, 
signalling that the API has accepted the request, BWUNAVAILABLE, 
signalling that completing this request would cause the bandwidth.sub.-- 
available register in the isochronous resource manager to become invalid 
and no action was taken, and UNDEFINEDERROR, signalling that an unexpected 
error was encountered. If a pending value was returned the API calls the 
MGMTCompletion routine when the allocation request is complete and at that 
time, the status field will contain the completion status for this 
request. 
The first calling parameter of a MGMTDeAllocateBandwidth routine is the 
address of an active ActivateReq data structure. The second parameter 
contains the address of a MGMTAllocateBWBlock data structure. This routine 
deallocates the bandwidth contained in the bandwidth field and fills in 
the bwAvailable field with the current value of the bandwidth.sub.-- 
available register in the currently active isochronous resource manager. 
The MGMTBusInfo routine returns information about the node on which the 
application is running and the connected IEEE 1394 bus. Such information 
includes the current setting of the PHY gap count, the number of nodes on 
the connected IEEE 1394 bus, a pointer to the bus topology map and a 
pointer to the bus speed map, as defined in the IEEE 1394 standard. 
The ASYNDataRequest routine generates one or more IEEE 1394 asynchronous 
read or write transactions in order to transfer data between the 
application's data buffer and a linear range of addresses in the 64 bit 
IEEE 1394 address space. The ASYNDataRequest routine has the following 
calling convention: 
STATUS ASYNDataRequest (ActivateReqPtr request, asyncTransportPtr 
xfrBlock); 
The possible status return values for an ASYNDataRequest routine are GOOD, 
signalling that the API has successfully completed the data transfer 
request, PENDING, signalling that the API has accepted the request and 
will complete it at a later time, INVALIDOPCODE, signalling that there is 
an unknown code in the flags.opCode field, INVALIDCONNECTION, signalling 
that the activateReqPtr field does not represent an active connection, and 
UNDEFINEDERROR, signalling that an unexpected error was encountered while 
attempting to honor the request even though some data may have been 
transferred. 
The first parameter of an ASYNDataRequest routine contains the address of a 
valid activateReq data structure. The second parameter contains the 
address of an asyncTransport data structure. This data structure describes 
the requested data transfer operation, as defined in Table VII below. 
TABLE VII 
__________________________________________________________________________ 
typedef struct AsyncTransport { 
ASYdata APIprivate; 
/* API private */ 
OPTION OPCode :4; 
/*defines the operation to perform*/ 
OPTION BusSpeed 
:4; 
/*bus speed to use for xfr*/ 
OPTION NonIncr :1; 
/*do not increment remote addr*/ 
BUFSIZE 
BlockSize /*for block read or write requests - 
size to use for all block requests 
0 means use max for bus speed*/ 
LocalBuffer ApplBufPtr; 
/*buf descr for application data*/ 
RemoteAddr RemoteBufPtr; 
/*64 bit address on IEEE 1394 bus*/ 
BUFSIZE 
Length; /*number of bytes to transfer*/ 
void (*ASyncCompletion) (struct AsyncTransport* req); /*cmpl routine*/ 
void *UserPtr; /*for use by the completion routine*/ 
STATUS Status; /*completion status for operation*/ 
} AsyncTransport, *AsyncTransportPtr; 
enum OpCodes { 
/*asynch data transfer operations*/ 
BLOCKWRITE, /*transfer data using block write requests*/ 
BLOCKREAD, /*transfer data using block read requests*/ 
QUADLETWRITE, /*transfer data using QUADLET write transactions*/ 
QUADLETREAD, /*transfer data using QUADLET read transactions*/ 
/* lock transactions*/ 
MASKSWAP, /*mask swap lock operation*/ 
COMESWAP, 
/*compare swap lock operation*/ 
FETCHADD, /*fetch and add lock operation*/ 
LITTLEADD, /*little endian fetch/add lock operation*/ 
BOUNDEDADD, /*bounded add lock operation*/ 
WRAPADD /*wrap add lock operation*/ 
}; 
__________________________________________________________________________ 
The ASYdata field includes private data for management of the request. The 
OpCode field contains a code describing the requested operation which must 
be one of the values defined in the asyncOpCodes enum. The NonIncr field 
when set to one, instructs the routine to transfer all data to the same 
IEEE 1394 address contained in the remoteBufPtr field and when set to 
zero, instructs the routine to transfer data to an incrementing range of 
IEEE 1394 addresses, beginning with the address contained in the 
remoteBufPtr field. The BlockSize field contains the maximum size, in 
bytes, to use for all block read or write request subactions. A value of 
zero means to use the maximum request size for the chosen bus speed. The 
APPLBufPtr field contains the descriptor for the application data buffer. 
The RemoteBufPtr field contains the 64 bit address of the data buffer in a 
remote IEEE 1394 node. The Length field contains the number of bytes to 
transfer which may be less than or equal to the length of the application 
data buffer. When the AsyncCompletion field is not equal to null, it 
contains the address of the routine to call upon completing the data 
transfer. The UserPtr field is available for use by the calling 
application's completion routine and is not modified by the API. The 
Status field contains the status of the requested data transfer operation. 
This field contains status "pending" until the asynchronous operation is 
complete. When the completion routine is invoked, this field will contain 
completion status. 
The ASYNLockRequest routine generates one lock transaction on the IEEE 1394 
bus. The ASYNLockRequest routine has the following calling convention: 
STATUS ASYNLockRequest (ActivateReqPtr request, AsyncLockBlockPtr 
lockBlock); 
The possible status return values for an ASYNLockRequest routine are GOOD, 
signalling that the API has successfully performed the lock transaction 
and the results are contained in the AsyncLockBlock, PENDING, signalling 
that the API has accepted the request and will complete it at a later 
time, INVALIDOPCODE, signalling that there is an unknown code in the 
OpCode field of the AsyncLockBlock data structure, INVALIDCONNECTION, 
signalling that the activateReqPtr field does not represent an active 
connection, and UNDEFINEDERROR, signalling that an unexpected error was 
encountered while attempting to honor the request even though some data 
may have been transferred. 
The first parameter of an ASYNLockRequest routine contains the address of a 
valid activateReq data structure. The second parameter contains the 
address of an AsyncLockBlock data structure. This data structure describes 
the requested data transfer operation, as defined in Table VIII below. 
TABLE VIII 
__________________________________________________________________________ 
typedef struct AsyncLockBlock { 
ASYdata APIprivate; 
/* API private */ 
OPTION OPCode 
:4; 
/*define, the operation to perform*/ 
OPTION BusSpeed 
:4; 
/*bus speed to use for xfr*/ 
struct { 
union { 
QUADLET Arg32; 
OCTLET Arg64; 
} arg; /* 32 or 64 bit lock argument */ 
union { 
QUADLET Data32; 
OCTLET Data64; 
} data; /* 32 or 64 bit lock data */ 
} ArgData; 
RemoteAddr remoteBuffPtr; 
/*64 bit address on IEEE 1394 bus*/ 
void (*AsyncCompletion) (struct AsyncLockBlock *req); 
/*completion routine*/ 
void *UserPtr; /*for use by the completion routine*/ 
STATUS Status; /*completion status for operation*/ 
} AsyncLockBlock, *AsyncLockBlockPtr; 
__________________________________________________________________________ 
The APIPrivate field contains private data for management of the request. 
The OpCode field contains a code describing the requested operation and 
must contain one of the values defined in the asyncOpCodes enum. The 
ArgData struct field contains the argument and data for this lock 
transaction. The remoteBufPtr field contains the 64 bit destination 
address on the IEEE 1394 bus. When the AsyncCompletion field is not equal 
to null, it contains the address of the routine to call upon completing 
the lock transaction. The UserPtr field is available for use by the 
calling application's completion routine and is not modified by the API. 
The Status field contains the status of the requested data transfer 
operation. This field contains status "pending" until the asynchronous 
operation is complete. When the completion routine is invoked, this field 
will contain completion status. 
The Isochronous Resource Management routines allocate and deallocate system 
resources needed to transfer isochronous data over the IEEE 1394 interface 
into or out of application data buffers. Allocation and deallocation is 
necessary to avoid conflicts among multiple potential applications of 
isochronous data in the system. Whenever isochronous data flows over the 
IEEE 1394 bus, there is an entity on the IEEE 1394 bus which owns the 
necessary bus resources, namely channel numbers and bandwidth. Each 
application which uses isochronous data has its own set of rules for who 
must allocate and deallocate these resources and when. The bus management 
routines in the API permit an application to allocate these resources 
according to the requirements of the IEEE 1394 standard. Note that the 
routines in this section do not allocate IEEE 1394 bus resources; these 
routines only allocate system level resources necessary to transfer 
isochronous data into or out of application data buffers. These resources 
include a DMA channel and the system resources to sustain it, such as the 
low level interrupt handler and dispatcher. 
The ISOCHOpen routine opens and initializes an isochronous port. An 
isochronous port is a collection of hardware and software resources in the 
local node on which the application of the API and the API are running. 
This collection of resources constitutes everything in the local node 
which is needed to transfer a single stream of isochronous data into or 
out of the node. This collection of resources does not include the IEEE 
1394 bus resources which the application must allocate separately, 
according to the bus management rules defined in section 8 of the IEEE 
1394 standard, and the governing application rules and requirements. The 
routines which enable an application of the API to allocate and deallocate 
IEEE 1394 bus resources have been described above. 
The port open routine has the following calling convention: 
status ISOCHOpen (ActivateReqPtr connectionPtr, ISOCHOpenBlockPtr 
openBlock); 
The first parameter of the port open routine contains the address of a 
valid activateReq data structure. The second parameter contains the 
address of an ISOCHOpenBlock data structure. Upon successful completion of 
this routine, the application uses this ISOCHOpenBlock data structure to 
reference this opened isochronous port on future calls to the API which 
affect this port. 
The possible status return values for a port open routine are GOOD, 
signalling that an open request was completed successfully, PENDING, 
signalling that the API has accepted the request and will complete it at a 
later time, NORESOURCES, signalling that an isochronous port or other 
necessary resource is not currently available and the request is denied, 
INVALIDREQUEST, signalling that the requested bus speed is not supported, 
INVALIDCONNECTION, signalling that the ActivateReqPtr field does not 
represent an active API connection, and UNDEFINEDERROR, signalling that 
the request could not be honored, but the error could not be identified. 
The calling parameter of a port open routine contains the address of an 
ISOCHOpenBlock data structure. This data structure describes the request, 
as defined in Table IX below. 
TABLE IX 
__________________________________________________________________________ 
typedef struct { 
ISOlink APIprivate; 
/* API private */ 
OPTION Direction 
:2; 
/*source/sink*/ 
OPTION BusSpeed 
:4; 
/*requested bus speed*/ 
void (*AsyncCompletion))struct ISOCHOpenBlock* req); /*compl routine*/ 
void *UserPtr; /*for use by the completion routine*/ 
STATUS Status; /*completion status for operation*/ 
} ISOCHOpenBlock, *ISOCHOpenBlockPtr; 
enum Direction { 
INPUT, /*specifies input to application to data buffer*/ 
OUTPUT /*specifies output from application data buffer*/ 
}; 
__________________________________________________________________________ 
The direction field indicates the direction of the isochronous data 
transfer. When the AsyncCompletion field is not equal to null, it contains 
the address of the routine to call upon completion. The UserPtr field is 
available for use by the calling application's completion routine and is 
not modified by the API. The Status field contains the status of the 
requested data transfer operation. This field contains status "pending" 
until the asynchronous data transfer operation is complete. When the 
completion routine is invoked, this field will contain completion status. 
When the application is finished with the isochronous port, it passes the 
isochPortPtr to the ISOCHClose routine. 
The ISOCHClose routine closes an isochronous port that was previously 
opened using the ISOCHOpen routine. This routine has the following calling 
convention: 
STATUS ISOCHClose (ActivateReqPtr connectionPtr, ISOCHOpenBlockPtr 
openBlock); 
This routine takes a single parameter and returns a status value. This 
routine executes asynchronously, and invokes the completion routine 
defined in the ISOCHOpenBlock upon completion. The possible status return 
values of an ISOCHClose routine are GOOD, signalling that the operation 
was completed successfully, PENDING, signalling that the API has accepted 
the request and will complete it at a later time, INVALIDCONNECTION, 
signalling that the connectionPtr does not represent an active API 
connection or openBlock does not represent a currently open isochronous 
port, and UNDEFINEDERROR, signalling that the request could not be 
honored, but the error could not be identified. 
The first calling parameter of ISOCHClose routine is the address of a valid 
activateReq data structure. The second calling parameter is the address of 
the ISOCHOpenBlock used to open the port with the ISOCHOpen routine. 
The isochronous data control routine controls a stream of isochronous data 
into or out of application data buffers. For applications which listen to 
isochronous data, these control routines only affect the flow of 
isochronous data into the system; they do not affect the isochronous data 
on the IEEE 1394 bus itself. For applications that transmit isochronous 
data from application data buffers, these control routines also affect the 
flow of isochronous data on the IEEE 1394 bus. 
The ISOCHControl routine has the following calling convention: 
STATUS ISOCHControl (ISOCHOpenBlockPtr opensBlockPtr, ISOCHCtlBlockPtr 
ctlReqPtr); 
The possible status return values of an ISOCHControl routine are GOOD, 
signalling that the operation was completed successfully, 
INVALIDCONNECTION, signalling that the openBlock field does not represent 
an active isochronous port, PENDING, signalling that the operation is 
currently pending, INVALIDOPCODE, signalling that the opCode field of the 
ISOCHControlBlock contained an illegal value, UNSUPPORTEDOP, signalling 
that the operation is not supported due to a limitation of the IEEE 1394 
interface hardware or a limitation of the software or operating 
environment, and UNDEFINEDERROR, signalling that the operation could not 
be performed, but the error could not be identified. If a pending value is 
returned, at the time the callback routine is called, the status field in 
the ISOCHControlBlock will contain the completion status of the control 
request. 
The first parameter of an ISOCHControl routine contains the address of a 
valid ISOCHOpenBlock data structure. The second parameter contains the 
address of an ISOCHCtlBlock data structure. This data structure describes 
the requested control operation, as defined in Table X below. 
TABLE X 
__________________________________________________________________________ 
typedef struct ISOCHCtlBlock { 
ISOlink 
ApIPrivate; 
/* API private */ 
OPTION IsoOpCode 
:4; 
/*operation to perform*/ 
OPTION IsoEvent 
:4, 
/*trigger event for start/stop*/ 
OPTION Sy :4; 
/*sy field value, if needed*/ 
OPTION Tag :2; 
/*tag value to use when starting*/ 
OPTION Channel 
:6; 
/*channel value to use when starting*/ 
BusTime 
Time; /*specifies when an event should occur*/ 
void (*AsyncCompletion)(struct ISOCHCtlBlock *req); 
/*completion routine*/ 
void *UserPtr; /*for use by the completion routine*/ 
STATUS Status /*completion status for operation*/ 
} ISOCHCtlBlock, *ISOCHCtlBlockPtr; 
__________________________________________________________________________ 
The APIPrivate field contains private storage used by the API to manage 
this request. The IsoOpCode field contains a value from the IsoOpCode enum 
which describes the requested control operation. The IsoEvent field 
specifies the trigger event on which to perform the requested operation. 
If the IsoEvent field contains the value "SYFIELD," the Sy field contains 
the value in the sy field that will cause the isochronous channel to start 
or stop. If the IsoOpCode field contains the value "START," the value from 
the Tag field is used for the tag value in the isochronous data block 
packet header. If the IsoOpCode field contains the value "START," the 
value from the Channel field is used for the channel value in the 
isochronous data block packet header. If the IsoEvent field contains the 
value "TIME," the Time field contains the bus time on which the requested 
action is to take place. When the AysncCompletion field is not equal to 
null, it contains the address of the routine to call upon completion of 
the data transfer. The UserPtr field is available for use by the calling 
application's completion routine. The API does not modify this field. The 
Status field contains the status of the requested data transfer operation. 
This field contains status "pending" until the asynchronous data transfer 
operation is complete. When the completion routine is invoked, this field 
will contain completion status. 
The isochronous attach routine passes application data buffer descriptors 
to the API software. The application may call this routine at any time to 
make buffers available to the IEEE 1394 interface hardware and the 
associated low layers of software. The calling convention for this routine 
is as follows: 
status ISOCHAttach(ISOCHOpenBlockPtr openBlock, ISOCHAppendBlockPtr 
append); 
The possible status return values for an isochronous attach routine are 
GOOD, signalling that the operation was completed and the application data 
buffers are accepted, INVALIDCONNECTION, signalling that the openBlock 
field does not represent an active isochronous port, UNSUPPORTEDOP, 
signalling that the resynchronization event specified in a buffer 
descriptor is not supported which may be due to hardware implementation, 
software implementation or other system environment limitation, 
INVALIDREQUEST, signalling that an attempt to append a circular list of 
application data buffers while isochronous data is flowing, or to append 
new buffers to an existing circular list while isochronous data is 
flowing, and UNDEFINEDERROR, signalling that the operation could not be 
completed, but an actual error could not be identified. 
The first parameter of an ISOCHAttach routine contains the address of a 
valid ISOCHOpenBlock data structure. The second parameter contains the 
address of an ISOCHAppendBlock data structure. This data structure 
describes the application data buffer list as defined in Table XI below. 
TABLE XI 
__________________________________________________________________________ 
typedef struct ISOCHAppendBlock { 
ISOlink APIPrivate; 
/* API private */ 
isochBufferPtr 
IsochBuffList; 
/*start of list of isoch buffers*/ 
void (*AsyncCompletion) (struct ISOCHAppendBlock *req); 
/*completion routine*/ 
void *UserPtr; /*for use by the completion routine*/ 
STATUS status; /*compietion status for operation*/ 
} ISOCHAppendBlock, *ISOCHAppendBlockPtr; 
__________________________________________________________________________ 
The APIPrivate field contains private storage used by the API to manage the 
request. The IsochBuffList field contains the address of the first 
isochronous buffer of a list to append to the specified port. If the 
current buffer list or the buffer list to append is circular then the 
operation can only be performed when the port is stopped and the append 
operation will replace any previously appended buffers. A non-circular 
list of buffers may be appended to an existing non-circular list of 
buffers at any time. When the AsyncCompletion field is not equal to null, 
it contains the address of the routine to call upon completion. The 
UserPtr field is available for use by the calling application's completion 
routine and is not modified by the API. The Status field contains the 
status of the requested operation. This field contains status "PENDING" 
until the asynchronous data operation is complete. When the completion 
routine is invoked, this field will contain completion status. 
The IsochBuffList field contains the address of an isochBuffer. The 
isochBuffer data structure describes a single application data buffer. 
Typically, isochBuffer data structures exist in a doubly linked list. This 
data structure is defined in Table XII below. 
TABLE XII 
__________________________________________________________________________ 
typedef struct isochBuffer { 
struct isochBuffer *Next; 
/*ptr to next block*/ 
struct isochBuffer *Previous; 
/*ptr to prev. Block*/ 
OPTION Circular 1; 
/*list is circular*/ 
OPTION ResynchEvent 
:4; 
/* optional resynch event*/ 
OPTION Sy :4; 
/*sy field value*/ 
busTime 
Time; /*used with resynch event*/ 
localBufPtr ApplBufPtr; 
/*ptr to application data*/ 
void (*IsochCompletion)(struct isochBuffer *buf); 
/*completion routine*/ 
void *UserPtr /*for use by the completion routine*/ 
} isochBuffer, *isochBufferPtr; 
__________________________________________________________________________ 
The Next field contains the address of the next buffer in the list. The 
Previous field contains the address of the previous buffer in the list. 
The Circular field indicates that the complete set of buffers is circular. 
The ResynchEvent field contains an optional resynchronization event. A 
value of IMMEDIATE in this field indicates no resynchronization. When the 
ResynchEvent field contains a value of "SYFIELD," the Sy field contains 
the sy value to pause for before transferring data into or out of this 
application data buffer. When the ResynchEvent field contains a value of 
"TIME," the Time field contains the bus time to wait for before 
transferring data into or out of this application data buffer. The 
ApplBufPtr field contains the address of the application data buffer. This 
address may be logical, physical, scattered or contiguous, depending on 
the capabilities of the operating environment. The IsochCompletion field 
contains the address of the completion routine. If the value in this field 
is not null, then this routine is called when data transfer for this 
buffer is complete. The UserPtr field is available for use by the calling 
application's completion routine and is not modified by the API. 
The ISOCHDetach routine retrieves application data buffers from the API and 
returns ownership to the application. The application may call this 
routine at any time to detach buffers from the IEEE 1394 interface 
hardware and the associated low layers of software. The requested buffers 
are detached when the completion routine is invoked. The calling 
convention for this routine is as follows: 
status ISOCHDetach(ISOCHOpenBlockPtr openBlock, ISOCHAppendBlockPtr 
unhook); 
The possible status return values of an ISOCHDetach routine are GOOD, 
signalling that the operation was completed and the application data 
buffers are now detached, PENDING, signalling that the operation is 
currently pending, INVALIDCONNECTION, signalling that the openBlock field 
does not represent an active isochronous port, INVALIDREQUEST, signalling 
that the buffers described in the ISOCHAppendBlock were not found, or they 
are not owned by the isochronous port described in the ISOCHOpenBlock 
structure, and UNDEFINEDERROR, signalling that the operation could not be 
completed, but an actual error could not be identified. If a pending value 
is returned, at the time the callback routine is called, the status field 
in the ISOCHAppendBlock will contain the completion status of the detach 
operation. 
The first parameter of an ISOCHDetach routine contains the address of a 
valid ISOCHOpenBlock data structure. The second parameter contains the 
address of an ISOCHAppendBlock data structure. This data structure 
describes the application data buffer list as defined above. 
The applications programming interface of the present invention provides an 
interface to an application and allows the application to transfer data 
over a bus structure in both isochronous and asynchronous data formats. 
The applications programming interface supports transferring asynchronous 
data over the bus structure 28 during an isochronous data transfer. While 
the isochronous data is being transferred over the bus structure 28, the 
asynchronous data can be used to fill in the gaps. The IEEE 1394 standard 
specifies a worst case jitter for the isochronous data, thereby specifying 
a bounded latency for a packet of isochronous data. The API 20 therefore 
ensures that the packets of isochronous data are transferred during their 
appropriate time period. However, in the gaps between the packets of 
isochronous data, asynchronous packets of data are transferred. 
In contrast to systems of the prior art, the API of the present invention 
is capable of automating the transfer of asynchronous data by controlling 
an automatic transaction generator 38 which automatically generates the 
transactions necessary to complete an asynchronous data transfer over the 
memory-mapped bus structure 28. During an isochronous data transfer, a 
linked list of buffer descriptors, each representing a corresponding 
buffer, is maintained for transferring the data to or from the application 
over the bus structure 28. Each buffer can include a callback routine and 
a resynchronization event. 
The present invention has been described in terms of specific embodiments 
incorporating details to facilitate the understanding of the principles of 
construction and operation of the invention. Such reference herein to 
specific embodiments and details thereof is not intended to limit the 
scope of the claims appended hereto. It will be apparent to those skilled 
in the art that modifications may be made in the embodiment chosen for 
illustration without departing from the spirit and scope of the invention.