Adaptec FireWire 1394 User manual

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
1
IEEE1394 Application Programming Interface Specification
for WIN32 (Windows 95 and NT)
(PAPI)
Adaptec PN 000000-00
Rev 1.14
July 3, 1997
Copyright 1996 Adaptec Inc. All rights reserved
Adaptec Inc. Confidential

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
2
1.0 Introduction
The IEEE1394 Application Programming Interface (PAPI) allows developers to write applications that
control a IEEE1394 node / device directly.
To use PAPI for Win32 the three functions listed in the next section must be imported from wnpapi32.dll
into the client’s application.
Function Description
GetPAPISupportInfo This function returns the total number of IEEE1394 host adapters installed and
ensures that the PAPI manager is initialized properly.
SendPAPICommand This function handles IEEE1394 I/O requests.
BusConfig Get or Set IEEE1394 and host adapter configuration
The PAPI Manager for Win32 is implemented as a Dynamic Link Library (DLL) named wnpapi32.dll and
wn1394.sys for WinNT. PAPI functions are used to retrieve information about IEEE1394 Host Adapters
and devices and to execute IEEE1394 I/O requests.
PAPI consists of three major API functions. GetPAPISupportInfo is used to determine the number of
IEEE1394 host adapters found. SendPAPICommand and BusConfig have several subcommands.
BusConfig commands are executed by filling in and sending down SBC packets, SendPAPICommands are
executed by sending down PRBs. If a command is to be executed asynchronously an event has to be
specified in the command packet, PRB or SBC, that will be signaled upon completion of the command.
Devices on the 1394 bus(es) are accessed using handles. A client must get a handle to a specific device by
calling BusConfig with command field set to P_GET_HANDLE and the node ID field set to the nodeID of
the target device. Handles are used instead of node Ids because Node Ids can potentially change when Bus
Resets occur.
The HaNum field in the header of every PAPI packet represents the Host adapter number in a multiple host
adapter situation. There is an assumption made and that is that two host adapters in the same system are
not on the same 1394 bus.
All PAPI commands except fot GetPAPISupportInfo have a common header, this header contains fields
for sub-commands that an application specifies what it wants to perform, BusId or Host Adapter number
to which the intended node is attached to, Device handle which basically address the specific node and a
status field that PAPI returns. Each command has its own set of possible status values that PAPI would
return and these are specified within each command description below.

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
3
Upon completion of a command the caller needs to inspect the Status field within the common header at
the top of the packet to determine whether the command executed successfully, PS_COMP, or whether
ther was an error. In the definition of every command in the following pages all the possible status(es) are
listed.

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
4
Definitions
PAPI: 1394 Application Programming Interface
PAPI Manager: The layer that processes PAPI requests
PAPI Client: An application that uses PAPI to access 1394 peripherals
DLL: Dynamic Link Library
SBC: Serial Bus Configuration packet
PRB: P1394 Request Block
Note: In the following sections fields marked with [OUT] are returned by the PAPI manager.
Fields marked with [IN] are set by the PAPI client before they are sent to the PAPI manager.
Fields marked as Reserved must be zeroed before the PRB is sent to the PAPI manager.

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
5
I. GetPAPISupportInfo Function
DWORD GetPAPISupportInfo (BYTE *NumberOfAdapters)
The GetPAPISupportInfo function returns in NumberOfAdapters the total number of IEEE1394 host
adapters installed. If the PAPI manager is not installed properly then the function returns an error.
Return Value Description
PAPI_NOERROR PAPI Mgr initialized without error
PAPI_FAILED_INIT PAPI Mgr failed to initialize properly
If the return value is PAPI_NOERROR then NumberOfAdapters is set to the number of IEEE1394 Host
adapters in the system.

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
6
II. SendPAPICommand Function
DWORD SendPAPICommand (PPRB lpPRB)
This function handles all IEEE1394 I/O requests. A command code is used to specify the type of I/O
requested. This function is called with a pointer to a IEEE1394 Request Block (PRB) structure which is
filled by the caller, the PAPI client.
The following IEEE1394 I/O command codes are defined within SendPAPICommand.
COMMAND CODE DESCRIPTION
P_GET_HA_INFO Get information on a specific host adapter along with the total
number of host adapters installed.
P_GET_DEV_INFO Get device’s configuration ROM information.
P_QUEUE_ISOC_CMD Queue an isochronous transfer
P_START_ISOC Begin isochronous transfers on the given channel
P_STOP_ISOC Stop isochronous transfers on the given channel
P_EXEC_ASYNC_CMD Execute an asynchronous transfer.
P_NOTIFY_ON_ACCESS Notify client when a mapped area is accessed
P_ABORT_1394_CMD Abort an outstanding I/O command.
P_GET_BUS_EVENT Asynchronous serial bus events are reported via this command
P_GET_CAP_VERSIONS Get Host adapter capabilities and Chip and HAL versions

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
7
The following structure is the header or all PRB and SBC packets.
typedef struct _PRB_SBC_HEADER
{BYTE Cmd; // PAPI command code
BYTE Status; // PAPI status returned
BYTE HaNum; // Host adapter number
BYTE Hdr_Rsvd1; // Reserved, must be 0
DWORD DevHandle // Handle to 1394 peripheral
DWORD Hdr_Rsvd[2]; // Reserved, must be 0
OVERLAPPED OverlappedInfo;
} PRB_SBC_HEADER, *PPRB_SBC_HEADER;

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
8
1. Get Host Adapter Info command
DWORD SendPAPICommand (PPRB lpPRB)
The SendPAPICommand function with command code P_GET_HA_INFO is used to get information on
an installed IEEE1394 host adapter.
typedef struct _PRB_GET_HA_INFO
{PRB_SBC_HEADER PRB_SBC_Header;
DWORD Rsvd1[2];
DWORD Rsvd2;
WORD Node_Count;
WORD HA_Node_ID;
WORD Root_ID;
WORD Cycle_Mstr_ID;
WORD Bus_Mgr_ID ;
WORD Isoch_Mgr_ID;
BYTE Gap_Count;
BYTE Rsvd3[3];
DWORD Rsvd4[2];
DWORD pSpeed_Map;
DWORD pTopology_Map;
DWORD pPower_Map;
BYTE HA_Identifier[16];
} PRB_GET_HA_INFO, *PPRB_GET_HA_INFO;

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
9
Member Description
Cmd [IN] P_GET_HA_INFO
Status [OUT] Status returned
PS_COMP
PS_ERROR Command completed successfully Command completed with error
HaNum [IN] Host adapter number, must = 0
Hdr_Rsvd1 [IN] Reserved, must = 0
DevHandle [IN] n/a
Hdr_Rsvd2 [IN] Reserved, must = 0
OverlappedInfo [IN] n/a
PRB_Rsvd1 [IN] Reserved, must = 0
Node_Count [OUT] Number of nodes on this bus
HA_Node_ID [OUT] ID of the host adapter
Root_ID [OUT] ID of Root node
Cycle_Mstr_ID [OUT] ID of node acting as Cycle Master
Bus_Mgr_ID [OUT] ID of node acting as active Bus Manager
Isoch_Mgr_ID [OUT] ID of node acting as Isochronous Resource Mgr.
Gap_Count [OUT] Current gap count of the bus
Rsvd2 [IN] Reserved, must = 0
pSpeed_Map [OUT] Pointer to Speed Map of the 1394 Bus
pTopology_Map [OUT] Pointer to Topology of 1394 Bus
pPower_Map [OUT] Pointer Power Map of 1394 Bus
HA_Identifier [OUT] ASCII string identifying the host adapter

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
10
2. Get Device Info Command
DWORD Send PAPICommand (PPRB lpPRB)
The SendPAPICommand function with command code P_GET_DEV_INFO is used to get the
configuration ROM information of a IEEE1394 device on the bus..
typedef struct _PRB_GET_DEV_INFO
{PRB_SBC_HEADER PRB_SBC_Header;
DWORD Rsvd1[2];
BYTE Rsvd2[2];
WORD node_ID;
BYTE Dev_Cfg_Rom_Info[1024];
DWORD NodeUniqueIdHi;
DWORD NodeUniqueIdLo;
BYTE RomFormat;
BYTE SerialBusDevice;
BYTE Rsvd3[2];
} PRB_GET_DEV_INFO, *PPRB_GET_DEV_INFO;
Member Desription
Cmd [IN] P_GET_DEV_INFO
Status [OUT] status returned
PS_COMP
PS_ERROR Command completed successfully Command completed with error
HaNum [IN] Host adapter number
Hdr_Rsvd1 [IN] Reserved, must = 0
DevHandle [IN] Not used, must = 0
Hdr_Rsvd2 [IN] Reserved, must = 0
OverlappedInfo [IN] n/a
Node_ID [IN] Node ID of device to get info from
Dev_Cfg_Rom_Info [OUT] Device configuration ROM information
NodeUniqueIdHi [OUT] upper 32 bits of device’s unique ID
NodeUniqueIdLo [OUT] lower 32 bits of device’s unique ID
RomFormat [OUT] 00 = Minimal ROM implementation
01 = General ROM implementation
SerialBusDevice [OUT] 00 = Not a 1394 device but conforms to IEEE1212
01 = Is a 1394 device
Rsvd2 [IN] Reserved, must = 0

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
11
3. Queue an isochronous transfer request
DWORD Send PAPICommand (PPRB lpPRB)
The SendPAPICommand function with command code P_ISOC_REQUEST is used to queue an
Isochronous transfer for a given channel. Generally this command is used to queue up several buffers
before issuing a P_START_ISOC command to initiate transfers. If buffers are sent down after a
P_START_ISOC command is sent then the command will be executed immediately if there are no other
buffers ahead of it. Otherwise, the command will be queued.
This scheme is used to maximize the chances of capturing all of the isochronous data received.
typedef struct _ PRB_ISOC_REQUEST
{PRB_SBC_HEADER PRB_SBC_Header;
DWORD Rsvd1[2];
BYTE Rsvd2;
BYTE Mode;
BYTE Rsvd3[2];
BYTE Channel;
BYTE Speed;
BYTE SyncCode;
BYTE Rsvd4;
WORD CycleStart;
BYTE Rsvd5[2];
DWORD Rsvd6[2];
WORD PrimaryXmitPayload;
WORD SecondaryXmitPayload;
DWORD IsocIoRequestFlags;
DWORD Rsvd7[2];
DWORD HA_Buf_Ptr;
DWORD Rsvd8;
DWORD TotalXfrLen;
DWORD Rsvd9[3];
} PRB_ISOC_REQUEST, *PPRB_ISOC_REQUEST;

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
12
Member Description
Cmd [IN] P_QUEUE_ISOC_CMD
Status [OUT] Status returned upon completion
PS_PENDING
PS_COMP
PS_ERROR
PS_ABORTED
PS_DMA_STOP
HaNum [IN] Host adapter number, must = 0
Hdr_Rsvd1 [IN] Reserved, must = 0
DevHandle [IN] Handle of IEEE1394 peripheral obtained via GetHandle
Hdr_Rsvd2 [IN] Reserved, must = 0
OverlappedInfo [IN] Completion event is placed in OverlappedInfo.hEvent
Rsvd1 [IN] Reserved, must = 0
Rsvd2 [IN] Reserved, must = 0
Mode [IN] Mode flags
PM_ISOC_READ = Isochronous read operation (receive).
PM_ISOC_WRITE = Isochronous write operation (broadcast).
PM_ISOC_DV_READ - Read DV format
PM_ISOC_DV_WRITE_NTSC - Write DV in NTSC format
PM_ISOC_DV_WRITE_PAL - Write DV in PAL format
Rsvd3 [IN] Reserved, must = 0
Channel [IN] Bits [7:6] = Isochronous data format tag. See IEEE1394 spec sec.
Bits [5:0] = Isochronous channel number.
Speed [IN] Speed at which the 1394 transfer should occur. If set to 0xFF,
optimal speed will be picked automatically for the transfer.
SyncCode [ IN] Sync code to be matched before transmission starts
Rsvd4 [IN] Reserved, must = 0
CycleStart [IN] The cycle at which transmission should start
Rsvd5 [IN] Reserved, must = 0
PrimaryXmitPayload [IN] Standard payload size to be transmitted in each isochronous cycle. In the
case of CIP payloads, this payload size should include the CIP header.
This field is equal to 488 for DV data.
SecondaryXmitPayload [IN] Secondary payload size to be transmitted if needed, in order to meet the
bytes per second data throughput required by a particular isochronous device.
This field is only valid if the VARIABLE_PACKET_SIZE Flag is set. This field
is only valid for broadcast (transmit) operations.
This field is equal to 8 for DV data
IsocIoRequestFlags [IN]
START_ON_SYNC_CODE
START_ON_CYCLE_NUMBER

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
13
STRIP_CIP_HEADERS - Depends on HW capabilities
INSERT_CIP_HEADERS - Depends on HW capabilities
VARIABLE_PACKET_SIZE
Rsvd7 [IN] Reserved,must = 0
HA_Buf_Ptr [IN] Data Buffer address
Rsvd8 [IN] Reserved, must = 0
TotalXfrlen [IN] Total transfer length
Rsvd9 [IN] Reserved, must = 0

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
14
4. Start an Isochronous Transfer
DWORD Send PAPICommand (PPRB lpPRB)
The SendPAPICommand function with command code P_START_ISOC is used to begin a 1394
Isochronous transfer on a particular channel. Any previously queued Isochronous requests, via
SendPAPICommand function with command code P_ISOC_REQUEST) will begin immediately. To stop
the Isochronous transfer, call SendPAPICommand function with command code P_STOP_ISOC.
typedef struct _ PRB_START_ISOC
{PRB_SBC_HEADER PRB_SBC_Header;
DWORD Rsvd1[2];
DWORD Channel;
} PRB_START_ISOC, *PPRB_START_ISOC;
Member Description
Cmd [IN] P_START_ISOC
Status [OUT] Status returned upon completion
PS_COMP
PS_ERROR
HaNum [IN] Host adapter number, must = 0
Hdr_Rsvd1 [IN] Reserved, must = 0
DevHandle [IN] N/A
Hdr_Rsvd2 [IN] Reserved, must = 0
Rsvd1 [IN] Reserved, must = 0
Channel [IN] The 1394 channel on which isochronous transfers should begin

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
15
5. Stop Isoc Transfer
DWORD Send PAPICommand (PPRB lpPRB)
The SendPAPICommand function with command code P_STOP_ISOC is used to stop isochronous
transfers on a particular channel. Any previously queued transfers will be completed. Any new queued
transfers will not start until SendPAPICommand function with command code P_START_ISOC is called.
typedef struct _ PRB_STOP_ISOC
{PRB_SBC_HEADER PRB_SBC_Header;
DWORD Rsvd1[2];
DWORD Channel;
} PRB_STOP_ISOC, *PPRB_STOP_ISOC;
Member Description
Cmd [IN] P_STOP_ISOC
Status [OUT] Status returned upon completion
PS_COMP - Transfers stopped
PS_ERROR - Transfers on the channel already stopped
HaNum [IN] Host adapter number, must = 0
Hdr_Rsvd1 [IN] Reserved, must = 0
DevHandle [IN] n/a
Hdr_Rsvd2 [IN] Reserved, must = 0
Rsvd1 [IN] Reserved, must = 0
Channel [IN] The 1394 channel on which isochronous transfers should stop

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
16
6. Execute Asynchronous transfer command
DWORD Send PAPICommand (PPRB lpPRB)
The SendPAPICommand function with command code P_EXEC_ASYNC_CMD is used to performs an
asynchronous serial bus transfer request. The data payload must be aligned on a DWORD boundary;
however, the total transfer length may be larger than the maximum data payload allowed per packet.
typedef struct _ PRB_EXEC_ASYNC
{PRB_SBC_HEADER PRB_SBC_Header;
DWORD Rsvd1[2];
BYTE Rsvd2;
BYTE Mode;
BYTE Rsvd3;
BYTE ResponseCode;
WORD Extend_tCode;
BYTE Speed;
BYTE Rsvd4;
WORD MaxBlockSize;
BYTE Rsvd5[2];
DWORD Rsvd6[2];
DWORD TargetDeviceAddressHi;
DWORD TargetDeviceAddressLo;
DWORD Rsvd7[2];
DWORD HA_Buf_Ptr;
DWORD Rsvd8;
DWORD TotalXfrLen;
DWORD Rsvd9[3];
} PRB_EXEC_ASYNC, *PPRB_EXEC_ASYNC;

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
17
Member Description
Cmd [IN] P_EXEC_ASYNC_CMD
Status [OUT] Status returned upon completion
PS_PENDING
PS_COMP
PS_ERROR
PS_ABORTED
PS_INVALID_HANDLE
HaNum [IN] Host adapter number, must = 0
Hdr_Rsvd1 [IN] Reserved, must = 0
DevHandle [IN] Handle of IEEE1394 peripheral
Hdr_Rsvd2 [IN] Reserved, must = 0
OverlappedInfo [IN] Completion event is placed in OverlappedInfo.hEvent
Rsvd1 [IN] Reserved, must = 0
Rsvd2 [IN] Reserved, must = 0
Mode [IN] Mode
PM_ASYNC_WRITE_REQUEST
PM_ASYNC_READ_REQUEST
PM_ASYNC_LOCK_REQUEST
Rsvd3 [IN] Reserved, must = 0
ResponseCode [OUT] Asynchronous transaction response code
PR_COMP
PR_CONFLICT_ERROR
PR_DATA_ERROR
PR_TYPE_ERROR
PR_ADDRESS_ERROR
Extend_tCode [IN] Extended Transaction Code for Lock transactions only
PE_MASK_SWAP
PE_COMPARE_SWAP
PE_FETCH_ADD
PE_LITTLE_ADD
PE_BOUNDED_ADD
PE_WRAP_ADD
PE_VENDOR_DEPENDENT
Speed [IN] Speed at which the 1394 transfer should occur. If set to 0xFF, the
optimal speed will be picked automatically for the transfer
Rsvd4 [IN] Reserved, must = 0
MaxBlockSize This specifies the maximum block size per payload for a block request. If
MaxBlockSize is set to zero, the optimal payload size will be picked
automatically for the transfer. Refer to the HA_GetCapabilites routine to
determine if this field is supported.
Rsvd5 [IN] Reserved, must = 0
Rsvd6 [IN] Reserved, must = 0

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
18
TargetDeviceAddressHi [IN] Device’s 1394 address high 32 bit
TargetDeviceAddressLo [IN] Device’s 1394 address low 32 bit
Rsvd7 [IN] Reserved, must = 0
HA_Buf_Ptr [IN] Host adapter buffer pointer
PRB_Rsvd8 [IN] Reserved, must = 0
TotalXfrLen [IN] Size of the data payload in Bytes.
PRB_Rsvd9 [IN] Reserved, must = 0

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
19
7. Notify client when 1394 mapped area is accessed
DWORD Send PAPICommand (PPRB lpPRB)
The SendPAPICommand function with command code P_NOTIFY_ON_ACCESS is used to register for a
notification when a remote node accesses a mapped section of 1394 address. Upon access, the event
specified in the OverlappedInfo field of the header will be signaled.
typedef struct _PRB_NOTIFY_ON_ACCESS
{
PRB_SBC_HEADER PRB_SBC_Header;
DWORD Rsvd1[3];
DWORD BufferAddress;
DWORD BufferLength;
DWORD Hi_1394_Address;
DWORD Lo_1394_Address;
WORD RequestorNodeID;
WORD RequestDataLength;
DWORD Rsvd2[3];
} PRB_NOTIFY_ON_ACCESS, *PPRB_NOTIFY_ON_ACCESS;
Member Description
Cmd [IN] P_MAP_NOTIFY_ON_ACCESS
Status [OUT] Status returned upon completion
PS_PENDING
PS_COMP
PS_ERROR
PS_ABORTED
HaNum [IN] Host adapter number, must = 0
Hdr_Rsvd1 [IN] Reserved, must = 0
DevHandle [IN] n/a
Hdr_Rsvd2 [IN] Reserved, must = 0
OverlappedInfo [IN] Completion event is placed in OverlappedInfo.hEvent
Rsvd1 [IN] Reserved, must = 0
BufferAddress [IN] Starting virtual address of the user buffer onto which the 1394

--- IEEE1394 Application Programming Interface Specification ---
--- Adaptec Inc. Confidential ---
7/9/97
20
address will be mapped
BufferLength [IN] Length of the buffer, i.e. length of mapped section in bytes
Hi_1394_Address [IN] upper 32 bit of 1394 address of access area for which notification
is being registered.
Lo_1394_Address [IN] lower 32bit of 1394 address
RequestorNodeId [OUT] Node ID of the originator of the unsolicited request
RequestDataLength [OUT] Number of bytes accessed