ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) DC 900-1516D Protogate, Inc.
Protogate, Inc. 12225 World Trade Drive, Suite R San Diego, CA 92128 (858) 451-0865 ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) © 2002 Protogate, Inc. All rights reserved Printed in the United States of America This document can change without notice. Protogate, Inc. accepts no liability for any errors this document might contain. Freeway is a registered trademark of Simpact, Inc. All other trademarks and trade names are the properties of their respective holders.
Contents List of Figures 7 List of Tables 9 Preface 11 1 Product Overview 17 2 Software Installation 19 2.1 2.2 2.3 2.4 2.5 2.6 3 Device Driver Installation Procedure. . . . . . . . . . . . Protocol Software Installation Procedure . . . . . . . . . Software Installation Procedure (VMSINSTAL tape) . . . Software Installation Procedure (VMS BACKUP saveset). Loading the ICP2432 Driver . . . . . . . . . . . . . . . . Loading the Protocol Software . . . . . . . . . . . . . . . . . . . . . . . . .
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 3.3.1.7 Blocking I/O . . . . . . . . . . . . . . . 3.3.1.8 Multithreaded Support. . . . . . . . . . 3.3.2 The Application Program’s Interface to DLITE 3.3.2.1 Building a DLITE Application . . . . . . 3.3.2.2 Blocking and Non-blocking I/O . . . . . 3.3.2.3 Changes in DLI/TSI . . . . . . . . . . . 3.3.2.4 Changes in DLI Functions . . . . . . . . 3.3.2.5 Callbacks . . . . . . . . . . . . . . . . . 3.3.2.6 DLITE Error Codes. . . . . . . . . . . . 3.3.
Contents 4.3.2 Use Of Node Numbers (DLI) . . . . . . . . 4.3.2.1 Node 1 . . . . . . . . . . . . . . . . . 4.3.2.2 Node 2 . . . . . . . . . . . . . . . . . 4.3.2.3 Nodes 3 through 126. . . . . . . . . . 4.3.3 DLI Session Commands . . . . . . . . . . . 4.3.3.1 ATTACH Command . . . . . . . . . . 4.3.3.2 DETACH Command. . . . . . . . . . 4.3.3.3 TERMINATE Command . . . . . . . 4.3.4 ICP Discarded Packets . . . . . . . . . . . . 4.4 Node Auto-Assignment Mode for Read Requests 4.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) Index 6 105 DC 900-1516D
List of Figures Figure 1–1: Typical Data Communications System Configuration . . . . . . . . . . . 18 Figure 3–1: DLI/TSI Interface in the Freeway Server Environment . . . . . . . . . . . 36 Figure 3–2: DLITE Interface in an Embedded ICP2432 Environment. . . . . . . . . . 37 Figure 3–3: DLI_ICP_DRV_INFO “C” Structure. . . . . . . . . . . . . . . . . . . . . 45 Figure 4–1: P4 Parameter Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 8 DC 900-1516D
List of Tables Table 2–1: Protocol Identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Table 3–1: DLITE Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Table 3–2: VMS Errors Mapped to dlerrno . . . . . . . . . . . . . . . . . . . . . . . . 51 Table 3–3: DLI Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Table 5–1: Comparison of DLI_OPT_ARGS and ICP_PACKET Structures . . . . . .
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 10 DC 900-1516D
Preface Purpose of Document This document describes how to use the ICP2432 intelligent communications processor (ICP) in a peripheral component interconnect (PCI) bus computer running the VMS operating system. Intended Audience This document is intended primarily for VMS system managers and applications programmers. Organization of Document Chapter 1 is an overview of the product. Chapter 2 describes how to install the ICP2432 and protocol software in a VMS system.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 3/3/99 Leslie: Temporarily remove 1332, 1532, 1541, and 1543 (post-layoffs) Protogate References The following documents provide useful supporting information, depending on the customer’s particular hardware and software environments. Most documents are available on-line at Protogate’s web site, www.protogate.com.
Preface • • • Getting Started with Freeway 2000/4000 DC 900-1330 Getting Started with Freeway 8800 DC 900-1552 Loopback Test Procedures DC 900-1533 Embedded ICP Installation and Programming Support • • • • • ICP2432 User’s Guide for Digital UNIX DC 900-1513 ICP2432 User’s Guide for OpenVMS Alpha DC 900-1511 ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) DC 900-1516 ICP2432 User’s Guide for Windows NT DC 900-1510 ICP2432 User’s Guide for Windows NT (DLITE Interface) DC 900-1514
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) • • • • • • Military/Government Protocols Programmer’s Guide DC 900-1602 SIO STD-1200A (Rev. 1) Programmer’s Guide DC 908-1359 SIO STD-1300 Programmer’s Guide DC 908-1559 X.25 Call Service API Guide DC 900-1392 X.25/HDLC Configuration Guide DC 900-1345 X.
Preface You can also fax your questions to us at (877) 473-0190 any time. Please include a cover sheet addressed to “Customer Service.” We are always interested in suggestions for improving our products. You can use the report form in the back of this manual to send us your recommendations.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 16 DC 900-1516D
Chapter 1 Product Overview The Protogate ICP2432 data communications product allows PCIbus computers running the VMS operating system to transfer data to other computers or terminals over standard communications circuits. The remote site need not have identical equipment. The protocols used comply with various corporate, national, and international standards. The ICP2432 product consists of the software and hardware required for user applications to communicate with remote sites.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) User Application Processes Host Driver (ZJDRIVER.
Chapter 2 Software Installation A typical software installation may contain two or more distribution media packages (tapes, CDs, and so on). One package contains the ICP2432 VMS device driver, DLITE, and related files. The other package may contain a specific Protogate protocol and its related files. This chapter describes the installation procedure for both the device driver and the protocol software for VMS systems.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 2.1 Device Driver Installation Procedure The ICP2432 driver (ZJDRIVER) uses the “Freeway” directory tree for building executable images even if you are not using a Freeway server. The software installation procedures described in this section load the ZJDRIVER and the DLITE API into a new or already existing Freeway directory. The following files are placed in the FREEWAY directory: • The [FREEWAY.CLIENT.VMS_EMB.
2: Software Installation 2.2 Protocol Software Installation Procedure The software installation procedures described in this section refer to file names that include a “ppp” identifier to indicate a specific protocol. Table 2–1 shows the “ppp” identifiers for various protocols. For example, ppp_FW_2432.MEM translates to BSC3270_FW_2432.MEM for BSC3270 or X25_FW_2432.MEM for X.25. Note that some newer protocol releases have image names that fit within the DOS 8.3 format (for example: X25_2432.MEM).
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) The following files are in the FREEWAY directory: • README.ppp provides general information about the protocol software • RELNOTES.ppp provides specific information about the current release of the protocol software • RELHIST.ppp provides information about previous releases of the protocol soft- ware For older Simpact software releases prior to June 1, 1998, the executable object for the protocol software, ppp_FW_2432.
2: Software Installation 2.3 Software Installation Procedure (VMSINSTAL tape) The software distribution media contains several VMS BACKUP savesets. To install the software from the distribution media onto your VMS computer, use the VMSINSTAL utility as described in the following procedure. Caution Remember that installing new software overwrites the previous software. After the distribution media is mounted, the procedure is automated and only requires that you respond to menu prompts.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) The computer checks the following conditions: • Are you logged in to the system manager’s account? You should install the software from that account; however, any account with the necessary privileges is acceptable. • Do you have adequate account quotas for installing software? VMSINSTAL checks for the various quota values.
2: Software Installation For DDCU, substitute a device name such as MUA0, MKA100, DUAl, or something similar. Step 6: The computer displays: Enter the products to be processed from the first distribution volume set. * Products: * Enter an asterisk (this causes all products to be installed). Step 7: The computer displays: * Enter installation options you wish to use (none): Refer to Digital’s VMS Installation Guide for a list of the VMSINSTAL options and how to enter them.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) * Is this acceptable [Y]? y Remember that DDCU means a device name. Press to answer yes (this is highly recommended). If you answer no, you are prompted to enter the name of a directory. Step 10: The computer displays: There are no more questions. The installation will proceed. The procedure completes automatically.
2: Software Installation 2.4 Software Installation Procedure (VMS BACKUP saveset) Some software distributions or updates from Protogate may be in the form of a ZIP file or a VMS BACKUP saveset that does not use the VMSINSTAL utility. This section lists the procedures to install software from this type of distribution. Caution Remember that installing new software overwrites the previous version of that software. The software distribution will usually contain three files as listed below: • filename.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) Step 2: Use FTP in binary (image) mode to copy the saveset (BCK file) from your Windows PC to your VMS system. Step 3: Convert the saveset file to a record format that will be recognized by the VMS BACKUP utility. To do this, use the DCL command below: $ SET FILE /ATTR=(RFM:FIX,RAT:NONE,LRL:32256) filename.BCK Step 4: Use the VMS BACKUP utility to restore the files on your system.
2: Software Installation 2.5 Loading the ICP2432 Driver The following procedure describes how to load the VMS device driver (ZJDRIVER) for the ICP2432. Once the device driver is loaded on your system, it does not have to be reloaded until the system is rebooted. The procedure also provides instruction on how to configure your system so that the ZJDRIVER is loaded automatically during system startup.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) SYSMAN-I-OUTPUT, command execution on node GABIN SYSMAN-I-IOPREFIX, the current prefix list is: SYS$,DECW$ The current prefix list is SYS$,DECW$. The empty string equates to the prefix SYS$.
2: Software Installation 2.6 Loading the Protocol Software The following procedure describes how to load the protocol software into the ICP2432 boards. Note that you may load and reload the protocol software as many times as you wish without having to reload the VMS device driver (ZJDRIVER) for the ICP2432. The procedure also provides instruction on how to configure your system so that the protocol software is loaded automatically at system startup.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) Note ICPLOADVMS searches for the script file and the installed protocol software image (for example, fmpload and FMP_FW_2432.MEM) in the specified directory. If not found in the specified directory, then it searches in the [FREEWAY.BOOT] directory. If the directory is not specified, the current directory is used. If the script file can not be found, ICPLOADVMS returns an error. Step 2: Execute ICPLOADVMS.
2: Software Installation $! Download Protocol Software $! $! $ICPLOADVMS device-name download-script-file dlite-flag $! $! $ ICPLOADVMS ZJA0 fmpload DLITE $ Step 4: Execute the ICP2432_STARTUP.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 34 DC 900-1516D
Chapter Techpubs — Terminology Cautions: 1) use blocking and nonblocking I/O (instead of synchronous and asynchronou s 2) use “Raw operation” rather than “Raw mode” 3 Programming Using the DLITE Embedded Interface 3.1 Overview This chapter primarily describes the differences between the data link interface (DLI) to Freeway (as described in the Freeway Data Link Interface Reference Guide) and the DLITE embedded interface in a OpenVMS system, referred to as “DLITE.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) DLITE, developers can concentrate on the communication requirements of the ICP2432 rather than the details required by the VMS interface and the ICP2432 OpenVMS driver, thereby reducing programming complexity and development time. DLITE can be thought of as a communications pipe to the ICP2432. It is compatible with the existing Freeway DLI (with caveats described in Section 3.3.1 on page 38).
3: Programming Using the DLITE Embedded Interface Instead, the embedded application using DLITE communicates directly with the OpenVMS ICP2432 driver (through the VMS interface), which accesses the locally attached ICP. This interface is shown in Figure 3–2. In this environment no Freewaytype communications take place; it is designed specifically for the embedded system.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 3.3 DLITE Interface The DLITE interface is described here in terms of enhanced capabilities, limitations and caveats, the API itself, configuration files, and logging/tracing (see Section 3.3.4). Within each context, necessary changes and any behavior differences are noted. 3.3.1 DLITE Limitations and Caveats 3.3.1.1 Raw Operation Only DLITE supports only Raw operation.
3: Programming Using the DLITE Embedded Interface vious writes are not posted as complete until DLI receives this LocalAck, then the LocalAck is thrown away). However, the DLITE user is responsible for receiving each LocalAck and performing any necessary processing. The DLITE behavior is exactly the same as when the DLI LocalAck configuration parameter is set to “no”. This generally implies the client application should post a dlRead after each dlWrite to receive the expected Local Ack. 3.3.1.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 3.3.1.5 dlInit Function No Longer Implied DLI allowed users to perform dlOpen before calling dlInit (dlInit would be invoked if required, not a recommended practice). This results in an error when using DLITE. Processing must be initialized using dlInit before any other service is requested. 3.3.1.6 Unsupported Functions The following functions are not supported. Applications invoking these functions return with the DLI_XX…XX_ERR_NEVER_INIT error.
3: Programming Using the DLITE Embedded Interface 3.3.2 The Application Program’s Interface to DLITE Except where described in the previous sections, the embedded DLITE interface does not change the application’s interface to DLI. While the DLI interface has remained intact, changes have been made in both the methods supporting DLI and in the underlying functionality. 3.3.2.1 Building a DLITE Application The DLITE API is provided on a static library named LIBVMSEMB.OLB.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) • dlWrite Using non-blocking I/O, a successful operation returns OK, and dlerrno has the value of EWOULDBLOCK . The application is notified of I/O completion through the I/O com- pletion handler (IOCH). The completed I/O operation is retrieved using a dlPoll request for read/write complete. See Section 3.3.2.5 on page 48 for more information on callbacks and I/O completion. 3.3.2.
3: Programming Using the DLITE Embedded Interface User requests are verified against the MaxBufs and MaxBufSize DLITE configuration parameters. Requests exceeding either of these return a buffer allocation error. Buffers allocated using dlBufAlloc are allocated with room for the ICP and Protocol header, and a small DLITE work area prefacing the user’s data area. This area is added to the user’s request; users do not have to account for these requirements in their buffer request.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) buffer is indeed freed. Any further reference to the buffer results in unpredictable results. Requests with a NULL buffer pointer and attempts to free a buffer not allocated with dlBufAlloc return with a buffer deallocation error message. dlInit The user application must call dlInit before any other DLITE service. If dlInit does not find the DLI configuration file, it returns the DLI_INIT_ERR_CFG_LOAD_FAILED error.
3: Programming Using the DLITE Embedded Interface typedef struct { unsigned long unsigned long unsigned long unsigned long unsigned long unsigned char _DLI_ICP_DRV_INFO Node; /* Node assigned */ DeviceNumber; /* Device Number (ICP) */ NumberOfPorts; /* Number of ports on ICP */ BufferAlignment; /* Byte alignment requirement */ NumberOfChans; /* Number of Channels */ Version[DLI_MAX_STRING + 1]; /* Driver version string.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) returned. Returning the cancelled request reduces the number of I/O completions by one. • Because cancelled I/O is considered completed, cancelled requests are also returned in response to requests for completed reads and writes (using dlPoll). These requests are returned with the DLI_IO_ERR_IO_CANCELLED error code. • This implementation of cancel processing supports those applications designed for the Freeway DLI.
3: Programming Using the DLITE Embedded Interface Note As with the DLI interface, read requests with a NULL buffer pointer result in DLITE allocating and returning a read buffer. The address of the buffer allocated is returned in the supplied buffer pointer upon return from the call. The user that wants a DLITE allocated buffer should ensure the buffer pointer supplied with the dlRead call is NULL. dlTerm Termination processing (dlTerm) releases resources and terminates DLITE.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 5. DLITE adds ICP->iStatus = LittleEndian ? htons (0x4000) : htons (0); 6. DLITE adds ICP->usDataBytes = htons (BufLen + DLI_PROT_HDR_SIZE); 7. If the ICP command is an Attach, or a Write Expedite, the node ID (previously retrieved from the VMS driver) is stored in ICP->usParam[0] ( ICP->usParms[0] = htons( Session->drvNodeID ) ). 8. PROT->usCommand = OptArgs->usProtCommand; 9. PROT->iModifier = OptArgs->iProtModifier; 10.
3: Programming Using the DLITE Embedded Interface There is no difference between the “main” callback and the “session” callback. They are initiated sequentially by DLITE. For sake of efficiency, Protogate recommends the user make use of only one. To maintain conformity with the existing DLI, callbacks are delivered upon completion of dlOpen processing. Although dlOpen processing does not generate a callback from the system (i.e.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) Table 3–1: DLITE Error Codes Value DLITE Error Code Description and Recommended Action –10211 DLI_OPEN_ERR_ICP_INVALID_ST Returned by dlOpen(). The ICP has not been downATUS loaded with a protocol or is in a non-operational state. –10231 DLI_OPEN_ERR_NO_DRV_INFO An error occurred in the I/O interface while requesting VMS driver information. Terminate the interface, verify VMS driver installation.
3: Programming Using the DLITE Embedded Interface Table 3–2: VMS Errors Mapped to dlerrno VMS Error Code DC 900-1516D Applicable dlerrno Codes SS$IVMODE DLI_READ_ERR_UNBIND DLI_WRIT_ERR_UNBIND SS$INSFMAPREG DLI_READ_ERR_IO_FATAL DLI_WRIT_ERR_IO_FATAL DLI_POLL_ERR_IO_FATAL SS$TIMEOUT DLI_READ_ERR_TIMEOUT DLI_WRIT_ERR_TIMEOUT DLI_POLL_ERR_READ_TIMEOU T DLI_POLL_ERR_WRITE_TIMEO UT SS$BUFFEROVF DLI_READ_ERR_OVERFLOW DLI_POLL_ERR_OVERFLOW SS$ACCVIO DLI_READ_ERR_INVALID_BUF DLI_WRIT_ERR_INVALID_BUF D
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) is returned in the usMaxBufs field of the configuration parameters returned in response to a dlPoll for system configuration. Operationally, this value limits the number of buffers the user can have outstanding using the dlBufAlloc function. If not explicitly defined in the DLI configuration file, the MaxBuffers parameter defaults to 1024. MaxBufSize — This parameter has been added to the “main” section.
3: Programming Using the DLITE Embedded Interface 3.3.4.1 Common Logging Service Errors An application can encounter several errors related to logging and tracing upon initialization with the dlInit function. See Table 3–3. These errors can result from the unavailability of system resources such as memory or disk space. In either case, the errors are non-fatal and the application proceeds normally; however, logging and tracing are not activated.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 54 DC 900-1516D
Chapter 4 Application Interface Programmers who prefer not to use the DLITE embedded interface (described in Chapter 3) have the option of writing their VMS application to communicate with the Protogate protocol software by sending and receiving formatted packets to the ICP2432 device. This is done by issuing VMS queued I/O (QIO) requests to the device driver (ZJDRIVER) supplied by Protogate. This chapter describes the use of the VMS system services as they apply to the Protogate device driver. 4.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) the QIO read path and are not associated with any command sent by the program. Asynchronous line events such as sudden changes in modem control signals are reported in the same way. For this reason, the VMS program should always keep a no-wait read posted to each active link in order to handle any unexpected packets. Protogate’s standard VMS device driver (ZJDRIVER) provides an interface to the ICP2432 that is used by several Protogate protocols.
4: Application Interface Your VMS system must have available PCIbus slots in order to use the ICP2432 boards. After the device driver is installed in the VMS system, ICP boards appear as the device names ZJAO, ZJBO. ZJCO, and so on.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 4.1.1 Channel Assignment The VMS application program must assign a channel to the device driver before any I/O can take place. To do this, the program uses the SYS$ASSIGN system service. The format of this system service is shown in Section 4.2.1 on page 61. Once a VMS program assigns a channel to an ICP, it has access to all communication ports on that ICP. A program can access more than one ICP by assigning a separate channel for each board.
4: Application Interface 4.1.2.2 I/O Status Block (IOSB) The programmer should always check the status field (first word) of the I/O Status Block (IOSB) after each QIO completion. This field returns a VMS completion code or error code that indicates the success of the call or reason for failure. The return codes used by the ICP device driver are described in Section 4.2.4.6 on page 71.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) transfers include at least a protocol header, each buffer read from the ICP contains at least the size of that header. 4.1.2.4 Node Numbers (P4) Once a channel is assigned to the ICP device name, data is directed to individual ports (links) on that ICP through the use of a node number in the P4 parameter of the QIO call. A node number represents a logical full-duplex path to the protocol software on the ICP.
4: Application Interface have the ability to revert to an earlier node number scheme used by Simpact’s ICP3222 and Digital’s Commserver products. This scheme connects a single node number to each ICP port. Whatever node number scheme or protocol you use, it is transparent to the VMS device driver. More information about protocol specifics can be found in Chapter 5. 4.2 Supported VMS System Services The ICP2432 device driver supports the VMS system services described in the following sections. 4.2.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 4.2.2 SYS$CANCEL To cancel all active or pending read or write requests associated with an I/O channel, the application issues the VMS SYS$CANCEL call. See the VMS system services manual for a detailed description. Synopsis SYS$CANCEL ( channel ) Parameters channel Communication channel 4.2.3 SYS$DASSGN To terminate its association with an ICP device, the application issues the VMS SYS$DASSGN call for the channel associated with the ICP.
4: Application Interface 4.2.4 SYS$QIO(W) To issue VMS read or write I/O calls, the client application issues the VMS SYS$QIOW or SYS$QIO calls (for I/O with, or without wait). See the VMS system services manual for a detailed description of SYS$QIOW and SYS$QIO.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 3. IO$_STARTMPROC 4. IO$_READVBLK , IO$_READLBLK, IO$_READPBLK 5. IO$_WRITEVBLK, IO$_WRITELBLK, IO$_WRITEPBLK All functions are handled as direct I/O using DMA transfer.
4: Application Interface 4.2.4.1 IO$_INITIALIZE[|IO$M_NOWAIT] The IO$_INITIALIZE function initializes the ICP2432. Condition Values Returned SS$_NORMAL Initialization completed successfully SS$_CANCEL Request canceled SS$_CTRLERR Request not completed; a fatal error occurred SS$_TIMEOUT Request timed out; no response from ICP The transfer count and device-specific information of the I/O Status Block (IOSB) are not used. Parameters None.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 4.2.4.2 IO$_LOADMCODE The IO$_LOADMCODE function loads a software block onto the ICP2432. Condition Values Returned Decreased size above Condition, Parameters, and Description to get Description on this page.
4: Application Interface 4.2.4.3 IO$_STARTMPROC The IO$_STARTMPROC function starts the ICP2432 software. Condition Values Returned SS$_NORMAL Request completed successfully SS$_BADPARAM Parameter is incorrect SS$_CANCEL Request canceled SS$_INVMODE Software was not downloaded SS$_TIMEOUT Request timed out; no response from ICP The transfer count and device-specific information of the I/O Status Block (IOSB) are not used.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 4.2.4.4 IO$_STARTDATA The IO$_STARTDATA function sets the node number of the read request for this channel number. Condition Value Returned SS$_NORMAL Request completed successfully SS$_ILLSEQIOOP Driver was not in node auto-assignment mode SS$_INVMODE Software was not downloaded The device-specific information of the I/O Status Block (IOSB) is set to the node number assigned by the driver.
4: Application Interface 4.2.4.5 IO$_SENSEMODE The IO$_SENSEMODE function returns the driver information. Condition Value Returned SS$_NORMAL Request completed successfully SS$_ACCVIO Buffer does not allow write access SS$_BADPARAM Parameter is incorrect The transfer count of the I/O Status Block (IOSB) is set, but the device-specific information of the IOSB is not used.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) typedef struct { int TimeoutValue; /* Timeout value for the SingleStepDriver */ int Node; int IcpWasReset; /* Node number corresponding to file handle. */ /* ICP has been reset since handle opened. */ int DeviceNumber; int NumberOfPorts; int IcpState; int BufferAlignment; int NumberOfChannel; /* Device number to which handle is opened. */ /* Number of ports on the ICP. */ /* Current state of the ICP. */ /* Alignment requirement for I/O buffers.
4: Application Interface 4.2.4.6 IO$_READxBLK[|IO$M_ABORT] The IO$_READxBLK function reads a packet from the ICP2432 firmware. The IO$_READxBLK|IO$M_ABORT function cancels the IO$_READxBLK function already requested on the same channel number.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) Description The driver accesses user virtual address space (specified by the P1 parameter) to access the packet. The packet must be set on a longword boundary. The read and write node numbers are used for communication between the driver and the ICP2432. The node numbers decide the source and destination of messages. Allowable values are 1 through 126. The read node number of P4 is bit 0 through bit 7.
4: Application Interface 4.2.4.7 IO$_WRITExBLK[|IO$M_ABORT] The IO$_WRITExBLK function writes a packet to the ICP2432 firmware. The IO$_WRITExBLK|IO$M_ABORT function cancels the IO$_WRITExBLK function already requested on the same channel number.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) Description The driver accesses user virtual address space (specified by the P1 parameter) to access the packet. The packet must be set on a longword boundary. The read and write node numbers are used for communication between the driver and the ICP2432. The node numbers decide the source and destination of messages. Allowable values are 1 through 126. The read node number of P4 is bit 0 through bit 7.
4: Application Interface 4.3 DLI Session Interface Protogate protocols designed for use on ICP2432 boards use a session-based method of communicating between the client application program and the protocol software on the ICP. This method of communication allows greater flexibility in connecting TCP/IP sockets to individual ICP ports for the Freeway line of servers. Protogate’s Data Link Interface (DLI) library uses this session-based interface on both the Freeway server and embedded ICP boards.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 4.3.2.1 Node 1 Node 1 is the primary node number to which all data is written. The VMS driver allows multiple programs to write to the same node number. The P4 parameter in the QIO call should be 0x0101 for all writes. 4.3.2.2 Node 2 Node 2 is the alternate write node. Its use varies per protocol. In some documents, node 2 is referred to as the “express node” for sending priority packets to the ICP.
4: Application Interface 4.3.3.1 ATTACH Command The ATTACH command creates a session between your program and the protocol software on the ICP.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 4.3.3.2 DETACH Command The DETACH command closes an individual session between your program and the protocol software on the ICP.
4: Application Interface 4.3.3.3 TERMINATE Command The TERMINATE command closes all sessions that use a particular read node number.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) Follow these steps to use the node auto-assignment: 12/3/98 Leslie: Ginni had the first part of the first bullet underlined, but no note. 1. Download the protocol software with set the flag of IO$_STARTMPROC function. (When the icpload utility is used, set the /DLITE qualifier on the START command. See Section 6.4.3.4 on page 97 for more information about the START command.) 2. The application assigns the device and gets the channel number. 3.
4: Application Interface mends that you use the DLI session interface so that you can also use the protocol image in a Freeway environment.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 82 DC 900-1516D
Chapter 5 Roger — Bill Reid’s review comment was “What is this and why is it?” Maybe it’s redundant now that we are putting all the packet info in the protocol documents ...Leslie ICP Packet Formats This chapter describes the packet formats used by Protogate protocols. The packet formats that are written to the ICP2432 are the same whether the ICP is attached to a Freeway server or a PCI bus in your VMS system.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) typedef struct _ICP_PACKET { ICP_HDR icp_hdr; PROT_HDR prot_hdr; char *data; } ICP_PACKET; typedef struct _ICP_HDR { unsigned short usICPClientID; unsigned short usICPServerID; unsigned short usICPCount; unsigned short usICPCommand; short iICPStatus; unsigned short usICPParms[3]; } ICP_HDR; typedef struct _PROT_HDR { unsigned short usProtCommand; short iProtModifier; unsigned short usProtLinkID; unsigned short usProtCircuitID; unsigned short usProtSe
5: ICP Packet Formats 5.2 DLI Optional Arguments A program using the full DLI library interface to an ICP on a Freeway server is not allowed to write information directly to the ICP and Protocol headers. Instead, Freeway users place the desired values in a DLI_OPT_ARGS structure and the DLI write call moves these values into the proper places in the ICP and Protocol headers. The same applies to DLI read calls.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) typedef struct _DLI_OPT_ARGS { unsigned short usFWPacketType; unsigned short usFWCommand; unsigned short usFWStatus; unsigned short usICPClientID; unsigned short usICPServerID; unsigned short usICPCommand; short iICPStatus; unsigned short usICPParms[3]; unsigned short usProtCommand; short iProtModifier; unsigned short usProtLinkID; unsigned short usProtCircuitID; unsigned short usProtSessionID; unsigned short usProtSequence; unsigned short usProtXPar
5: ICP Packet Formats Table 5–1: Comparison of DLI_OPT_ARGS and ICP_PACKET Structures DLI_OPT_ARGS field name ICP_PACKET field name Field Description usFWPacketType omitted Server’s packet type usFWCommand omitted Server’s command sent or received usFWStatus omitted Server’s status of I/O operations usICPClientID icp_hdr.usICPClientID Old su_id usICPServerID icp_hdr.usICPServerID Old sp_id omitted icp_hdr.usICPCount Size of PROT_HDR plus data usICPCommand icp_hdr.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 88 DC 900-1516D
Chapter 6 Roger — Bill Reid’s review comment was “We do not tell the user what this thing is.” It appears adequate to me, but maybe you can add something more user friendly?? ...Leslie ICPLOAD Utility This chapter describes how to use the ICPLOAD program to download the ICP-resident application to the ICP and get or set the driver’s timeout value for the SingleStep debugger (a product of Wind River, Inc.).
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 6.2 OS/Impact and Downloaded Files Software on the ICP2432 executes under control of Protogate’s OS/Impact operating system. The OS/Impact system generation procedure typically creates several different files, each of which must be downloaded to the ICP. A load address is specified for each file; this defines the address at which each file is to be placed within the ICP’s memory. In addition, an execution address is specified for the ICP.
6: ICPLOAD Utility 6.4 Using ICPLOAD.EXE 6.4.1 Invoking ICPLOAD via the RUN Command ICPLOAD.EXE may be invoked via a RUN command from VMS’s DCL prompt. It will then prompt for its first command, as follows: $ RUN ICPLOAD ICPLOAD> ICPLOAD may be executed from a command procedure, in which case it reads com- mands from the lines in the command procedure immediately following the DCL RUN command. 6.4.2 Invoking ICPLOAD as a Foreign Command ICPLOAD may be invoked as a foreign command as follows: 1.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) In the preceding examples, the symbol LDICP was chosen arbitrarily; you can replace this with any symbol you like. If ICPLOAD is invoked as a foreign command without specifying any parameters or qualifiers, the ICPLOAD> prompt will be given and the utility will operate as if it had been invoked via a RUN command. 6.4.3 ICPLOAD Commands The general syntax of ICPLOAD commands is similar to that of DCL commands.
6: ICPLOAD Utility The usual sequence of commands for downloading an ICP is: • RESET the device • LOAD the files to the ICP; the ICP-resident software is usually provided in several different files, and a separate LOAD command is required for each file • START execution of the ICP-resident software The following sections describe the RESET, LOAD, START, and HELP commands in detail. The Format paragraph shows the command with all of its parameters and required qualifiers.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 6.4.3.1 HELP This command provides help at the ICPLOAD command prompt. Format HELP Parameters None Qualifiers None Description The HELP command provides access to the help library ICPLOAD.HLB at the ICPLOAD command prompt. Operation is similar to that for DCL’s HELP. The logical name ICP2432_HELPFILE must exist and must provide a full file specification (including device and directory name) for ICPLOAD.HLB.
6: ICPLOAD Utility 6.4.3.2 RESET This command performs a hardware reset of the ICP. Format RESET device_name Parameters device_name This parameter specifies the ICP device to be reset. Qualifiers None Description The RESET command enables the ICP to be downloaded via a subsequent LOAD command. Your process must have the OPER privilege to use this command. Example ICPLOAD> RESET ZJB0 This command resets the second ICP2432 in the system.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 6.4.3.3 LOAD This command transfers the ICP-resident software from a file on the client system to the ICP. Format LOAD device_name Parameters device_name This parameter specifies the ICP device to be downloaded. Qualifiers /FILE=file_name This qualifier specifies the name of an OS/Impact file. /ADDRESS=address This qualifier specifies the ICP address at which the file is to be loaded.
6: ICPLOAD Utility 6.4.3.4 START This command causes the ICP to begin execution of the downloaded software. Format START device_name /STARTUP=address Parameters device_name This parameter specifies the ICP device to be started. Qualifiers 12/3/98 Leslie: Ginni had the first sentence underlined, but no note. /DLITE This qualifier specifies the driver works for node auto-assignment. See Section 4.4 on page 79 for more information about node auto-assignment.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 6.4.3.5 GET This command gets the driver’s timeout value (in seconds) for the SingleStep debugger. Format GET device_name /TIMEOUT Parameters device_name This parameter specifies the ICP device to get. Qualifiers /TIMEOUT This qualifier specifies the timeout value in seconds. Description The GET command shows the driver’s timeout value for the SingleStep debugger.
6: ICPLOAD Utility 6.4.3.6 SET This command sets the driver’s timeout value (in seconds) for the SingleStep debugger. Format SET device_name /TIMEOUT=timeout_value Parameters device_name This parameter specifies the ICP device to set. Qualifiers /TIMEOUT This qualifier specifies the timeout value in seconds. Description The SET command sets the driver’s timeout value for the SingleStep debugger. Example ICPLOAD> SET ZJA0 /TIMEOUT=5 The example command above sets the timeout value at 5 seconds.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 6.5 ICPLOAD Callable Routines The ICPLOAD.OLB file includes several routines that may be called by a user-written VMS application to affect downloading of an ICP. This section describes how to use these routines. 6.5.1 Conventions The ICPLOAD callable routines are written in C. They may be called from any VMS language that conforms to the Alpha Procedure Calling Standard. Each of these routines returns either a VMS or RMS system service status code.
6: ICPLOAD Utility 6.5.1.1 icpreset This routine causes an ICP to be reset and prepared for a download operation. Format int icpreset (char *device); Returns The completion status of the operation (normally SS$_NORMAL). Arguments DC 900-1516D device: the VMS device name of the ICP.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 6.5.1.2 icpload This routine causes a file to be downloaded to the ICP. This routine is typically used more than once per download sequence (once for each OS/Impact component file). Format int icpload (char *device, char *file, int address); Returns The completion status of the operation; normally SS$_NORMAL. Refer to Chapter 4 for descriptions of status codes returned by the ICP device driver.
6: ICPLOAD Utility 6.5.1.3 icpstart This routine is used to cause an ICP to begin execution of the downloaded code. Format int icpstart( char *device, int address, int flag); Returns The completion status of the operation; normally SS$_NORMAL. Refer to Chapter 4 for descriptions of status codes returned by the ICP device driver. Arguments device: the VMS device name of the ICP. address: starting address for execution. flag: if set to 1, the driver is set for auto node assignment.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) 104 DC 900-1516D
Index A Always QIO support 39 Application how to build for DLITE 41 Application interface 55 Assign a channel 61 ATTACH command 77 Audience 11 Auto-assignment mode 79 B Blocking I/O 41 Building a DLITE application 41 C Callable routines ICPLOAD 100 Callbacks 48 Cancel reads and writes 62 Cancelling I/O 45 cfgerrno global variable 39 Commands HELP 94 ICPLOAD 92 LOAD 96 RESET 95 START 97 Configuration typical system 18 Configuration files 49 raw operation 49 Configuration parameters MaxBuffers 49 MaxBufSize
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) building DLITE application 41 configuration files 49 download select flag 31 embedded versus Freeway 36 environment 37 function changes 42 functions 41 general error file 53 libraries 41 limitations and caveats 38 always QIO support 39 dlInit no longer implied 40 global variables 39 local ack processing 38 raw operation only 38 unsupported functions 40 logging and tracing 52 objectives 37 overview 35 dlOpen 44 dlPoll 44 cancel processing 45 driver inf
Index ICPLOAD callable routines 100 source code 20 ICPLOAD commands 92 ICPLOAD components 89 icpload routine 102 ICPLOAD.EXE 91 ICPLOADVMS.
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) icpload 102 icpreset 101 icpstart 103 ZJDRIVER installation 20 source code 20 S Session commands, DLI 76 Session interface, DLI 75 Sessions opening ICP 44 Software installation (BACKUP saveset) 27 Software installation procedure protocol 21 Software installation procedure (BACKUP saveset) ICP2432 27 Software installation procedure (VMSINSTAL) ICP2432 23 Software installation (VMSINSTAL) 23 START command 97 Start ICP software 67 Structures dlPoll dri
ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) DC 900-1516D Customer Report Form We are constantly improving our products. If you have suggestions or problems you would like to report regarding the hardware, software or documentation, please complete this form and mail it to Protogate at 12225 World Trade Drive, Suite R, San Diego, CA 92128, or fax it to (877) 473-0190. If you are reporting errors in the documentation, please enter the section and page number.
Protogate, Inc.