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
Other manuals for FireWire 1394
1
This manual suits for next models
1
Other Adaptec Recording Equipment manuals
