Realtime Interface Co-Processor
Operating System/2 Support
User's Guide

VERSION 1.03.5 (JUNE 1996)


Table of Contents

About This Guide

  • The Users of This Guide
  • How This Guide Is Organized
  • How to Use This Guide
  • Related Publications
  • Reference Publications
  • Chapter 1. General Product Description

  • Overview
  • Hardware Requirements
  • Software Requirements
  • Chapter 2. Installing the Software

  • Installation Instructions
  • Step 1. Create the Co-Processor Parameter File
  • Step 2. Install the Device Driver
  • Step 3. Install the Realtime Control Microcode
  • Chapter 3. Parameter File Description

  • ICAPARM.PRM Parameter File Definition
  • Parameter File Example
  • System Configuration With a Parameter File
  • System Configuration Without a Parameter File
  • Chapter 4. Device Driver Description

  • Installing the Device Driver
  • Chapter 5. Application Loader Utility

  • Starting the Application Loader
  • Chapter 6. Preparing/Installing Application Tasks

  • Preparing Application Tasks
  • Installing Application Tasks
  • Chapter 7. Dynamic Link Routines

  • Overview
  • ICADevChangePage
  • ICADevGetExtParms
  • ICADevGetInBuf
  • ICADevGetParms
  • ICADevGetSecStatus
  • ICADevGetVersion
  • ICADevInputBuffer
  • ICADevIssueCommand
  • ICADevLock
  • ICADevNotify
  • ICADevOutputBuffer
  • ICADevPeerClose
  • ICADevPeerOpen
  • ICADevPeerReceive
  • ICADevPeerReceiveDone
  • ICADevPeerSend
  • ICADevPrimaryStatus
  • ICADevPutOutBuf
  • ICADevReadString
  • ICADevRegSemaphore
  • ICADevRemNotify
  • ICADevRemSemaphore
  • ICADevReset
  • ICADevSecStatus
  • ICADevTaskFlush
  • ICADevUnLock
  • ICADevWinRelease
  • ICADevWinResNoWait
  • ICADevWinResWait
  • ICADevWriteString
  • Chapter 8. Device Driver Functions

  • Calls to the Device Driver
  • Sample Device Driver Call
  • ChangePage
  • Close
  • GetExtParameters
  • GetInputBuffer
  • GetParameters
  • GetSecondaryStatus
  • GetVersion
  • InputBuffer
  • IssueCommand
  • Lock
  • Notify
  • Open
  • OutputBuffer
  • PeerClose
  • PeerOpen
  • PeerSend
  • PrimaryStatus
  • PutOutputBuffer
  • ReadString
  • RegisterSemaphore
  • RemoveNotify
  • RemoveSemaphore
  • Reset
  • SecondaryStatus
  • TaskFlush
  • UnLock
  • WindowRelease
  • WindowReserveNoWait
  • WindowReserveWait
  • WriteString
  • Chapter 9. Online Dump Facility

  • Starting the Online Dump Facility
  • Output Files
  • Dumping a Co-Processor Adapter
  • Arming a Co-Processor Adapter
  • Restoring a Co-Processor Adapter
  • Arming a Co-Processor Adapter for AutoDump
  • Changing the Dump Drive
  • Chapter 10. Dump Formatter Facility

  • Output Files
  • Dump Formatter Facility Invocation
  • Dump Formatter Facility Profile
  • Profile Parameters
  • Supplied Profile
  • Appendix A. Message List

  • Information Messages
  • Error Messages
  • Appendix B. Tips and Techniques

  • Online Message Help
  • Setting the Shared Storage Window
  • System Configuration
  • Developing Tasks
  • Tasks and System Unit Applications
  • Appendix C. Error Codes

    Appendix D. The Ignore Feature

    INTERNATIONAL BUSINESS MACHINES PROVIDES THIS PUBLICATION "AS IS," WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in revisions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

    It is possible that this publication may contain references to, or information about, IBM products (machines or programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

    (C) Copyright IBM Corporation 1988, 1992
    All rights reserved.


    About This Guide

    This guide provides technical information on installing and using the Realtime Interface Co-Processor OS/2 Support product, which supports the Realtime Interface Co-Processor family of adapters--including:

    Throughout this guide, the term "co-processor adapter" refers to any adapter in the Realtime Interface Co-Processor family of adapters listed above.


    The Users of This Guide

    The information in this guide is intended for software designers, programmers, plant equipment installation personnel, technicians, and anyone who needs to understand the use and operation of the Realtime Interface Co-Processor OS/2 Support.

    The user should be familiar with the system unit and OS/2; therefore, this guide does not explain terminology, except for terms specific to the Realtime Interface Co-Processor family of adapters and the Realtime Control Microcode.


    How This Guide Is Organized

    The Realtime Interface Co-Processor OS/2 Support User's Guide is organized as follows:


    How to Use This Guide

    This guide provides both user's guide and reference information, and should be used with other technical documents for the co-processor adapter.

    The following conventions are used in this guide:


    Related Publications

    Related books in the Realtime Interface Co-Processor library include:


    Reference Publications

    You may need to use one or more of the following publications for reference with this guide:


    Chapter 1. General Product Description


    Overview

    The Realtime Interface Co-Processor OS/2 Support product is a package of program services providing an interface between protect mode programs running under OS/2 and tasks running on the co-processor adapter.

    The OS/2 Support software is intended to be used with both IBM and non-IBM products. IBM does not exercise any control over the hardware or the software of non-IBM products. The user is responsible for determining if the non-IBM products are compatible with the Realtime Interface Co-Processor OS/2 Support software. IBM does not assume any responsibility for selection of any non-IBM products, nor does it give out any information on the products, their performance, price, or maintenance.


    Hardware Requirements

    The following are minimum hardware requirements for the Realtime Interface Co-Processor OS/2 Support product:


    Software Requirements

    The following are minimum software requirements for the Realtime Interface Co-Processor Operating System/2 Support product:


    Chapter 2. Installing the Software

    This chapter provides a guide for installing the software for the IBM co-processor adapter.


    Installation Instructions

    The installation procedures include doing the following:

    During the installation steps, the following apply in explaining commands entered at the OS/2 level:

    Step 1. Create the Co-Processor Parameter File

    The co-processor parameter file, ICAPARM.PRM, is a user-created ASCII file that the device driver uses to initialize the installed co-processor adapters. The file defines the identification parameters for each co-processor adapter installed in the system unit.

    Note:

    The parameter file may be called by any name in the OS/2 environment. ICAPARM.PRM is used as an example name throughout this guide.

    The parameter file is not required for the following co-processor adapters:

    The parameter file may be used, however, to override the MAXTASK, MAXPRI, MAXQUEUE, and MAXTIME configuration parameters for these adapters. (For more information on the default configuration values see "System Configuration With a Parameter File" and "System Configuration Without a Parameter File".)

    Instructions

    Create the parameter file as an ASCII file using a text editor. Include one line (record) of identification parameters for each co-processor adapter installed in the system unit (an example follows). Each record defining a co-processor adapter must:

    The order in which a record is placed in the file determines the logical card number of the co-processor adapter. The first record defines logical co-processor adapter 0; the second record, logical co-processor adapter 1; and so on.

    Note:

    When there is no parameter file, the logical co-processor adapter numbers start with 0 for the co-processor adapter in the lowest-numbered slot in the system unit.

    Example

    The following example shows the parameter file for a system unit with two co-processor adapters installed:

    # 02A0 0 6C 10 10 10 10 0F E010 ; First co-processor adapter
    # 0AA0 0 6D 10 10 10 10 0F E010 $ Last  co-processor adapter
       |   |  |  |  |  |  |  |   |
       |   |  |  |  |  |  |  |   |
       |   |  |  |  |  |  |  |   |
       |   |  |  |  |  |  |  |   +---- Compare degate 1 and 0
       |   |  |  |  |  |  |  +-------- Compare degate 2
       |   |  |  |  |  |  +----------- MAXTIME
       |   |  |  |  |  +-------------- MAXQUEUE
       |   |  |  |  +----------------- MAXPRI
       |   |  |  +-------------------- MAXTASK
       |   |  +----------------------- Page value
       |   +-------------------------- Meg value
       +------------------------------ Co-processor adapter
                                       I/O address
    
    For more information on the parameters, see "Chapter 3. Parameter File Description".

    Step 2. Install the Device Driver

    The device driver must be invoked through the CONFIG.SYS file after system reset or start-up. To invoke the device driver using the CONFIG.SYS file:

    1. Add the following line to the CONFIG.SYS file:
         device=[d:][\path1\]ICARICIO.SYS [[d:][\path2\]configfile]
      
      where:

      d:
      is the drive.

      path1
      is the path to the ICARICIO.SYS device driver file.

      path2
      is the path to the parameter file.

      configfile
      is the name of the parameter file (typically ICAPARM.PRM).
      Note:
      Additional device driver parameters may be specified for disabling the device driver's "system unit reboot" feature and invoking the "ignore a co-processor adapter" feature. For information on these parameters, see Chapter 4.

    2. Ensure that the ICA.MSG message file is located in a directory in the DPATH variable in CONFIG.SYS.

    3. Reset the system to install the device driver in system unit memory. The following messages should be displayed:
          IBM Realtime Interface Co-Processor OS/2 Support
          Copyright IBM Corp. 1988, 1992
          ICARICIO.SYS initializing co-processor adapters
          ICARICIO.SYS installed and running
      
    If a different set of messages is displayed, refer to Appendix A. "Message List" in this manual for recommended action.

    For further information on the device driver, refer to "Chapter 4. Device Driver Description".

    Step 3. Install the Realtime Control Microcode

    The IBM Realtime Control Microcode is the control program for the co-processor adapter and must be loaded on the co-processor adapter before any user tasks are loaded. The Realtime Control Microcode's file name is either ICAAIM.COM or ICARCM.COM, as described under the instructions that follow. The Realtime Control Microcode is provided on diskette and packaged with your co-processor adapter's guide to operations document. The application loader utility (ICALDRC.COM) is used to load the Realtime Control Microcode onto the co-processor adapter. (For more information on the application loader, see "Chapter 5. Application Loader Utility".)

    Instructions

    For the Realtime Interface Co-Processor, the Realtime Interface Co-Processor Multiport, the Realtime Interface Co-Processor Multiport/2, and the X.25 Interface Co-Processor/2, use the following command to load the Realtime Control Microcode onto the co-processor adapter:

    > ICALDRIC n1 ICAAIM.COM 0

    For the Realtime Interface Co-Processor Portmaster Adapter/A and the Realtime Interface Co-Processor Multiport Adapter, Model 2, use the following command to load the Realtime Control Microcode to the co-processor adapter:

    > ICALDRIC n1 ICARCM.COM 0

    The logical co-processor adapter number (n1) is determined by the order in which the co-processor's identification record appears in the ICAPARM.PRM file, starting with a decimal 0 for the first record.

    Note:

    When there is no ICAPARM.PRM file, the logical co-processor adapter numbers start with a decimal 0 for the co-processor adapter in the lowest-numbered slot in the system unit.
    The 0 at the end of the command line is the task number; Realtime Control Microcode must always be loaded as task 0. If the Realtime Control Microcode is successfully loaded, the following message is displayed:

    Normal termination. Task 00 loaded on coproc nn.

    If a different message is displayed, see Appendix A. "Message List" for the corrective action.

    Note:

    If you are also installing the IBM Realtime Interface Co-Processor Extended Services product, you can install it at this point. For installation instructions for the Extended Services product, see the Realtime Interface Co-Processor Extended Services User's Guide, or the Realtime Interface Co-Processor Extended Services License Information and Starting Instructions booklet.

    Chapter 3. Parameter File Description

    This chapter provides a detailed description of the user-created parameter file (ICAPARM.PRM), which tells the device driver how to initialize the installed co-processor adapters.

    Note:

    The parameter file may be called by any name in the OS/2 environment. ICAPARM.PRM is used as an example name throughout this guide.

    The ICAPARM.PRM file is not required for the following co-processor adapters:

    A parameter file may be created to override the MAXTASK, MAXPRI, MAXQUEUE, and MAXTIME configuration parameters for the adapter. The defaults are described under "System Configuration With a Parameter File" and "System Configuration Without a Parameter File".

    ICAPARM.PRM Parameter File Definition

    The ICAPARM.PRM file is a user-created ASCII file that defines identification parameters for the co-processor adapter installed in your system unit. The file consists of one record (line) for each co-processor adapter.

    The general rules to consider when defining the ICAPARM.PRM file are that:

    +----------+----------------------+--------+-----------------+
    |          |       Field          | Field  |                 |
    |  Field   |       Name           | Size   |  Value/Range    |
    +----------+----------------------+--------+-----------------+
    |          |  Beginning record    |   -    |        #        |
    |          |  delimiter           |        |                 |
    +----------+----------------------+--------+-----------------+
    |   1      |  Co-processor adapter|        |                 |
    |          |  base I/O address    | Word   |  02A0h - 3EA0h  |
    +----------+----------------------+--------+-----------------+
    |   2      |  Meg Value           | Byte   |    00h - 0Fh    |
    +----------+----------------------+--------+-----------------+
    |   3      |  Page Value          | Byte   |    00h - 7Fh    |
    +----------+----------------------+--------+-----------------+
    |   4      |  MAXTASK             | Byte   |    00h - F8h    |
    +----------+----------------------+--------+-----------------+
    |   5      |  MAXPRI              | Byte   |    01h - FFh    |
    +----------+----------------------+--------+-----------------+
    |   6      |  MAXQUEUE            | Byte   |    00h - FEh    |
    +----------+----------------------+--------+-----------------+
    |   7      |  MAXTIME             | Byte   |    00h - FEh    |
    +----------+----------------------+--------+-----------------+
    |   8      |  Compare degate 2    | Byte   |    00h - FFh    |
    +----------+----------------------+--------+-----------------+
    |   9      |  Compare degate 1    | Word   |  0000h - FFFFh  |
    |          |  and 0               |        |                 |
    +----------+----------------------+--------+-----------------+
    |          |  Ending record       |   -    |  If last        |
    |          |  delimiter           |        |  co-processor   |
    |          |                      |        |  adapter,       |
    |          |                      |        |  $, else ;      |
    +----------+----------------------+--------+-----------------+
    

    Parameter File Example

    The following example shows the parameter file for a system unit with two co-processor adapters installed.

    # 02A0 00 6C 10 10 10 10 0F E010 ; First co-processor adapter
    # 0AA0 00 6D 10 10 10 10 0F E010 $ Last  co-processor adapter
       |   |  |  |  |  |  |  |   |
       |   |  |  |  |  |  |  |   |
       |   |  |  |  |  |  |  |   |
       |   |  |  |  |  |  |  |   +---- Compare degate 1 and 0
       |   |  |  |  |  |  |  +-------- Compare degate 2
       |   |  |  |  |  |  +----------- MAXTIME
       |   |  |  |  |  +-------------- MAXQUEUE
       |   |  |  |  +----------------- MAXPRI
       |   |  |  +-------------------- MAXTASK
       |   |  +----------------------- Page value
       |   +-------------------------- Meg value
       +------------------------------ Co-processor adapter
                                       I/O address
    
    In the preceding example, the meg value of 0 and the page value of 6Ch in the first line indicate that the co-processor adapter's shared window is located at physical address 0D8000h. The meg value of 0 and the page value of 6Dh in the second line indicate that the co-processor adapter's shared storage window is located at physical address 0DA000h. The compare degate values of 0Fh and E010h indicate that the co-processor adapters will reset if physical address 0FE010h is accessed on the system unit. Physical address 0FE010h is an address in ROM accessed during system restart.

    The Programmable Option Select (POS), part of the Personal System/2 architecture, configures part of the Realtime Interface Co-Processor Multiport/2, X.25 Interface Co-Processor/2 and Realtime Interface Co-Processor Portmaster Adapter/A. POS replaces jumpers and switches used for initializing hardware adapters. The Meg and Page fields are initialized by POS and override the values entered in the parameter file. See the IBM Realtime Interface Co-Processor Multiport/2 Guide to Operations, the IBM Realtime Interface Co-Processor Portmaster Adapter/A Guide to Operations, the IBM Realtime Interface Co-Processor Firmware Technical Reference and the IBM Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport, Realtime Interface Co-Processor Multiport/2 Technical Reference and X.25 Interface Co-Processor Technical Reference for more information on POS.

    Parameter Field Definitions

    This section defines each parameter field of the ICAPARM.PRM file.

    Beginning Record Delimiter
    +---------------+------------------------------------------+
    |   Length      | One character # (number sign)            |
    +---------------+------------------------------------------+
    |   Range       | #                                        |
    +---------------+------------------------------------------+
    |   Description | The first character of each record must  |
    |               | be a #.                                  |
    +---------------+------------------------------------------+
    
    Co-Processor Adapter Base I/O Address
    +---------------+-----------+------------------------------+
    |   Length      |  Word     |     Physical Co-Processor    |
    |               |           |         Adapter Number       |
    +---------------+-----------+------------------------------+
    |   Value       |  02A0h    |    Co-Processor Adapter 0    |
    |               |  06A0h    |    Co-Processor Adapter 1    |
    |               |  0AA0h    |    Co-Processor Adapter 2    |
    |               |  0EA0h    |    Co-Processor Adapter 3    |
    |               |  12A0h    |    Co-Processor Adapter 4    |
    |               |  16A0h    |    Co-Processor Adapter 5    |
    |               |  1AA0h    |    Co-Processor Adapter 6    |
    |               |  1EA0h    |    Co-Processor Adapter 7    |
    |               |  22A0h    |    Co-Processor Adapter 8    |
    |               |  26A0h    |    Co-Processor Adapter 9    |
    |               |  2AA0h    |    Co-Processor Adapter 10   |
    |               |  2EA0h    |    Co-Processor Adapter 11   |
    |               |  32A0h    |    Co-Processor Adapter 12   |
    |               |  36A0h    |    Co-Processor Adapter 13   |
    |               |  3AA0h    |    Co-Processor Adapter 14   |
    |               |  3EA0h    |    Co-Processor Adapter 15   |
    +---------------+-----------+------------------------------+
    |   Description | This value is set by the switches of     |
    |               | the Realtime Interface Co-Processor,     |
    |               | the Realtime Interface Co-Processor      |
    |               | Multiport and the Interface Co-Processor |
    |               | Multiport Adapter, Model 2.              |
    |               | When using the Realtime Interface Co-    |
    |               | Processor Multiport/2, X.25 Interface    |
    |               | Co-Processor/2, and Realtime Interface   |
    |               | Co-Processor Portmaster Adapter/A, this  |
    |               | value is selected with the reference     |
    |               | diskette for your system unit.           |
    |               | See the IBM Realtime Interface     |
    |               | Co-Processor Multiport/2 Guide to        |
    |               | Operations for more information.  |
    |               | Starting at this value, eight input/     |
    |               | output addresses are used.               |
    +---------------+------------------------------------------+
    
    Megabyte Value
    +---------------+------------------------------------------+
    |   Length      | Byte                                     |
    +---------------+------------------------------------------+
    |   Range       | 00h - 0Fh                                |
    +---------------+------------------------------------------+
    |   Description | The megabyte value indicates which       |
    |               | megabyte of system unit storage is       |
    |               | used for the co-processor adapter's      |
    |               | window.  A megabyte value of 0 indicates |
    |               | that the window is located in the        |
    |               | first megabyte of system unit storage.   |
    |               | A value of 1 indicates that the window   |
    |               | is located in the second megabyte of     |
    |               | system unit storage.  See the note in    |
    |               | the "Page Value" section regarding       |
    |               | placement of the window.                 |
    |               | When using the Realtime Interface Co-    |
    |               | Processor Multiport/2, X.25 Interface    |
    |               | Co-Processor/2 and Realtime Interface    |
    |               | Co-Processor Portmaster Adapter/A,       |
    |               | this value is overridden by the value    |
    |               | selected with the reference diskette for |
    |               | your system unit.                        |
    +---------------+------------------------------------------+
    
    Page Value
    +---------------+------------------------------------------+
    |   Length      | Byte                                     |
    +---------------+------------------------------------------+
    |   Range       | 00h - 7Fh                                |
    +---------------+------------------------------------------+
    |   Description | The page value is an offset (in          |
    |               | increments of 8KB) within the megabyte   |
    |               | specified by the megabyte value.  This   |
    |               | value indicates the location of the      |
    |               | co-processor adapter's shared storage    |
    |               | window within the specified megabyte.  A |
    |               | page value of 0 indicates the window     |
    |               | is located at the beginning of the       |
    |               | megabyte specified by the megabyte value.|
    |               | When assigning the location of the co-   |
    |               | processor, the adapter's shared storage  |
    |               | window should not overlap the window of  |
    |               | another co-processor adapter.  In        |
    |               | addition, regions are 128KB wide and are |
    |               | defined by the type of memory devices    |
    |               | that reside in those regions.  If a      |
    |               | co-processor adapter is configured as an |
    |               | 8-bit device, it cannot reside in the    |
    |               | same 128KB region as a 16-bit device.    |
    |               | Conversely, if a co-processor adapter is |
    |               | configured as a 16-bit device, it cannot |
    |               | reside in the same 128KB region as an    |
    |               | 8-bit device.                            |
    |               | When using the Realtime Interface Co-    |
    |               | Processor Multiport/2, X.25 Interface    |
    |               | Co-Processor/2 and Realtime Interface    |
    |               | Co-Processor Portmaster Adapter/A,       |
    |               | this value is selected with the          |
    |               | reference diskette for your system unit. |
    +---------------+------------------------------------------+
    
    MAXTASK
    +---------------+------------------------------------------+
    |   Length      | Byte                                     |
    +---------------+------------------------------------------+
    |   Range       | 00h - F8h                                |
    +---------------+------------------------------------------+
    |   Description | This is the highest task number that can |
    |               | be loaded on a given co-processor        |
    |               | adapter.  Task 0 is reserved for the     |
    |               | Realtime Control Microcode.  This value  |
    |               | should be selected carefully to avoid    |
    |               | reserving unnecessary space in the       |
    |               | Realtime Control Microcode's data area.  |
    +---------------+------------------------------------------+
    
    MAXPRI
    +---------------+------------------------------------------+
    |   Length      | Byte                                     |
    +---------------+------------------------------------------+
    |   Range       | 01h - FFh                                |
    +---------------+------------------------------------------+
    |   Description | This is the highest priority level that  |
    |               | may be assigned to a task loaded on this |
    |               | co-processor adapter.  This value should |
    |               | be selected carefully to avoid reserving |
    |               | unnecessary space in the Realtime Control|
    |               | Microcode's data area.                   |
    +---------------+------------------------------------------+
    
    MAXQUEUE
    +---------------+------------------------------------------+
    |   Length      | Byte                                     |
    +---------------+------------------------------------------+
    |   Range       | 00h - FEh                                |
    +---------------+------------------------------------------+
    |   Description | This is the highest queue number         |
    |               | available for application tasks          |
    |               | executing on the co-processor adapter.   |
    |               | This value should be selected            |
    |               | carefully to avoid reserving unnecessary |
    |               | space in the Realtime Control            |
    |               | Microcode's data area.                   |
    +---------------+------------------------------------------+
    
    MAXTIME
    +---------------+------------------------------------------+
    |   Length      | Byte                                     |
    +---------------+------------------------------------------+
    |   Range       | 00h - FEh                                |
    +---------------+------------------------------------------+
    |   Description | This is the highest timer number         |
    |               | reserved for application tasks           |
    |               | executing on the given co-processor      |
    |               | adapter.  This value should be           |
    |               | selected carefully to avoid reserving    |
    |               | unnecessary space in the Realtime Control|
    |               | Microcode's data area.                   |
    +---------------+------------------------------------------+
    
    Compare Degate 2
    +---------------+------------------------------------------+
    |   Length      | Byte                                     |
    +---------------+------------------------------------------+
    |   Range       | 00h - FFh                                |
    +---------------+------------------------------------------+
    |   Description | When this address, in conjunction with   |
    |               | Compare Degate 1 and 0, is accessed by   |
    |               | the system unit, the co-processor        |
    |               | adapter's shared storage window          |
    |               | automatically degates from the system    |
    |               | unit memory bus.                         |
    |               | If the system unit architecture          |
    |               | only supports 1 megabyte of memory,      |
    |               | this parameter is limited to 00h - 0Fh.  |
    |               | 00h - FFh is valid only in a system      |
    |               | designed for 16 megabytes of memory.     |
    |               | This field should have a value of 0      |
    |               | to disable the feature.                  |
    |               | The Compare Degate fields are undefined  |
    |               | on the Realtime Interface Co-Processor   |
    |               | Multiport/2, the X.25 Interface Co-      |
    |               | Processor/2 the and Realtime Interface   |
    |               | Co-Processor Portmaster Adapter/A.       |
    |               | Shared storage automatically degates     |
    |               | from the system unit bus when the        |
    |               | system is re-booted without turning off  |
    |               | the system (soft reset).                 |
    |               |                                          |
    |               | For a list of the recommended addresses, |
    |               | see "Recommended Compare Degate          |
    |               | Addresses," later in this section.       |
    +---------------+------------------------------------------+
    
    Compare Degate 1 and 0
    +---------------+------------------------------------------+
    |   Length      | Word                                     |
    +---------------+------------------------------------------+
    |   Range       | 0000h - FFFFh                            |
    +---------------+------------------------------------------+
    |   Description | When this address, in conjunction with   |
    |               | Compare Degate 2, is accessed by the     |
    |               | system unit, the co-processor adapter    |
    |               | automatically degates its shared         |
    |               | storage window from the system unit      |
    |               | bus (see "Compare Degate 2").  To        |
    |               | disable this feature, the field has      |
    |               | a value of 0.                            |
    |               |                                          |
    |               | For a list of the recommended addresses, |
    |               | see the following chart.                 |
    +---------------+------------------------------------------+
    

    Recommended Compare Degate Addresses

    Following are the recommended Compare Degate addresses for the ICAPARM.PRM file definition:

    +------------------------+-----------------+----------------+
    |System unit             | Compare Degate  | Compare Degate |
    |                        |       2         |    1 and 0     |
    +------------------------+-----------------+----------------+
    |IBM 5531, 7531, or 7532 |       0F        |     E010       |
    |Industrial Computer;    |                 |                |
    |PC XT; PC AT; PS/2      |                 |                |
    |Model 25 or 30;         |                 |                |
    |IBM 5531, 7531 and      |                 |                |
    |7532 Industrial         |                 |                |
    |Computer                |                 |                |
    +------------------------+-----------------+----------------+
    |IBM 7552 Industrial     |       0C        |     0000       |
    |Computer                |                 |                |
    +------------------------+-----------------+----------------+
    |IBM 7541, 7542, 7561    |       Any       |     Any        |
    |7562 and 7568           |       value     |     value      |
    |Industrial              |                 |                |
    |Computer;               |                 |                |
    |PS/2 Model 50, 50Z      |                 |                |
    |55, 60, 70, or 80       |                 |                |
    +------------------------+-----------------+----------------+
    
    Ending Record Delimiter
    +---------------+------------------------------------------+
    |   Length      | 1 character                              |
    +---------------+------------------------------------------+
    |   Range       | ; or $                                   |
    +---------------+------------------------------------------+
    |   Description | The last character in the definition     |
    |               | record for a co-processor adapter should |
    |               | be a ; (semicolon). If this is the last  |
    |               | record in the file, the last character   |
    |               | should be a $ (dollar sign). If a system |
    |               | does not have the $ character, the ASCII |
    |               | equivalent of $ (24h) should be used.    |
    +---------------+------------------------------------------+
    

    System Configuration With a Parameter File

    If a parameter file is defined, the device driver first processes the co-processor adapters listed in that file. The first entry in the parameter file defines logical co-processor adapter 0; the second entry, logical co-processor adapter 1; and so on. After the parameter file entries are processed, the device driver scans the system unit slots for additional Realtime Interface Co-Processor Multiport/2, Realtime Interface Co-Processor Portmaster Adapter/A, and X.25 Interface Co-Processor/2 adapters. (These adapters do not require a parameter file.) If additional adapters from this group are installed, they are configured to the default values that follow, and are assigned logical card numbers following the numbers of the adapters defined in the parameter file. Numbering continues with the co-processor adapter in the lowest-numbered slot in the system unit and proceeds in ascending order.

    For example, if the configuration file contains the following:

    #    0AA0    00    6C    10    10    10    10    0F    E010;
    #    06A0    00    6D    10    10    10    10    0F    E010$
    
    and the slots are configured as follows:
        Slot          Co-Processor at base address
    ----------------------------------------------------
          1                     02A0
          2                     0AA0
          3                     06A0
          4                     0EA0
    
    The logical card number assignments are:
        Logical Card          Base Address
        Number
    -------------------------------------------
            0                    0AA0
            1                    06A0
            2                    02A0
            3                    0EA0
    

    System Configuration Without a Parameter File

    If no parameter file is used, the device driver initializes the Realtime Interface Co-Processor Multiport/2, the Realtime Interface Co-Processor Portmaster Adapter/A and the X.25 Interface Co-Processor/2 adapters to the following default values:

    I/O Base Address:
    This value is read from the card's POS registers. They should be set with the system unit Reference Diskette.

    Window Location (Meg and Page):
    These values are read from the card's POS registers. They should be set with the system unit Reference Diskette.

    MAXTASK:
    Set to default value of 0x10 (decimal 16).

    MAXPRI:
    Set to default value of 0x10 (decimal 16).

    MAXQUEUE:
    Set to default value of 0x50 (decimal 80).

    MAXTIME:
    Set to default value of 0x32 (decimal 50).

    Compare Degate Address:
    Undefined. Adapter storage automatically degates after a soft reset of the host on the Realtime Interface Co-Processor Multiport/2, X.25 Interface Co-Processor/2, and the Realtime Interface Co-Processor Portmaster Adapter/A adapters.

    If these defaults do not meet the requirements of your system configuration, create an entry in the parameter file to override the defaults. A parameter file is required for the Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport, and the Realtime Interface Co-Processor Multiport Adapter, Model 2.


    Chapter 4. Device Driver Description

    This chapter provides a detailed description of the device driver. The Realtime Interface Co-Processor Operating System/2 Support device driver (ICARICIO.SYS) provides a software interface to the co-processor adapters. The device driver's main functions:


    Installing the Device Driver

    The device driver must be invoked through the CONFIG.SYS file after system reset or start-up. To invoke the device driver using the CONFIG.SYS file:

    1. Add the following line to the CONFIG.SYS file:
         device=[d:][\path1\]ICARICIO.SYS [[d:][\path2\]configfile]
                [-R][I(X,Y,Z)]
      
      where:

      d:
      is the drive

      path1
      is the path to the ICARICIO.SYS device driver file.

      path2
      is the path to the parameter file.

      configfile
      is the name of the parameter file (typically ICAPARM.PRM).

      -R
      causes the device driver's (icaricio.sys) "system unit reboot" feature to be disabled. The Realtime Interface Co-Processor provides the capability to allow software on the card to re-IPL the system unit. The -R option can be used to disable that feature.

      I
      signifies the user would like to invoke the "ignore a co-processor adapter" feature.

      (X,Y,Z)
      are the physical card numbers of the co-processor adapters the user wants to ignore.

      Note:

      A co-processor adapter that appears in the ICAPARM.PRM (parameter) file will not be ignored. Therefore, if a card you want to ignore appears in your ICAPARM.PRM file, the card's entry must be removed from that file.

      For more information on the ignore feature, see Appendix D.

    2. Ensure that the ICA.MSG message file is located in a directory in the DPATH variable in CONFIG.SYS.

    3. Reset the system to install the device driver in system unit memory. The following messages should be displayed:
          IBM Realtime Interface Co-Processor OS/2 Support
          Copyright IBM Corp. 1988, 1992
          ICARICIO.SYS initializing co-processor adapters
          ICARICIO.SYS installed and running
      

    If a different set of messages is displayed, refer to Appendix A. "Message List" in this manual for recommended action.


    Chapter 5. Application Loader Utility

    The application loader utility (ICALDRIC.EXE) is used to load the Realtime Control Microcode and tasks to the co-processor adapter. The loader utility can be invoked from the keyboard, a .CMD file, or it may be called from another program using OS/2 facilities.

    Note:

    The device driver (ICARICIO.SYS) must be loaded before the application loader is invoked. See Chapter 2, "Installing the Software" for information on loading the device driver.

    The first task loaded onto a co-processor adapter must be the Realtime Control Microcode (file ICAAIM.COM or ICARCM.COM), provided with the co-processor adapter. After the Realtime Control Microcode is loaded, the user may load applications or other tasks onto the co-processor adapter. Each task must have a unique task number that is assigned when the task is loaded. The MAXTASK field in the parameter file (ICAPARM.PRM) defines the highest task number under which a task can be loaded. (For additional information on the parameter file, see Chapter 3, "Parameter File Description.")

    The following example loads the Realtime Control Microcode onto co-processor adapter 0:

    > ICALDRIC 0 ICAxxx.COM 0

    Where xxx = AIM for Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport, Realtime Interface Co-Processor Multiport/2, or &ric3.; xxx = RCM for Realtime Interface Co-Processor Portmaster Adapter/A or Realtime Interface Co-Processor Multiport Adapter, Model 2.

    The first 0 (decimal) represents the first logical co-processor adapter as defined in the parameter file. The last 0 (decimal) represents the task number, which is always 0 for the Realtime Control Microcode.

    Realtime Control Microcode Version 1.x (ICAAIM.COM) does not support the passing of parameters.

    Realtime Control Microcode Version 2.x (ICARCM.COM) supports the following parameters:

    Note:

    Parameters 1 and 2 may be used at the same time by separating the parameters with a blank. For example: These parameters may be passed together and in any order; that is, they are not mutually exclusive and not order dependent.

    The loader can load .EXE or .COM files only. The maximum length of a COM file is 64KB bytes, while the length of an EXE file is restricted by the amount of free storage on the co-processor adapter at the time the load is attempted.

    The loader sets up the initial values for the Code Segment Register, Data Segment Register, Stack Segment Register, and Stack Pointer Register in the task header.


    Starting the Application Loader

    The application loader requires command line parameters, shown following, to indicate which task to load and how it should be loaded. The first three parameters are required; while the remaining parameters are shown within brackets to indicate that they are optional. The brackets cannot be used in the actual invocation line.

    The parameters must appear in the order in which they are listed in the following paragraphs. Each parameter must be separated by either a space or a comma. If a parameter is to be skipped but a later parameter is to be used, a comma must be used in place of the skipped parameter. (Examples follow the parameter descriptions.)

    The loader parameters are:

    ICALDRIC CO-PROC_NUM,TASK_FILE,TASK_NUM[,START][,LOW/HIGH]
    [,BOUND][,MSG][(PARMS]
    Where
    ICALDRIC
    The name of the loader program.
    CO-PROC_NUM
    The logical co-processor adapter number (decimal) where the task is to be loaded. The logical adapter number is determined by the position of this co-processor adapter's descriptor in the parameter file. This parameter is required.
    TASK_FILE
    The file name, including the extension, of the task to be loaded. A drive and path may be specified if the task is not in the current directory. This parameter is required.
    TASK_NUM
    The task number to be assigned to the task to to be loaded. Realtime Control Microcode must be loaded as task 0 (decimal). Application tasks may be loaded in the decimal range of 1 to the MAXTASK value, as assigned in the ICAPARM.PRM file. This parameter is required.
    START
    The start flag. The letter "S" indicates that the task should be started after it is loaded. The letter "L" indicates that the task should only be loaded. If this parameter is not used, the task is started by default.
    LOW/HIGH
    The flag for loading in high or low co-processor adapter memory. Specify the string HIGH to load the task at the highest possible address and LOW to load the task at the lowest possible address. The default load location in co-processor adapter storage is the highest possible address.

    Note:

    RCM V1.3 or greater must be installed to use this option.
    BOUND
    The memory boundary in paragraphs that the task should be loaded on. The default task load boundary is one paragraph (16 bytes). If a boundary other than one paragraph is required, the required boundary can be entered in this parameter. The boundary must be an exact power of 2 (only one bit on in the entire word).
    MSG
    The message flag. If this parameter is not specified, messages are displayed by default. The letter "N" indicates that application loader messages should be suppressed.

    If messages are suppressed, the loader returns a return code upon completion. This return code is the same as the loader message number. Therefore, if messages are suppressed and a non-zero return code is received from the loader, the meaning of the return code can be found by looking at the loader message with the same message number. The messages are described in Appendix A of this manual.

    PARMS
    Parameters passed to the task. All the characters beyond the parenthesis "(" on the command line are passed to the task along with the task name. If parameters are specified, the task name, a single space, and all the characters following the parenthesis "(" are copied to the task parameter area. The "(" signals the end of optional parameters. The task name is converted to upper case. The parameters are copied to offset 001Ch in the task's header segment. The maximum length of the parameter area is 128 bytes. The parameters are passed as a NULL terminated string.

    Examples

    In the following example, the task USERTASK.EXE is loaded on co-processor adapter 1 as task 2 with messages suppressed. All other parameters have the default values.

         > ICALDRIC 1 USERTASK.EXE 2,,,,N
    
    This sample loads the task TASK.EXE as task 1 on card 0.
         > ICALDRIC 0 TASK.EXE 1
    
    This sample loads the task TASK.EXE as task 2 on card 1. The task is passed the parameter string "parameter string".
         > ICALDRIC 1 C:\TASK.EXE 2 (parameter string
    

    Chapter 6. Preparing/Installing Application Tasks

    This chapter provides overview information on preparing and installing application tasks. Additional information on loading tasks is in "Chapter 5. Application Loader Utility".


    Preparing Application Tasks

    Tasks that run on the co-processor adapters can be written in assembly language or C language. For information on the development of C tasks, see the IBM Realtime Interface Co-Processor C Language Support Version 1.03 User's Guide. The rest of this section discusses development of assembler language tasks.

    Application tasks must have either the .COM or .EXE format, and can be developed with IBM Macro Assembler/2.

    See the file READ.ME on the IBM Realtime Interface Co-Processor OS/2 Support Programs diskette for information on the files necessary for assembly. Refer to the IBM Macro Assembler/2 manual for details concerning parameters.


    Installing Application Tasks

    After the device driver and Realtime Control Microcode are installed and your application tasks are constructed, you can use the application loader utility (ICALDRIC.COM) to install your application tasks on the co-processor adapter. Each task must be assigned a unique task number. The MAXTASK field in the parameter file defines the highest task number that can be assigned to a task to be loaded.

    To install a task, issue the following command:

    > ICALDRIC n1 taskname.ext n2

    Where n1 is the logical co-processor adapter number (decimal), taskname.ext is the name (including extension) of the application task, and n2 is the task number (decimal) assigned to the task to be loaded.

    If the task is successfully loaded, the following message is displayed:

    Normal termination. Task 00 loaded on coproc 00

    If a different message is displayed, see Appendix A, "Message List," for the recommended action.

    Once your application tasks are successfully loaded on the co-processor adapter, the tasks are ready to communicate with system unit applications.

    For detailed information on loading tasks, refer to "Chapter 5. Application Loader Utility".


    Chapter 7. Dynamic Link Routines


    Overview

    The dynamic link routines provide a programming interface for system unit programs to the device driver and any installed co-processor adapters. Co-processor adapter memory and tasks may be accessed by dynamic link routines.

    The dynamic link routines are defined in two files: ICARICDL.LIB and ICARICDL.DLL. The file ICARICDL.LIB contains link information; it should be linked with system unit programs that call the dynamic link routines necessary for system unit applications. The file ICARICDL.DLL contains the dynamic link routine code. The directory giving the location of the file should be in the list of directories assigned to the LIBPATH variable in CONFIG.SYS; enabling OS/2 to find the code at runtime.

    The include file (ICACALLS.INC) is shipped with the product for assembly language programs. The file contains a set of macros that declare the dynamic link routines external, push parameters on the stack, and call the dynamic link routines.

    To use the dynamic link routines in an assembly language program, put the following line in the source file of that program:

              include   icacalls.inc
    
    To assemble and link the program using the dynamic link routines, use the following commands:
              masm asmprog;
              link asmprog,,,icaricdl.lib;
    
    All examples of dynamic link routines in the text use these macros.

    See Appendix C. "Error Codes" for the error codes returned by the dynamic link routines.

    The dynamic link routines used to access the ICARICIO.SYS device driver are explained in the remainder of this chapter.

    ICADevChangePage


    Purpose

    ICADevChangePage changes the shared storage window to point to a different page of co-processor adapter memory.

    Calling Sequence

    EXTRN   ICADevChangePage:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    NewPage      ;new page value
    PUSH    BYTE    OldPage      ;old page value returned
    CALL    ICADevChangePage
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    NewPage
    is the new page number for the shared storage window.

    OldPage
    returns the previous page referenced by the shared storage window.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF07h = ERROR_ICA_INVALID_PAGE
    FF0Ah = ERROR_ICA_WIN_RESERVED
    
    Remarks

    The ICADevChangePage function can only be called by applications that have already reserved the shared storage window of the given co-processor adapter. The function is usually used by applications that directly access co-processor adapter memory and need to access a different page of that memory.

    Example

    In the following example, the CPU page register is set to 5 so that page 5 of co-processor adapter 0's memory is seen through the shared storage window.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    NewPage    db      5                ;new page number
    OldPage    db      ?                ;returned old page number
    
               @ICADevChangePage DevHan,CoProc,NewPage,OldPage
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevGetExtParms


    Purpose

    The ICADevGetExtParms dynamic link routine obtains extended parameter information for Realtime Interface Co-Processor Multiport/2, Realtime Interface Co-Processor Portmaster Adapter/A, and X.25 Interface Co-Processor/2 adapters.

    Calling Sequence

    EXTRN   ICADevGetExtParms:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    ParmLen      ;number of parm bytes to return
    PUSH@   OTHER   ExtParmBuf   ;destination for parameters
    CALL    ICADevGetExtParms
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    ParmLen
    is the number of parameter bytes to return to the caller. In this release, this field should have a value of 6 or less. This routine returns the smaller of the ParmLen parameter and the number of available parameter bytes.

    ExtParmBuf
    is a double word pointer to where the parameters are stored.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    
    Remarks

    The ICADevGetExtParms function returns a 6-byte record containing the extended parameter information for a given co-processor adapter. The user should verify that there is enough space to receive the extended parameters.

       Adapter code                  BYTE
       Physical slot number          BYTE
       EIB 0 ID                      BYTE
       EIB 1 ID                      BYTE
       Clocking options (0,1)        BYTE
       Arbitration level             BYTE
    
    Field Definitions

    Adapter code:
    the adapter type. The bits are defined as XXXX XXXA where A=0 indicates that the adapter is a Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport, or Realtime Interface Co-Processor Multiport Adapter, Model 2. A=1 indicates that the adapter is either a Realtime Interface Co-Processor Multiport/2 or an X.25 Interface Co-Processor/2. A=2 indicates that the adapter is a Realtime Interface Co-Processor Portmaster Adapter/A.

    Physcial slot number:
    a byte that contains the slot number of the card.

    Electrical Interface Board 0 ID:
    a identification byte for Electrical Interface Board 0.

    Electrical Interface Board 1 ID:
    a identification byte for Electrical Interface Board 1.

    Clocking options:
    a byte that indicates the clocking options for ports 0 and 1. The user should first check the Adapter Code field; if bit0=0, the clocking options are not available and this field in undefined. Bit 0 is the least significant bit. If bit0=1, the field has the following definition:
            D7 D6 D5 D4 D3 D2 D1 D0
            |  |  |  |  |  |  |  |
            |  |  |  |  |  |  |  +---- PLL/32 (port 0)
            |  |  |  |  |  |  +------- Loc/Rem (port 0)
            |  |  |  |  |  +---------- DCE/DTE (port 0)
            |  |  |  |  +------------- Reserved = 0
            |  |  |  +---------------- PLL/32 (port 1)
            |  |  +------------------- Loc/Rem (port 1)
            |  +---------------------- DCE/DTE (port 1)
            +------------------------- Reserved = 0
    
            with the following bit definitions:
    
                  PLL/32:  0 = divisor of 16
                           1 = divisor of 32
    
                  Loc/Rem: 0 = Remote
                           1 = Local
    
                  DCE/DTE: 0 = DTE is the clock source
                           1 = DCE is the clock source
    
    Example

    In the following example, the Electrical Interface Board 0 ID for adapter 0 is returned.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    ExtParmLen db      5                ;parameter buffer length
    EP         ICAEXTPARM <>            ;parameter buffer
    
               @ICADevGetExtParms DevHan,CoProc,ExtParmLen,EP
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    
               mov     al,EP.EIB0ID
    

    ICADevGetInBuf


    Purpose

    ICADevGetInBuf reads the contents of a task's input buffer.

    Calling Sequence

    EXTRN   ICADevGetInBuf:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH@   OTHER   Buffer       ;destination for buffer data
    PUSH@   WORD    Length       ;length to read
    CALL    ICADevGetInBuf
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    Buffer
    is a double word pointer to where the input buffer data is stored.

    Length
    is a double word pointer to the number of bytes to be read. A value of 0 indicates that 64KB should be read.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF1Ch = ERROR_ICA_BAD ADDRESS
    
    Remarks

    The ICADevGetInBuf function can be called by any application; ownership of the shared storage window is not required. This information typically obtains input data after a task interrupts the system unit.

    If a length greater than the size of the input buffer is specified, the function reads only the number of bytes in the input buffer. The number of bytes actually read is returned in the same location. The user should make sure that there is enough space to receive the input buffer data.

    Example

    In the following example, 8 bytes of Realtime Control Microcode's input buffer on co-processor adapter 1 are read into RCMInBuf.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    TaskNum    db      0                ;RCM's task number
    RCMInBuf   db      8 dup (?)        ;destination buffer
    InLen      dw      8                ;number of bytes to read
    
               @ICADevGetInBuf DevHan,CoProc,TaskNum,RCMInBuf,InLen
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevGetParms


    Purpose

    ICADevGetParms gets the configuration parameters for a given co-processor adapter.

    Calling Sequence

    EXTRN   ICADevGetParms:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH@   OTHER   ParmBuffer   ;destination for parameters
    CALL    ICADevGetParms
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    ParmBuffer
    is a double word pointer to where the configuration parameters are stored.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    
    Remarks

    The ICADevGetParms function returns a 20-byte record containing the configuration parameters for the given co-processor adapter. The user should verify that enough space is available to receive the configuration parameters.

       Field                         Length
    -----------------------------------------
       Base I/O address               WORD
       Reserved                       BYTE
       Shared storage window meg      BYTE
       Shared storage window page     BYTE
       Highest task number            BYTE
       Highest priority value         BYTE
       Highest queue number           BYTE
       Highest timer number           BYTE
       CAD16 .. CAD23                 BYTE
       CAD0 .. CAD15                  WORD
       Reserved                      DWORD
       Interrupt level index          BYTE
       Reserved                       WORD
       Shared storage window size     BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Base I/O address:
    the base address of the co-processor adapter's I/O ports. These ports are used by the device driver for controlling the co-processor adapter.

    Shared storage window meg:
    the meg of system unit memory at the co-processor adapter's shared storage window location.

    Shared storage window page:
    the page of system unit memory, within the defined meg, at the co-processor adapter's shared storage window location.

    Highest task number:
    the highest task number that can be loaded on the co-processor adapter.

    Highest priority value:
    the lowest priority level (highest priority number) that can be assigned.

    Highest queue number:
    the highest queue number that can be allocated on the co-processor adapter.

    Highest timer number:
    the highest software timer number that can be allocated on the co-processor adapter.

    CAD16 .. CAD23:
    the high byte of the physical address that causes co-processor adapter memory to degate. When combined with the CAD0..CAD15 field, this defines the system unit address that causes the co-processor adapter's memory to degate when the address is accessed.

    CAD0 .. CAD15:
    the low-word of the physical address that causes co-processor adapter memory to degate.

    Interrupt level index:
    an index that indicates the interrupt level on which the co-processor adapter interacts with the system unit. The following chart shows the correlation between the interrupt level index and the actual interrupt level:
         Index    Interrupt Level
         -----    ---------------
           0            3
           1            4
           2            7
           3            9
           4           10
           5           11
           6           12
           7           15
    
    Shared storage window size:
    the size code that indicates the size of the co-processor adapter's shared storage window. The following chart matches the size code with the window size:
        Size Code     Window Size
        ---------     -----------
            0             8KB
            1            16KB
            2            32KB
            3            64KB
    
    Example

    In the following example, the highest task number for co-processor adapter 0 is put in the AL register after calling ICADEVGETPARMS.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    Parm0      ICAPARM <>               ;parameter buffer
    
               @ICADevGetParms DevHan,CoProc,Parm0
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    
               mov     al,Parm0.PRM_LarTask ;get Highest task number
    

    ICADevGetSecStatus


    Purpose

    ICADevGetSecStatus reads the contents of a task's secondary status buffer.

    Calling Sequence

    EXTRN   ICADevGetSecStatus:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH@   OTHER   Buffer       ;destination for buffer data
    PUSH@   WORD    Length       ;length to read
    PUSH    BYTE    Status       ;status control flag
    CALL    ICADevGetSecStatus
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    Buffer
    is a double word pointer to where the secondary status buffer data is stored.

    Length
    is a double word pointer to the number of bytes to read. A value of 0 indicates that 64KB should be read.

    Status
    is the status flag that indicates if the status available bit in the task's primary status byte should be checked.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF0Ch = ERROR_ICA_STATUS_NOT_READY
    FF1Ch = ERROR_ICA_BAD_PARMS
    
    Remarks

    The ICADevGetSecStatus function can be called by any application; ownership of the shared storage window is not required. This function typically obtains status information after a task reports an error.

    If a length greater than the size of the secondary status buffer is specified, the function reads only the number of bytes in the input buffer. The number of bytes actually read is returned in the same location. The user should ensure that enough space is available to receive the secondary status buffer data.

    The Status parameter contains control bits of the form 0000 000a; where a=0 means that the buffer should always be read and a=1 means that the buffer should be read only if the status available bit is set in the task's primary status byte.

    Example

    In the following example, 10 bytes are read from task 1's secondary status buffer on co-processor adapter 0 only if the status available bit is set in task 1's primary status byte.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    TaskNum    db      1                ;task number 1
    SBuf       db      10 dup (?)       ;buffer area for status
    SLen       dw      10               ;number of bytes to read
    SFlag      db      1                ;flag for read only if status
                                        ; available
    
               @ICADevGetSecStatus DevHan,CoProc,TaskNum,SBuf,SLen,SFlag
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevGetVersion


    Purpose

    ICADevGetVersion reads the major and minor version code of the installed device driver.

    Calling Sequence

    EXTRN   ICADevGetVersion:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle from DosOpen
    PUSH@   WORD    Version      ;destination for version code
    CALL    ICADevGetVersion
    
    Where:

    Version
    is the version code. The minor code is stored in the first byte; the major code is stored in the second byte. The call returns a value of 0x0103 for this release.
    Returns

    No error

    ICADevGetVersion returns the version of the installed device driver. This version code determines the services available from the device driver.

    Example

    In the following example, the level of the device driver is checked.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    Version    dw      ?                ;level of driver
    
               @ICADevGetVersion DevHan,Version
    
               cmp     Version,0103h    ;check level of driver
    

    ICADevInputBuffer


    Purpose

    ICADevInputBuffer reads the address of a task's input buffer from the task's Buffer Control Block.

    Calling Sequence

    EXTRN   ICADevInputBuffer:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH@   OTHER   Buffer       ;destination for buffer address
    CALL    ICADevInputBuffer
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    Buffer
    is a double word pointer to where the input buffer address is stored.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    
    Remarks

    The ICADevInputBuffer function returns the address of a task's input buffer in a 5-byte record. The user should ensure that enough space is available to store the buffer address.

    The format of the buffer address record follows:

         +---------------------------------------+
         | Buffer length in bytes           WORD |
         | Buffer page offset               WORD |
         | Buffer page number               BYTE |
         +---------------------------------------+
    
    Example

    In the following example, the address of Realtime Control Microcode's input buffer is read into BufAddr.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    TaskNum    db      0                ;task number 0
    BufAddr    ICABUFFER <>             ;buffer address structure
    
               @ICADevInputBuffer DevHan,CoProc,TaskNum,BufAddr
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevIssueCommand


    Purpose

    ICADevIssueCommand issues a command with parameters to a task.

    Calling Sequence

    EXTRN   ICADevIssueCommand:FAR
    
    PUSH    WORD    DevHandle     ;device driver handle
    PUSH    BYTE    CoProc        ;co-processor adapter number
    PUSH    BYTE    TaskNum       ;task number
    PUSH    BYTE    Command       ;command code
    PUSH@   OTHER   Buffer        ;pointer to buffer to write
    PUSH    WORD    Length        ;length of buffer to write
    PUSH    WORD    Time-out      ;wait length in milliseconds
    CALL    ICADevIssueCommand
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    Command
    is the command code to give to the task.

    Buffer
    is a double word pointer to the parameter bytes to write to the task's output buffer.

    Length
    is the number of parameter bytes. A value of 0 indicates that no parameter bytes should be written.

    Time-out
    is the number of milliseconds to wait for a response from Realtime Control Microcode.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF0Bh = ERROR_ICA_TIMEOUT
    FF12h = ERROR_CMD_REJECTED
    FF14h = ERROR_ICA_OB_TOO_SHORT
    FF1Ch = ERROR_ICA_ BAD_ADDRESS
    FF11h = ERROR_ICA_BAD_PCSELECT
    
    Remarks

    The ICADevIssueCommand function issues a command to a task on a given co-processor adapter. A length of 0 is passed to the function if there are no parameters to write. If the length parameter is larger than the size of the task's output buffer, an error is returned to the application.

    Example

    In the following example, a command is issued to task 1 on co-processor adapter 0. The command code is 8, and three parameter bytes are put in task 1's output buffer: 10h, 20h and 30h.

             include icacalls.inc        ;include macros
    
    DevHan    dw      ?                  ;handle returned by DosOpen
    CoProc    db      0                  ;co-processor adapter 0
    TaskNum   db      1                  ;task number 1
    Cmd       db      8                  ;command code = 8
    Buf       db      10h,20h,30h        ;parameter buffer
    Len       dw      3                  ;number of parameter bytes
    Time-out  dw      5000               ;time-out = 5000 milliseconds
    
       @ICADevIssueCommand DevHan,CoProc,TaskNum,Cmd,Buf,Len,Time-out
    
    
             or      ax,ax              ;jump in case of error
             jnz     ErrorHandler
    

    ICADevLock


    Purpose

    ICADevLock locks a segment and obtains its physical address. The locked memory can then be used for bus master transfers via Peer Services.

    Note:

    This routing is only necessary when using Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Calling Sequence

    EXTRN   ICADevLock:FAR
    PUSH    WORD    DevHandle       ; device driver handle
    PUSH    WORD    Selector        ; selector to lock
    PUSH@   DWORD   PhysAddr        ; physical address returned
                                    ; here
    PUSH@   DWORD   LockHand        ; lock handle returned
                                    ; here
    CALL    ICADevLock
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The ICADevLock function locks a segment of memory and returns its physical address. This function is necessary when transferring data to or from the system unit via Realtime Control Microcode move data peer request.

    Example

        include icacalls.inc   ;include macros
    
    DevHan     dw      ?       ;handle returned by DosOpen
    Selector   dw      ?       ;selector of memory to lock
    Phys@      dd      ?       ;physical memory address returned here
    LockHan    dd      ?       ;lock handle
    
               @ICADevLock DevHan,Selector, Phys@,LockHan
    
               or      ax,ax   ;jump in case of error
               jnz     ErrorHandler
    

    ICADevNotify


    Purpose

    ICADevNotify registers a semaphore with the device driver for notification of special events.

    Calling Sequence

    EXTRN   ICADevNotify:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    Control      ;control bits
    PUSH    DWORD   Semaphore    ;semaphore handle to register
    CALL    ICADevNotify
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    Control
    is the control flag.

    Semaphore
    is the handle of the semaphore to register.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Dh = ERROR_ICA_INVALID_CONTROL
    FF15h = ERROR_ICA_SEM_FULL
    FF1Dh = ERROR_ICA_BAD_SEMAPHORE
    
    Remarks

    The ICADevNotify function registers a semaphore with the device driver for notification of special events. The Semaphore parameter is a handle returned by the DosCreateSem OS/2 function. The semaphore should be made non-exclusive by the DosCreateSem call.

    The format of the Control parameter is a000 0000; where a=1 for notification of Initialize commands to Realtime Control Microcode on the co-processor adapters; all other bits should be 0. When an Initialize command is issued to Realtime Control Microcode, all semaphores registered for that co-processor adapter with the ICADevNotify function are cleared. After registering the semaphore, application threads should call DosSemWait for the semaphore for notification of Initialize commands to Realtime Control Microcode.

    A maximum of 255 semaphores can be registered with the device driver.

    Example

    In the following example, the SemHan semaphore handle is registered with the device driver. When an Initialize command is issued to Realtime Control Microcode on co-processor adapter 0, the device driver clears the SemHan semaphore and awakens the process waiting on the semaphore.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    Control    db      80h              ;flag for RCM Init notify
    SemHan     dd      ?                ;semaphore handle from
                                        ; DosCreateSem
    
               @ICADevNotify DevHan,CoProc,Control,SemHan
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevOutputBuffer


    Purpose

    ICADevOutputBuffer reads the address of a task's output buffer from the task's Buffer Control Block.

    Calling Sequence

    EXTRN   ICADevOutputBuffer:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH@   OTHER   Buffer       ;returned buffer address
    CALL    ICADevOutputBuffer
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    Buffer
    is a double word pointer to where the output buffer address will be stored.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The ICADevOutputBuffer function returns the address of a task's output buffer in a 5-byte record.

    The format of the buffer address record follows:

         +---------------------------------------+
         | Buffer length in bytes           WORD |
         | Buffer page offset               WORD |
         | Buffer page number               BYTE |
         +---------------------------------------+
    
    Example

    In the following example, the address of Realtime Control Microcode's output buffer is read into BufAddr.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    TaskNum    db      0                ;task number 0
    BufAddr    ICABUFFER <>             ;buffer address structure
    
               @ICADevOutputBuffer DevHan,CoProc,TaskNum,BufAddr
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevPeerClose


    Purpose

    ICADevPeerClose closes a peer handle.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Calling Sequence

    EXTRN   ICADevPeerClose : FAR
    PUSH    WORD    DevHandle       ; device driver handle
    PUSH    WORD    PeerHandle      ; peer handle
    PUSH    WORD    DispCode        ; disposition code
    
    CALL    ICADevPeerClose
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF17h = ERROR_ICA_BAD_HANDLE
    FF18h = ERROR_ICA_REQS_REMAIN
    FF1Fh = ERROR_ICA_UNKNOWN_DISP
    FF20h = ERROR_ICA_UNKNOWN_PEER
    
    Remarks

    The ICADevPeerClose is used to return a peer handle to the device driver and terminate peer services.

    Example

         include icacalls.inc    ;include macros
    
    DISP_PURGE equ     0
    DevHan     dw      ?         ;handle returned by DosOpen
    PeerHan    dw      ?         ;peer handle returned by ICADevPeerOpen
    
               @ICADevPeerClose DevHan,PeerHan,DISP.PURGE
    
               or      ax,ax     ;jump in case of error
               jnz     ErrorHandler
    

    ICADevPeerOpen


    Purpose

    ICADevPeerOpen establishes a peer task in the system unit unit.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Calling Sequence

    EXTRN   ICADevPeerOpen  :  FAR
    PUSH    WORD    DevHandle       ; device driver handle
    PUSH    WORD    BuffSize        ; size of peer data segment
    PUSH@   DWORD   PeerHandle      ; peer handle
    
    CALL    ICADevPeerOpen
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF16h = ERROR_ICA_NO_PEER_HAND
    FF1Eh = ERROR_NOT_ENOUGH_MEMORY
    FF22h = ERROR_TOO_MANY_SEMAPHORES
    
    Remarks

    The ICADevPeerOpen function establishes a thread as a peer task. The function returns a peer handle used as the thread's task ID within the peer request block. The BuffSize parameter specifies the size (in bytes) of the buffer area allocated for receiving incoming peer request blocks. The driver copies incoming request blocks to the receive area and returns a positive acknowledgement as long as buffers are available. If buffers are not available, the driver negatively acknowledges any incoming peer request blocks for the task.

    Example

          include icacalls.inc     ;include macros
    
    BUFF_SIZE  equ     1024        ;1Kb buffer area
    DevHan        dw      ?        ;handle returned by DosOpen
    PeerHan       dw      ?        ;peer handle is returned here
    
          @ICADevPeerOpen DevHan,BUFF_SIZE,PeerHan
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevPeerReceive


    Purpose

    ICADevPeerReceive receives peer request blocks.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Calling Sequence

    EXTRN   ICADevPeerReceive:FAR
    PUSH    WORD    PeerHandle       ; Peerhandle
    PUSH    DWORD   Time-out         ; time-out in milliseconds
                                     ; 0 = no wait
                                     ; -1 = wait forever
    PUSH@   DWORD   PeerReqBlk       ; pointer to peer request
                                     ; blocks returned
    PUSH@   WORD    ReqBlkCount      ; count of request blocks
                                     ; returned
    
    CALL    ICADevPeerReceive
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF19h = ERROR_ICA_NO_REQS
    FF0Bh = ERROR_ICA_TIMEOUT
    FF0Ah = ERROR_RCV_SEQ_ERR
    FF17h = ERROR_ICA_BAD_HANDLE
    
    Remarks

    The ICADevPeerReceive returns a pointer to a list of peer request blocks along with a count of request blocks in the list. An ICADevPeerReceiveDone call must be called to free request blocks. If no peer request blocks are available to receive after the request blocks are processed by the peer task, the call blocks are subject to the time-out parameter.

    Example

               include icacalls.inc      ;include macros
    
    PeerHan    dev     ?                 ;peer handle
    Timeout    dd      -1                ;Time-out (-1 = no timeout)
    PRBPtr     dd      ?                 ;Pointer to PRB returned here
    PRBCt      dw      ?                 ;Count of PRB's returned here
    
               @ICADevPeerReceive  PeerHan,Timeout,PRBPtr,PRBCt
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevPeerReceiveDone


    Purpose

    ICADevPeerReceiveDone is used by a peer task to indicate the completion of processing of received peer request blocks.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Calling Sequence

    EXTRN   ICADevPeerReceiveDone:FAR
    PUSH    WORD  Peerhandle            ; Peerhandle
    CALL    ICADevPeerReceive
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF17h = ERROR_ICA_BAD_HANDLE
    FF1Ah = ERROR_RCV_SEQ_ERR
    
    Remarks

    The ICADevPeerReceiveDone, used after an ICADevPeerReceive call, indicates that the application is done processing the peer request blocks returned by the ICADevPeerReceive call. The application must complete all processing of the request blocks or copy any necessary data before making this call. Failure to call ICADevPeerReceiveDone causes request blocks to consume the buffer area created on the ICADevPeerOpen. When this buffer area is exhausted, the driver NAKs any incoming request blocks for the application.

    Example

               include icacalls.inc     ;include macros
    
    PeerHan    db      ?                ;peer handle
    
               @ICADevPeerReceiveDone  PeerHan
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevPeerSend


    Purpose

    ICADevPeerSen sends a peer request block to a peer task on a Realtime Interface Co-Processor Portmaster Adapter/A or another peer thread in the system unit.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Calling Sequence

    EXTRN   ICADevPeerSend:FAR
    
    PUSH    WORD    DevHandle       ; device driver handle
    PUSH@   OTHER   PeerReqBlk      ; peer request block
    
    CALL    ICADevPeerSend
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF21h = ERROR_ICA_BAD_PARM
    FF1Eh = ERROR_ICA_NOT_ENOUGH_MEMORY
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks The ICADevPeerSend routine is used to send a peer request block to a task on an Realtime Interface Co-Processor Portmaster Adapter/A. For a complete discussion of the Realtime Control Microcode Version 2.0 and Realtime Interface Co-Processor Portmaster Adapter/A peer services, refer to the Realtime Interface Co-Processor Firmware Technical Reference

    Example

               include icacalls.inc     ;include macros
    
    PRB        struc    PeerReqBlk
    
               @ICADevPeerSend  PRB
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevPrimaryStatus


    Purpose

    ICADevPrimaryStatus reads the primary status byte for a given task.

    Calling Sequence

    EXTRN   ICADevPrimaryStatus:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH@   BYTE    PrimStat     ;pointer to primary status variable
    CALL    ICADevPrimaryStatus
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    PrimStat
    is a double word pointer to where the primary status byte is stored.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    
    Remarks

    The ICADevPrimaryStatus function returns the primary status byte for the given task. See the IBM Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport, and Realtime Interface Co-Processor Multiport/2 Technical Reference, and the IBM Realtime Interface Co-Processor Firmware Technical Reference for the meanings of the primary status bits.

    Example

    In the following example, the primary status byte of task 1 on co-processor adapter 0 is stored in PrimStat.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    TaskNum    db      1                ;task number 1
    PrimStat   db      ?                ;primary status byte
    
               @ICADevPrimaryStatus DevHan,CoProc,TaskNum,PrimStat
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevPutOutBuf


    Purpose

    ICADevPutOutBuf writes a buffer to the given task's output buffer.

    Calling Sequence

    EXTRN   ICADevPutOutBuf:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH@   OTHER   Buffer       ;source of buffer data
    PUSH@   WORD    Length       ;length to write
    CALL    ICADevPutOutBuf
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    Buffer
    is a double word pointer to buffer data to write to the output buffer.

    Length
    is a double word pointer to the number of bytes to write. It returns the number of bytes actually written. A value of 0 indicates that 64KB should be written.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    
    Remarks

    The ICADevPutOutBuf function can be called by any application; ownership of the shared storage window is not required. This function typically writes to the output buffer before issuing a command to the task. If a length greater than the size of the output buffer is specified, the function writes only the number of bytes in the output buffer. The number of bytes actually written is returned in the same location.

    Example

    In the following example, 8 bytes of data are written to the output buffer of task 1 on co-processor adapter 1.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    TaskNum    db      1                ;task number 1
    OutData    db      8,7,6,5,4,3,2,1  ;source buffer
    OutLen     dw      8                ;number of bytes to write
    
               @ICADevPutOutBuf DevHan,CoProc,TaskNum,OutData,OutLen
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevReadString


    Purpose

    ICADevReadString reads a given co-processor adapter's memory into an application buffer.

    Calling Sequence

    EXTRN   ICADevReadString:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    WORD    Length       ;length to read
    PUSH    WORD    SegPage      ;segment or page of read
    PUSH    WORD    Offset       ;offset of read
    PUSH    BYTE    Format       ;address format control byte
    PUSH@   OTHER   Buffer       ;destination for co-proc memory
    CALL    ICADevReadString
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    Length
    is the number of bytes to read. A value of 0 indicates that 64KB should be read.

    SegPage
    is the segment or page number of the read.

    Offset
    is the segment offset or page offset of the read.

    Format
    is the control byte defining the format of the address.

    Buffer
    is a double word pointer to buffer where the co-processor adapter memory should be copied.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF07h = ERROR_ICA_INVALID_PAGE
    FF08h = ERROR_ICA_INVALID_OFFSET
    FF09h = ERROR_ICA_INVALID_FORMAT
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The ICADevReadString function reads co-processor adapter memory into a system unit buffer. The address of the co-processor adapter memory can be specified either as a segment and offset or as a page and offset.

    Note:

    Logical segments:offset addresses are converted to page:offset addresses assuming that there is direct memory mapping on Realtime Interface Co-Processor Portmaster Adapter/A. Physical page:offset addresses should be used when physical Realtime Interface Co-Processor Portmaster Adapter/A memory is remapped in the 80186 logical address space. The application is responsible for ensuring that the physical memory on the Realtime Interface Co-Processor Portmaster Adapter/A adapter can be addressed.
    The Format parameter should have a value of FFh for page and offset addresses; a value of 00 designates a segment and offset address; a value of 01 designates a 32-bit physical address.

    Example

    In the following example, the first 4 bytes of the Interface Block on co-processor adapter 1 is read into Buffer.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    Len        dw      4                ;number of bytes to read
    Seg        dw      0                ;segment 0
    Off        dw      440h             ;offset 440h
    Format     db      0                ;segment:offset address
    Buffer     db      4 dup (?)        ;destination buffer
    
               @ICADevReadString DevHan,CoProc,Len,Seg,Off,Format,Buffer
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevRegSemaphore


    Purpose

    ICADevRegSemaphore registers a semaphore with the device driver.

    Calling Sequence

    EXTRN   ICADevRegSemaphore:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH    DWORD   Semaphore    ;handle of semaphore to register
    CALL    ICADevRegSemaphore
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number for which to register the semaphore.

    Semaphore
    is the handle of the application's semaphore.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF15h = ERROR_ICA_SEM_FULL
    FF1Dh = ERROR_ICA_BAD_SEMAPHORE
    
    Remarks

    The ICADevRegSemaphore function registers an application's semaphore with the device driver. Semaphores synchronize between system unit applications and co-processor adapter tasks. The device driver clears any semaphores registered for that task and adapter when a task on a co-processor adapter interrupts the system unit. The semaphore must be created as a non-exclusive semaphore. To wait on a task interrupt, the application:

    1. Calls DosCreateSem to create a non-exclusive semaphore.

    2. Calls DosSetSem to set a semaphore.

    3. Registers the semaphore with the ICADevRegSemaphore call.

    4. Calls DosSemWait to wait for the semaphore to be cleared.
    Example

    In the following example, the SemHan semaphore handle is registered with the device driver. When an interrupt is received from task 0 on co-processor adapter 0, the device driver clears the SemHan semaphore and awakens the process waiting on the semaphore.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    TaskNum    db      0                ;task number 0 (RCM)
    SemHan     dd      ?                ;semaphore handle from
                                        ; DosCreateSem
    
               @ICADevRegSemaphore DevHan,CoProc,TaskNum,SemHan
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevRemNotify


    Purpose

    ICADevRemNotify removes a semaphore from the device driver list for notification of Realtime Control Microcode Initialize commands.

    Calling Sequence

    EXTRN   ICADevRemNotify:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    Control      ;control bits
    PUSH    DWORD   Semaphore    ;semaphore handle to remove
    CALL    ICADevRemNotify
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    Control
    is the control flag.

    Semaphore
    is the handle of the semaphore to remove from the notification list.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Dh = ERROR_ICA_INVALID_CONTROL
    FF1Dh = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The ICADevRemNotify function removes and clears a semaphore from the device driver's notification list for special events. The ICADevNotify function should have registered the semaphore handle with the device driver.

    The format of the Control parameter is a000 0000; where a=1 for notification of Realtime Control Microcode Initialize commands. All other bits should be 0.

    Example

    In the following example, the SemHan semaphore handle is removed by the device driver from its internal tables. ICADevNotify call registered SemHan with the devic driver.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    Control    db      80h              ;flag for RCM Init notify
    SemHan     dd      ?                ;semaphore handle from
                                        ; DosCreateSem and registered
                                        ; with ICADevNotify
    
               @ICADevRemNotify DevHan,CoProc,Control,SemHan
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevRemSemaphore


    Purpose

    ICADevRemSemaphore removes a semaphore from the device driver's list of registered semaphores.

    Calling Sequence

    EXTRN   ICADevRemSemaphore:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number for semaphore
    PUSH    DWORD   Semaphore    ;handle of semaphore to remove
    CALL    ICADevRemSemaphore
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter for which the semaphore was registered.

    TaskNum
    is the task number for which the semaphore was registered.

    Semaphore
    is the handle of the application's semaphore.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF1Dh = ERROR_ICA_BAD_SEMAPHORE
    
    Remarks

    The ICADevRemSemaphore function removes and clears an application's semaphore from the registered semaphore list in the device driver. The ICADevRegSemaphore function registers semaphores with the device driver for synchronization between the system unit application and the co-processor adapter task. When the application no longer needs notification of interrupts from the task, it should de-register the semaphore with the ICADevRemSemaphore function. The co-processor adapter and task numbers should be the same as those used when the semaphore was registered with the ICADevRegSemaphore function.

    Example

    In the following example, the SemHan semaphore handle is removed from the device driver's internal tables. The function is called when the process no longer needs to be notified of interrupts from task 0 (Realtime Control Microcode) on co-processor adapter 0.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    TaskNum    db      0                ;task number 0 (RCM)
    SemHan     dd      ?                ;semaphore handle from
                                        ; DosCreateSem and registered
                                        ; with ICADevRegSemaphore
    
               @ICADevRemSemaphore DevHan,CoProc,TaskNum,SemHan
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevReset


    Purpose

    ICADevReset issues a hardware reset to the given co-processor adapter.

    Calling Sequence

    EXTRN   ICADevReset:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    CALL    ICADevReset
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter to reset.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    
    Remarks

    The ICADevReset function issues a hardware reset to the given co-processor adapter. The Realtime Control Microcode and all other tasks are unloaded; the co-processor adapter then goes through its power-on self test.

    Example

    In the following example, co-processor adapter 1 is reset:

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    
               @ICADevReset DevHan,CoProc
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevSecStatus


    Purpose

    ICADevSecStatus reads the address of a task's secondary status buffer from the task's Buffer Control Block.

    Calling Sequence

    EXTRN   ICADevSecStatus:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH    BYTE    TaskNum      ;task number
    PUSH@   OTHER   Buffer       ;destination for buffer address
    CALL    ICADevSecStatus
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    TaskNum
    is the task number of the buffer owner.

    Buffer
    is a double word pointer to where the secondary status buffer address is stored.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    
    Remarks

    The ICADevSecStatus function returns the address of a task's secondary status buffer in a 5-byte record. The user should ensure that enough space is available to store the buffer address.

    The format of the buffer address record follows:

         +---------------------------------------+
         | Buffer length in bytes           WORD |
         | Buffer page offset               WORD |
         | Buffer page number               BYTE |
         +---------------------------------------+
    
    Example

    In the following example, the address of Realtime Control Microcode's secondary status buffer is read into BufAddr.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    TaskNum    db      0                ;task number 0
    BufAddr    ICABUFFER <>             ;buffer address structure
    
               @ICADevSecStatus DevHan,CoProc,TaskNum,BufAddr
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevTaskFlush


    Purpose

    ICADevTaskFlush flushes all requests from the calling process for services from the device driver.

    Calling Sequence

    EXTRN   ICADevTaskFlush:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    CALL    ICADevTaskFlush
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.
    Returns

    None.

    Remarks

    The ICADevTaskFlush function "flushes" any window requests by the calling process, releases any co-processor adapter windows owned by the calling process, and de-registers any semaphores registered with the device driver by the calling process. This function can be used in an application exit routine to release resources before terminating the process.

    Example

    In the following example, all requests by the calling process are flushed from the device driver. In addition, all shared storage windows owned by the calling process are released.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    
               @ICADevTaskFlush DevHan
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevUnLock


    Purpose

    The ICADevUnlock unlocks a previously locked segment with ICADevLock.

    Note:

    This routing is only necessary when using Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Calling Sequence

    EXTRN   ICADevUnLock :  FAR
    PUSH    WORD    DevHandle       ; device driver handle
    PUSH    DWORD   LockHand        ; lock handle to unlock
    CALL    ICADevUnLock
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The ICADevUnlock function unlocks a segment of memory and returns its physical address. This function is necessary when transferring data to or from the system unit via RCSMoveData peer request.

    Example

         include icacalls.inc     ;include macros
    
    DevHan     dw      ?          ;device driver handle
    LockHan    dd      ?          ;lock handle returned by ICADevLock
    
         @ICADevUnlock DevHan,LockHan
    
               or      ax,ax      ;jump in case of error
               jnz     ErrorHandler
    

    ICADevWinRelease


    Purpose

    ICADevWinRelease releases ownership of a co-processor adapter shared storage window.

    Calling Sequence

    EXTRN   ICADevWinRelease:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    CALL    ICADevWinRelease
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter shared storage window.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Ah = ERROR_ICA_WIN_NOT_OWNED
    
    Remarks

    The ICADevWinRelease function releases ownership of the shared storage window for the given co-processor adapter. Another application thread may then acquire another window. The selector created for referencing the window is removed from the process's Local Descriptor Table.

    Example

    In the following example, the shared storage window of co-processor adapter 1 is released.

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    
               @ICADevWinRelease DevHan,CoProc
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevWinResNoWait


    Purpose

    ICADevWinResNoWait requests ownership of a co-processor adapter shared storage window; the call returns if the window is already owned.

    Calling Sequence

    EXTRN   ICADevWinResNoWait:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH@   DWORD   WinAddr      ;pointer to shared storage window
    PUSH@   WORD    PID          ;owning thread's process ID if owned
    PUSH@   WORD    ThreadID     ;owning thread's thread ID if owned
    CALL    ICADevWinResNoWait
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter shared storage window.

    WinAddr
    is a double word pointer to where the shared storage window address should be placed.

    PID
    is the process ID of the owning thread if the window is already owned.

    ThreadID
    is the thread ID of the owning thread if the window is already owned.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Ah = ERROR_ICA_WIN_RESERVED
    
    Remarks

    The ICADevWinResNoWait function requests ownership of the shared storage window for the given co-processor adapter. If the window is already owned by another thread, the function returns immediately with the process ID and thread ID of the window owner. If the call is successful, a double word pointer to the shared storage window is returned to the calling thread; this pointer can be used for directly reading and writing the co-processor adapter memory. A selector is added to the process's Local Descriptor Table for referencing the window.

    Example

    In the following example, the calling process requests ownership of the shared storage window of co-processor adapter 0:

               include icacalls.inc     ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      0                ;co-processor adapter 0
    WinPtr     dd      ?                ;window pointer
    PID        dw      ?                ;process ID of window owner
    ThreadID   dw      ?                ;thread ID of window owner
    
               @ICADevWinResNoWait DevHan,CoProc,WinPtr,PID,ThreadID
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevWinResWait


    Purpose

    ICADevWinResWait requests ownership of a co-processor adapter shared storage window; the call is blocked if the window is already owned.

    Calling Sequence

    EXTRN   ICADevWinResWait:FAR
    
    PUSH    WORD    DevHandle     ;device driver handle
    PUSH    BYTE    CoProc        ;co-processor adapter number
    PUSH@   DWORD   WinAddr       ;returns pointer to window
    PUSH    DWORD   Time-out      ;time-out on wait (in milliseconds)
    CALL    ICADevWinResWait
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter shared storage window.

    WinAddr
    is a double word pointer to where the shared storage window address should be placed.

    Time-out
    is a time-out length in milliseconds for the wait if the window is already owned by another thread.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Bh = ERROR_ICA_TIMEOUT
    
    Remarks

    The ICADevWinResWait function requests ownership of the shared storage window for the given co-processor adapter. If the window is already owned by another thread, the calling thread is blocked until either the window is released or the wait times out. A successful call returns a double word pointer to the shared storage window. The pointer directly reads and writes the co-processor adapter memory. A selector is added to the process's Local Descriptor Table for referencing the window.

    Example

    In the following example, the calling process requests ownership of the shared storage window of co-processor adapter 0.

               include icacalls.inc     ;include macros
    
    DevHan      dw      ?                ;handle returned by DosOpen
    CoProc      db      0                ;co-processor adapter 0
    WinPtr      dd      ?                ;window pointer
    Time-out    dd      2000             ;max wait = 2 seconds
    
               @ICADevWinResWait DevHan,CoProc,WinPtr,Time-out
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    ICADevWriteString


    Purpose

    ICADevWriteString writes an application buffer to co-processor adapter memory.

    Calling Sequence

    EXTRN   ICADevWriteString:FAR
    
    PUSH    WORD    DevHandle    ;device driver handle
    PUSH    BYTE    CoProc       ;co-processor adapter number
    PUSH@   WORD    Length       ;length to write
    PUSH    WORD    SegPage      ;segment or page of write
    PUSH    WORD    Offset       ;offset of write
    PUSH    BYTE    Format       ;address format control byte
    PUSH@   OTHER   Buffer       ;buffer to write to co-proc memory
    CALL    ICADevWriteString
    
    Where:

    DevHandle
    is the handle returned when opening the device driver with DosOpen.

    CoProc
    is the logical number of the co-processor adapter.

    Length
    is the number of bytes to write. A value of 0 indicates that 64KB should be written.

    SegPage
    is the segment or page number of the write.

    Offset
    is the segment offset or page offset of the write.

    Format
    is the control byte defining the format of the address.

    Buffer
    is a double word pointer to the buffer that contains the data to write.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF07h = ERROR_ICA_INVALID_PAGE
    FF08h = ERROR_ICA_INVALID_OFFSET
    FF09h = ERROR_ICA_INVALID_FORMAT
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The ICADevWriteString function writes a system unit buffer to co-processor adapter memory. The address of the co-processor adapter memory can be specified either as a segment and offset or as a page and offset. The Format parameter should have a value of FFh for page and offset addresses; a value of 00 designates segment and offset addresses; a value of 01 designates a 32-bit physical address.

    Note:

    Logical segments:offset addresses are converted to page:offset addresses, assuming that there is direct memory mapping on Realtime Interface Co-Processor Portmaster Adapter/A. Physical page:offset addresses should be used when physical Realtime Interface Co-Processor Portmaster Adapter/A memory is remapped in the 80186 logical address space. The application is responsible for ensuring that the physical memory on the Realtime Interface Co-Processor Portmaster Adapter/A adapter can be addressed.

    Example

    In the following example, 5 bytes from Buffer are written to page 1 offset 0 on co-processor adapter 1:

       include icacalls.inc             ;include macros
    
    DevHan     dw      ?                ;handle returned by DosOpen
    CoProc     db      1                ;co-processor adapter 1
    Len        dw      4                ;number of bytes to read
    Page       dw      1                ;page 1
    Off        dw      0                ;offset 0
    Format     db      0FFh             ;segment:offset address
    Buffer     db      1,2,3,4,5        ;destination buffer
    
      @ICADevWriteString DevHan,CoProc,Len,Page,Off,Format,Buffer
    
               or      ax,ax            ;jump in case of error
               jnz     ErrorHandler
    

    Chapter 8. Device Driver Functions


    Calls to the Device Driver

    The device driver supports a subset of the standard device driver calls defined by OS/2. (See the IBM Operating System/2 Technical Reference for a list of the standard device driver calls.)

            Command     Name
    -------------------------------------
              00h       Init
              0Dh       Open
              0Eh       Close
              10h       Generic IOCtl
              14h       Deinstall
    
    All the device driver services are available through the Generic IOCtl call interface. This interface is defined in the IBM Operating System/2 Programming Tools and Information Version 1.3 and the OS/2 Control Program Programming Reference Version 2.0 documents.

    The DosDevIOCtl call accesses the device driver services; the DosDevIOCtl call is defined in the IBM Operating System/2 Programming Tools and Information Version 1.3 and the OS/2 Control Program Programming Reference Version 2.0 documents. In the call to DosDevIOCtl, the category code should have a value of F0h; the function codes are listed with a short description of available services in the table following. The parameter and data packet formats are defined for each service later in this chapter.

        FuncCode   Name                  Description
    ----------------------------------------------------------------------------
           40h     Reset                 Reset a co-processor adapter
    
           41h     ChangePage            Point a shared storage window
                                         to a different page of co-processor
                                         adapter memory
    
           42h     WindowReserveWait     Reserve a shared storage window;
                                         block until ready
    
           43h     WindowReserveNoWait   Reserve a shared storage window;
                                         return error if already owned
    
           44h     WindowRelease         Release a shared storage window
    
           45h     TaskFlush             Remove all requests by the calling
                                         process
    
           46h     WriteString           Write co-processor adapter memory
    
           47h     RegisterSemaphore     Register semaphore with device
                                         driver for task interrupts
    
           48h     RemoveSemaphore       Remove semaphore from device
                                         driver's semaphore list
    
           49h     PutOutputBuffer       Write to a task's output buffer
    
           4Ah     IssueCommand          Issue a command with parameters
                                         to a co-processor adapter task
    
           4Bh     Notify                Register semaphore with device
                                         driver for special events
    
           4Ch     RemoveNotify          Remove semaphore from device
                                         driver's list for special
                                         events
    
           4Eh     PeerSend              Send a peer request block
    
           4Fh     Lock                  Lock a segment and obtain its
                                         physical address
    
           50h     Unlock                Unlock a segment
    
           60h     GetParameters         Get the configuration parameters
                                         for a co-processor adapter
    
           61h     InputBuffer           Get the address and length of a
                                         task's input buffer
    
           62h     OutputBuffer          Get the address and length of a
                                         task's output buffer
    
           63h     SecondaryStatus       Get the address and length of a
                                         task's secondary status buffer
    
           64h     PrimaryStatus         Get a task's primary status byte
    
           65h     ReadString            Read co-processor adapter memory
    
           66h     GetInputBuffer        Get the contents of a task's
                                         input buffer
    
           67h     GetSecondaryStatus    Get the contents of a task's
                                         secondary status buffer
    
           69h     GetVersion            Get the version number of the
                                         installed driver
    
           6Ah     GetExtParmaters       Get the extended parameters for
                                         a co-processor adapter
           6Bh     PeerOpen              Enable peer services and obtain
                                         a peer handle
    
           6Ch     PeerClose             Close a peer request block and
                                         terminate usage of peer services
    
    The device driver services may also be used through a set of dynamic link routines defined in "Chapter 7. Dynamic Link Routines". The dynamic link routines protect the user from changes in the device driver and are the preferred means of accessing the device driver.

    Sample Device Driver Call

    The following example shows a call to the ChangePage function; in the example, the shared storage window of co-processor adapter 0 is being changed to display page 1.

    
    extrn         DOSDEVIOCTL:far
    
    DevHandle     dw      ?                 ; Device driver handle
                                            ;  from DosOpen
    
    Parm_Buffer   label   byte              ; Parameter packet
    Parm_CoProc   db      0
    Parm_NewPage  db      1
    
    Data_Buffer   label   byte              ; Data packet
    Data_OldPage  db      ?
    
    
                  lea     ax,Data_Buffer    ; Data packet address
                  push    ds
                  push    ax
                  lea     ax,Parm_Buffer    ; Parameter packet address
                  push    ds
                  push    ax
                  push    041h              ; Function code
                  push    0F0h              ; Category code
                  mov     ax,DevHandle      ; Device driver handle
                  push    ax
                  call    DOSDEVIOCTL       ; Call ChangePage
    
                  or      ax,ax             ; Check for error
                  jnz     ErrorHandler      ; Jump if error occurred
    
    See "ICADevChangePage" for a similar example of the ICADevChangePage dynamic link routine. The ICADevChangePage dynamic link routine provides the same function as the ChangePage Generic IOCtl call.

    ChangePage


    Purpose

    ChangePage changes the shared storage window to point to a different page of co-processor adapter memory.

    Category Code: F0h
    Function Code: 41h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
       New page number                BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Old page number                BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter window to relocate.

    New page number:
    the page of co-processor adapter memory to reference with shared storage window.

    Old page number:
    the previous page of co-processor adapter memory referenced by shared storage window.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF07h = ERROR_ICA_INVALID_PAGE
    FF0Ah = ERROR_ICA_WIN_RESERVED
    
    Remarks

    The co-processor adapter has its own address space separate from the system unit; however, system unit applications can access the co-processor adapter's memory through a shared storage window. The window size on the Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport and the Realtime Interface Co-Processor Multiport Adapter, Model 2 is 8KB; the window size on the Realtime Interface Co-Processor Multiport/2, the X.25 Interface Co-Processor/2, and the Realtime Interface Co-Processor Portmaster Adapter/A can be set for 8KB, 16KB, 32KB or 64KB. This function changes the page of co-processor adapter memory seen through the shared storage window. The calling process must own the shared storage window (acquired with the WindowReserveWait or WindowReserveNoWait functions) to use the ChangePage function.

    Close


    Purpose

    Close releases the handle used to access the device driver.

    Remarks

    This function is not a Generic IOCtl function; it should be called through the OS/2 DosClose call. This releases the device handle used to access the device driver Generic IOCtl. When DosClose is called, any uncompleted Generic IOCtl calls to the device driver block the DosClose until the calls are returned.

    GetExtParameters


    Purpose

    GetExtParameters obtains extra configuration parameter information for a given co-processor adapter.

    Category Code: F0h
    Function Code: 6Ah

    Parameter Packet Format

       Field                         Length
    --------------------------------------------
       Co-processor adapter number    BYTE
       Parameter length (in bytes)    BYTE
    
    Data Packet Format
       Field                         Length
    --------------------------------------------
       Adapter code                  BYTE
       Physical slot number          BYTE
       EIB 0 ID                      BYTE
       EIB 1 ID                      BYTE
       Clocking options (0,1)        BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Parameter length:
    the number of parameter bytes to return. In this release, this field should have a value of 5 or less.

    Adapter code:
    the adapter type. The bits are defined as XXXX XXXA where A=0 indicates that the adapter is a Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport or Realtime Interface Co-Processor Multiport Adapter, Model 2. A=1 indicates that the adapter is an Realtime Interface Co-Processor Multiport/2, an Realtime Interface Co-Processor Portmaster Adapter/A, or an X.25 Interface Co-Processor/2.

    Physical slot number:
    a byte that contains the slot number of the card.

    Electrical Interface Board 0 ID:
    an identification byte for Electrical Interface Board 0.

    Electrical Interface Board 1 ID:
    an identification byte for Electrical Interface Board 1.

    Note:

    Refer to the Realtime Interface Co-Processor Firmware Technical Reference for the values of the identification byte.

    Clocking options:
    a byte that indicates the clocking options for ports 0 and 1. The user should first check the AdapterCode field; if bit0=0, the clocking options are not available and this field in undefined. Bit 0 is the least significant bit. If bit0=1, the field has the following definition:
            D7 D6 D5 D4 D3 D2 D1 D0
            |  |  |  |  |  |  |  |
            |  |  |  |  |  |  |  +---- PLL/32 (port 0)
            |  |  |  |  |  |  +------- Loc/Rem (port 0)
            |  |  |  |  |  +---------- DCE/DTE (port 0)
            |  |  |  |  +------------- Reserved = 0
            |  |  |  +---------------- PLL/32 (port 1)
            |  |  +------------------- Loc/Rem (port 1)
            |  +---------------------- DCE/DTE (port 1)
            +------------------------- Reserved = 0
    
            with the following bit definitions:
    
                  PLL/32:  0 = divisor of 16
                           1 = divisor of 32
    
                  Loc/Rem: 0 = Remote
                           1 = Local
    
                  DCE/DTE: 0 = DTE is the clock source
                           1 = DCE is the clock source
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    
    Remarks

    The GetExtParameters function returns extra parameter information for each card.

    GetInputBuffer


    Purpose

    GetInputBuffer reads the contents of a task's input buffer.

    Category Code: F0h
    Function Code: 66h

    Parameter Packet Format

       Field                         Length
    --------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
       Length                         WORD
    
    Data Packet Format
       Field                         Length
    --------------------------------------------
       Destination buffer pointer    DWORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the task number of the buffer owner.

    Length:
    the number of bytes to read. The number of bytes read returns in this field.

    Destination buffer pointer:
    a double word pointer to the stored input buffer data.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The GetInputBuffer function reads the contents of a task's input buffer. If a length greater than the size of the input buffer is specified, the function reads, from the task's Buffer Control Block, only the number of bytes in the input buffer. The number of bytes read, returns in the Length field of the parameter packet.

    This function does not require the caller to own the shared storage window of the co-processor adapter.

    GetParameters


    Purpose

    GetParameters obtains the configuration parameters for a given co-processor adapter.

    Category Code: F0h
    Function Code: 60h

    Parameter Packet Format

       Field                         Length
    ---------------------------------------------
       Co-processor adapter number    BYTE
    
    Data Packet Format
       Field                         Length
    ---------------------------------------------
       Base I/O address               WORD
       Reserved                       BYTE
       Shared storage window meg      BYTE
       Shared storage window page     BYTE
       Highest task number            BYTE
       Highest priority value         BYTE
       Highest queue number           BYTE
       Highest timer number           BYTE
       CAD16 .. CAD23                 BYTE
       CAD0 .. CAD15                  WORD
       Reserved                      DWORD
       Interrupt level index          BYTE
       Reserved                       WORD
       Shared storage window size     BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Base I/O address:
    the base address of the co-processor adapter's I/O ports. These ports are used by the device driver for controlling the co-processor adapter.

    Shared storage window meg:
    the meg of system unit memory at the co-processor adapter's shared storage window location.

    Shared storage window page:
    the page of system unit memory, within the defined meg, at the co-processor adapter's shared storage window location.

    Highest task number:
    the highest task number that can be loaded on the co-processor adapter.

    Highest priority value:
    the lowest priority level (highest priority number) that can be assigned.

    Highest queue number:
    the highest queue number that can be allocated on the co-processor adapter.

    Highest timer number:
    the highest software timer number that can be allocated on the co-processor adapter.

    CAD16 .. CAD23:
    the high byte of the physical address that causes co-processor adapter memory to degate. When combined with the CAD0..CAD15 field, this defines the system unit address that causes the co-processor adapter's memory to degate when the address is accessed.

    CAD0 .. CAD15:
    the low-word of the physical address that causes co-processor adapter memory to degate.

    Interrupt level index:
    an index that indicates the interrupt level on which the co-processor adapter interacts with the system unit. The following chart shows the correlation between the interrupt level index and the actual interrupt level:
         Index    Interrupt Level
         -----    ---------------
           0            3
           1            4
           2            7
           3            9
           4           10
           5           11
           6           12
           7           15
    
    Shared storage window size:
    the size code that indicates the size of the co-processor adapter's shared storage window. The following chart matches the size code with the window size:
        Size Code     Window Size
        ---------     -----------
            0             8KB
            1            16KB
            2            32KB
            3            64KB
    
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    
    Remarks

    The GetParameters function returns the configuration parameters for the given co-processor adapter in the data packet. These parameters are defined in the parameter file. The device driver uses these parameters when initializing the co-processor adapter.

    GetSecondaryStatus


    Purpose

    GetSecondaryStatus reads the contents of a task's secondary status buffer.

    Category Code: F0h
    Function Code: 67h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
       Length                         WORD
       Status flag                    BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Destination buffer pointer    DWORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the task number of the buffer owner.

    Length:
    the number of bytes to read. The number of bytes actually read returns in this field. A value of zero indicates that 64KB should be read.

    Status flag:
    the control bits that determine when the secondary status buffer should be read. The bits have the format 0000 000a where a=1 indicates that the buffer should be read only if the status available bit is set in the task's primary status byte; a value of a=0 indicates that the secondary status buffer should be read regardless of the value of the status available bit.

    Destination buffer pointer:
    a double word pointer to where the secondary status buffer data is stored.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF0Ch = ERROR_ICA_STATUS_NOT_READY
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The GetSecondaryStatus function reads the contents of the given task's secondary status buffer. If a length greater than the size of the secondary status buffer is specified, the function reads only the number of bytes in the secondary status buffer; the size of the secondary status buffer is read from the task's Buffer Control Block. The number of bytes actually read is returned in the Length field of the parameter packet.

    This function does not require the caller to own the shared storage window for the co-processor adapter.

    GetVersion


    Purpose

    GetVersion will return the release level for this and all succeeding versions of the driver.

    Category Code: F0h
    Function Code: 69h

    Parameter Packet Format

    None

    Data Packet Format

       Field                         Length
    ------------------------------------------
       Minor version code             BYTE
       Major version code             BYTE
    
    Field Definitions

    Minor version code:
    this field has the fractional portion of the version number. The value is BC where the version is A.BC. In this release, the field has a value of 03h.

    Major version code:
    this field has the integer portion of the version number. The value is A where the version is A.BC. In this release, the field has a value of 01h.
    Returns

    No error

    Remarks

    The GetVersion function returns the version level of the installed driver, enabling users to determine what services are available. An error code of 0xFF0E (invalid function or category code) indicates that the original device driver is installed.

    InputBuffer


    Purpose

    InputBuffer reads the address and length of a task's input buffer from the task's Buffer Control Block.

    Category Code: F0h
    Function Code: 61h

    Parameter Packet Format

       Field                         Length
    --------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
    
    Data Packet Format
       Field                         Length
    --------------------------------------------
       Length                         WORD
       Offset                         WORD
       Page                           BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the task number of the buffer owner.

    Length:
    the length of the task's input buffer (returned by the function).

    Offset:
    the page offset of the task's input buffer (returned by the function).

    Page:
    the page of the task's input buffer (returned by the function).
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    
    Remarks

    The InputBuffer function reads the length and address of the task's input buffer and stores them in the data packet. This address may then read or write the buffer.

    This function does not require the caller to own the shared storage window for the co-processor adapter.

    IssueCommand


    Purpose

    IssueCommand issues a command with parameters to a task.

    Category Code: F0h
    Function Code: 4Ah

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
       Command code                   BYTE
       Length                         WORD
       Time-out                       WORD
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Parameter pointer             DWORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the task number of the task to receive the command.

    Command code:
    the command code to put in the task's Buffer Control Block.

    Length:
    the number of parameter bytes to write to the task's output buffer. A value of zero indicates that no parameter bytes should be written.

    Time-out:
    the number of milliseconds to wait for the Realtime Control Microcode to respond to the command.

    Parameter pointer:
    the double word pointer to parameter bytes that are written to the task's output buffer.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF0Bh = ERROR_ICA_CMD_TIMEOUT
    FF14h = ERROR_ICA_OB_TOO_SHORT
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    FF11h = ERROR_ICA_ BAD_PCSELECT
    FF12h = ERROR_ICA_COMMAND_REJECTED
    FF13h = ERROR_ICA_NO_CMD_RESPONSE
    
    Remarks

    The IssueCommand function issues a command to a task on a given co-processor adapter. A length of 0 is passed to the function if there are no parameters to write. If the length parameter is larger than the size of the task's output buffer, an error is returned to the application.

    The calling application does not need to own the co-processor adapter's shared storage window to call this function.

    Lock


    Purpose

    Lock locks a segment and obtains its physical address. The locked memory can then be used for bus master transfers via the Peer Services.

    Note:

    This routine is necessary only when using the Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Category Code: F0h
    Function Code: 4Fh

    Parameter Packet Format

       Field                         Length
    ---------------------------------------------
       Selector                      WORD
    
    Data Packet Format
       Field                         Length
    ---------------------------------------------
       Lock handle                   DWORD
       Physical address              DWORD
    
    Field Definitions

    Selector:
    This field contains the locked selector. The driver locks this segment and passes back the 32-bit physical address for offset 0 within the selector.

    Lock Handle:
    This is the handle for the locked selector. The Lock Handle is used to unlock the segment when it is no longer needed.

    Physical Address:
    This is the 32-bit physical address of offset 0 in the given Selector. This field is returned by the driver.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    

    Notify


    Purpose

    Notify registers a semaphore with the device driver for special events on the co-processor adapter.

    Category Code: F0h
    Function Code: 4Bh

    Parameter Packet Format

       Field                         Length
    ------------------------------------------
       Co-processor adapter number    BYTE
       Control flag                   BYTE
       Semaphore handle              DWORD
    
    Data Packet Format
       Field                         Length
    ------------------------------------------
       reserved                       WORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Control flag:
    control bits indicating the events for which the semaphore should be registered. The format of the control flag is a000 0000 where a=1 means the semaphore should be registered for Initialize commands issued to Realtime Control Microcode on the given co-processor adapter.

    Semaphore handle:
    the double word handle of the semaphore to register with the device driver.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Dh = ERROR_ICA_INVALID_CONTROL
    FF15h = ERROR_ICA_SEM_FULL
    FF1Dh = ERROR_ICA_BAD_SEMAPHORE
    
    Remarks

    The Notify function registers a semaphore with the device driver for notification of Initialize commands to Realtime Control Microcode. When an Initialize command is issued to Realtime Control Microcode on the specified co-processor adapter, all semaphores registered for that co-processor adapter with the Notify function are cleared. Application threads should call DosSemWait with the semaphore after registering the semaphore with the Notify function. A maximum of 255 semaphores may be registered with the device driver.

    The semaphore should be made non-exclusive by the DosCreateSem call.

    Open


    Purpose

    Open acquires a device handle to be used in requesting device driver services.

    Remarks

    This function is not a Generic IOCtl function; it should be called through the DosOpen call. This returns, to the caller, a device handle used for the device driver's Generic IOCtl calls and for the dynamic link routines.

    The following parameters should be passed to DosOpen:

    OutputBuffer


    Purpose

    OutputBuffer reads the address and length of a task's output buffer from the task's Buffer Control Block.

    Category Code: F0h
    Function Code: 62h

    Parameter Packet Format

       Field                         Length
    --------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
    
    Data Packet Format
       Field                         Length
    --------------------------------------------
       Length                         WORD
       Offset                         WORD
       Page                           BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the task number of the buffer owner.

    Length:
    the length of the task's output buffer (returned by the function).

    Offset:
    the page offset of the task's output buffer (returned by the function).

    Page:
    the page of the task's output buffer (returned by the function).
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The OutputBuffer function reads the length and address of the task's output buffer and stores them in the data packet. This address can then read or write the buffer.

    This function does not require the caller to own the shared storage window for the co-processor adapter.

    PeerClose


    Purpose

    PeerClose closes a peer handle and terminates usage of peer services.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A adapter.

    CategoryCode: F0h
    Function Code: 6Ch

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Peer Handle                   WORD
       Disp code                     WORD
       Reserved                      DWORD
    
    Data Packet Format

    None

    Field Definitions

    Peer handle:
    The peer handle to be closed.

    Disp code:
    This field controls the handling of any unreceived request blocks on a close. A value of 0 causes the request blocks to be purged. A value of 1 causes the close request to fail with error code ERROR_ICA_REQS_REMAIN if any unreceived peer request blocks are queued.

    Reserved:
    reserved and must be 0.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF17h = ERROR_ICA_BAD_HANDLE
    FF18h = ERROR_ICA_REQS_REMAIN
    

    PeerOpen


    Purpose

    PeerOpen establishes an application as a peer task within the system unit.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A adapter.

    Category Code: F0h
    Function Code: 6Bh

    Parameter Packet Format

       Field                         Length
    ---------------------------------------------
       Peer Segment                  WORD
       Peer Segment Size             WORD
       Sem handle                    DWORD
       Reserved                      DWORD
    
    Data Packet Format
       Field                         Length
    ---------------------------------------------
       Peer handle                    WORD
       Reserved                       DWORD
    
    Field Definitions

    Sem handle:
    The semaphore handle the driver clears to signal incoming peer request blocks.

    Peer segment:
    A block of memory used by the driver to pass peer request blocks to the application. The driver locks this memory. The format of the peer segment passed to the driver follows:
      Buffer size         Peer request blocks
    ---------------------------------------------
      WORD                Peer handle
      DWORD               Driver sem handle
      WORD                Rx wait flag
      WORD                Head PRB pointer
      WORD                Tail PRB pointer
      WORD                Tail Rx PRB pointer
      WORD                Buffer size
      WORD                Buffer count
      WORD                Reserved
      DWORD               Reserved
    
    The fields in the peer segment are defined as follows.

    Peer handle:
    Initialized by the driver and contains the peer handle of the application that owns this peer segment.

    Driver sem handle:
    Contains the semaphore handle used by the driver to signal incoming peer request blocks. It is initialized by the driver.

    Rx wait flag:
    This Boolean flag indicates if the application is waiting for a peer request block via the semaphore. If the flag is true, the driver signals the semaphore when an incoming peer request block arrives. The caller (the ICADevReceive DLL routine) initializes and sets this flag when waiting for the semaphore. The driver resets this flag when it clears the semaphore.

    Head PRB pointer:
    This is the offset of the oldest peer request block in the peer request block list. It is initialized to 0 and updated exclusively by the driver.

    Tail PRB pointer:
    This is the offset of the newest peer request block in the peer request block list. It is initialized to 0 and updated exclusively by the driver.

    Tail Rx PRB pointer:
    This field is for use by the caller to keep track of the last peer request block received. This field allows the caller to process peer request blocks in the peer request block list and allows the driver to continue receiving peer request blocks. The ICADevReceive and ICADevReceiveDone DLL routines use this field to point to the last peer request block passed to the caller. It is initialized and used exclusively by the caller.

    Buffer size:
    the size of the peer request block area. It is initialized by the caller.

    Peer request blocks:
    the data area reserved for passing peer request blocks. The driver copies received peer request blocks to this area.

    Peer handle:
    The peer handle will be returned to the application by the driver in this field.

    Peer segment size:
    The size, in bytes, of the peer segment.

    Reserved:
    reserved and must be 0.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF16h = ERROR_ICA_NO_PEER_HANDLE
    

    PeerSend


    Purpose

    PeerSend sends a peer request block.

    Note:

    This routine requires Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Category Code: F0h
    Function Code: 4Eh

    Parameter Packet Format

       Field                         Length
    ------------------------------------------
       Peer request block            WORD
    
    Data Packet Format

    None

    Field Definitions

    Peer request block:
    A pointer to the peer request block to be sent. The peer request block, used only with the Realtime Interface Co-Processor Portmaster Adapter/A adapter, sends a peer request to a task on a local or remote processor. The remote processor can either be another Realtime Interface Co-Processor Portmaster Adapter/A adapter or the system unit. Refer to the Realtime Control Microcode Firmware Technical Reference for the format of the peer request block.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF21h = ERROR_ICA_BAD_PARM
    
    The error codes on a bad peer request block return in the completion code field of the peer request block. Refer to the IBM Realtime Interface Co-Processor Firmware Technical Reference for a complete list of peer request block completion codes.

    PrimaryStatus


    Purpose

    PrimaryStatus reads the primary status byte for a given task.

    Category Code: F0h
    Function Code: 64h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Primary status byte            BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the number of the task whose primary status byte is returned.

    Primary status byte:
    the value of the task's primary status (returned by the function).
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    
    Remarks

    The PrimaryStatus function returns the value of the given task's primary status byte in the data packet. See the IBM Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport, and Realtime Interface Co-Processor Multiport/2 Technical Reference, or the IBM Realtime Interface Co-Processor Firmware Technical Reference, for the meanings of the primary status bits.

    PutOutputBuffer


    Purpose

    PutOutputBuffer writes a buffer to the given task's output buffer.

    Category Code: F0h
    Function Code: 49h

    Parameter Packet Format

       Field                         Length
    ------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
       Length                         WORD
    
    Data Packet Format
       Field                         Length
    ------------------------------------------
       Source buffer pointer         DWORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the task number of the buffer owner.

    Length:
    the number of bytes to write. The number of bytes actually written is returned in this field. A value of 0 indicates that 64KB should be written.

    Source buffer pointer:
    a double word pointer to the data that should be written to the task's output buffer.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The PutOutputBuffer function writes a buffer to the given task's output buffer. If a length greater than the size of the output buffer is specified, the function writes only enough bytes to fill the output buffer; the size of the output buffer is read from the task's Buffer Control Block. The number of bytes actually written is returned in the data packet.

    This function does not require the caller to own the shared storage window for the co-processor adapter.

    ReadString


    Purpose

    ReadString reads a given co-processor adapter's memory into an application buffer.

    Category Code: F0h
    Function Code: 65h

    Parameter Packet Format

       Field                         Length
    -----------------------------------------
       Co-processor adapter number    BYTE
    
    Data Packet Format
       Field                         Length
    -----------------------------------------
       Length                         WORD
       Offset                         WORD
       Segment/page                   WORD
       Address format                 BYTE
       Destination buffer pointer    DWORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Length:
    the number of bytes to read from co-processor adapter memory. A value of 0 indicates that 64KB should be read.

    Offset:
    the offset of memory address. The meaning of this field is determined by the Address format field.

    Segment/page:
    the segment or page of the memory address. The meaning of this field is determined by the Address format field.

    Address format:
    the control field determining the address format. If the field contains 00, the Segment/page field is a segment in co-processor adapter memory, and the Offset field is an offset in that segment. If the field contains FFh, the Segment/page field contains the page number of the read, and the Offset field contains the page offset of the read. If the field contains 01h, the Segment/page and offset fields are a 32-bit physical address. The least significant 16-bits are in the offset field.

    Note:

    Logical segment:offset addresses are converted to page:offset addresses, assuming there is direct memory mapping on Realtime Interface Co-Processor Portmaster Adapter/A. Physical page:offset addresses should be used when physical Realtime Interface Co-Processor Portmaster Adapter/A memory is remapped in the 80186 logical address space. The application is responsible for ensuring that the physical memory on the Realtime Interface Co-Processor Portmaster Adapter/A adapter can be addressed.

    Destination buffer pointer:
    a double word pointer to the buffer where the co-processor adapter memory is be copied.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF07h = ERROR_ICA_INVALID_PAGE
    FF08h = ERROR_ICA_INVALID_OFFSET
    FF09h = ERROR_ICA_INVALID_FORMAT
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The ReadString function reads co-processor adapter memory into a system unit buffer. The address in co-processor adapter memory can be specified either as a segment and offset or as a page and offset.

    This function does not require the caller to own the shared storage window of the co-processor adapter.

    RegisterSemaphore


    Purpose

    RegisterSemaphore registers a semaphore for task interrupts.

    Category Code: F0h
    Function Code: 47h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
       Semaphore handle              DWORD
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       reserved                       WORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the registered semaphore number of the task.

    Semaphore handle:
    the double word semaphore handle returned by DosCreateSem. This semaphore clears when an interrupt is received from the given task on the given co-processor adapter.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF15h = ERROR_ICA_SEM_FULL
    FF1Dh = ERROR_ICA_BAD_SEMAPHORE
    
    Remarks

    The RegisterSemaphore function registers an application semaphore with the device driver. Semaphores are a means of synchronization between system unit applications and co-processor adapter tasks. When a task on a co-processor adapter interrupts the system unit, the device driver clears any semaphores registered for that task and co-processor adapter. The following steps indicate how an application waits for a task. The application task:

    1. Creates a non-exclusive semaphore with the DosCreateSem command.

    2. Sets the semaphore with the DosSemSet call.

    3. Registers the semaphore with the RegisterSemaphore call.

    4. Calls DosSemWait to wait for the semaphore to be cleared.
    A maximum of 255 semaphores may be registered with the device driver.

    RemoveNotify


    Purpose

    RemoveNotify removes a semaphore from the device driver list for notification of special events.

    Category Code: F0h
    Function Code: 4Ch

    Parameter Packet Format

       Field                         Length
    ------------------------------------------
       Co-processor adapter number    BYTE
       Control flag                   BYTE
       Semaphore handle              DWORD
    
    Data Packet Format
       Field                         Length
    ------------------------------------------
       Reserved                       WORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Control flag:
    control bits indicating the events for which the semaphore should no longer be registered. The format of the control flag is a000 0000 where a=1 means that the semaphore should no longer be registered for Initialize commands to Realtime Control Microcode on the given co-processor adapter.

    Semaphore handle:
    the double word handle of the semaphore registered with the device driver.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Dh = ERROR_ICA_INVALID_CONTROL
    FF1Dh = ERROR_ICA_BAD_SEMAPHORE
    
    Remarks

    The RemoveNotify function removes and clears a semaphore from the device driver list for notification of special events. Before termination, all processes should use this function to remove semaphores registered with the Notify function.

    RemoveSemaphore


    Purpose

    RemoveSemaphore removes a semaphore from the device driver's list of registered semaphores.

    Category Code: F0h
    Function Code: 48h

    Parameter Packet Format

       Field                         Length
    ------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
       Semaphore handle              DWORD
    
    Data Packet Format
       Field                         Length
    ------------------------------------------
       Reserved                       WORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the number of the task for which the semaphore was registered.

    Semaphore handle:
    the double word semaphore handle returned by DosCreateSem. This semaphore is removed from the device driver's internal list of semaphores when an interrupt is received from the task on the co-processor adapter.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    FF1Dh = ERROR_ICA_BAD_SEMAPHORE
    
    Remarks

    The RemoveSemaphore function removes and clears an application's semaphore from the registered semaphore list in the device driver. When an application no longer needs notification of interrupts from the task, it de-registers the semaphore with the RemoveSemaphore function.

    Reset


    Purpose

    Reset issues a hardware reset to the given co-processor adapter.

    Category Code: F0h
    Function Code: 40h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Reserved                       BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter to reset.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    
    Remarks

    The Reset function issues a hardware reset to the co-processor adapter. The Realtime Control Microcode and all other tasks are unloaded and the co-processor adapter performs a power-on self test (POST).

    SecondaryStatus


    Purpose

    SecondaryStatus reads the address of a task's secondary status buffer from the task's Buffer Control Block.

    Category Code: F0h
    Function Code: 63h

    Parameter Packet Format

       Field                         Length
    ------------------------------------------
       Co-processor adapter number    BYTE
       Task number                    BYTE
    
    Data Packet Format
       Field                         Length
    ------------------------------------------
       Length                         WORD
       Offset                         WORD
       Page                           BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Task number:
    the task number of the buffer owner.

    Length:
    the length of the task's secondary status buffer (returned by the function).

    Offset:
    the page offset of the task's secondary status buffer (returned by the function).

    Page:
    the page of the task's secondary status buffer (returned by the function).
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF06h = ERROR_ICA_INVALID_TASK_STATUS
    
    Remarks

    The SecondaryStatus function reads the length and address of the task's output buffer and stores them in the data packet. This address can then be used to read or write to the buffer.

    This function does not require the caller to own the shared storage window for the co-processor adapter.

    TaskFlush


    Purpose

    TaskFlush flushes all requests from the calling process for services from the device driver.

    Category Code: F0h
    Function Code: 45h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       reserved                       BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Reserved                       BYTE
    
    Field Definitions

    Bytes in the parameter and data packets are left for future expansion.

    Returns

    None

    Remarks

    The TaskFlush function flushes any window requests by the calling process, releases any co-processor adapter windows owned by the calling process, and de-registers any semaphores registered with the device driver by the calling process. This function may be used in an application exit routine before terminating the process.

    UnLock


    Purpose

    Unlock unlocks a segment previously locked by the Lock function.

    Note:

    This routine is only necessary when using Realtime Control Microcode Version 2.0 and the Realtime Interface Co-Processor Portmaster Adapter/A.

    Category Code: F0h
    Function Code: 50h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Lock handle                   DWORD
    
    Data Packet Format

    None

    Field Definitions

    Lock Handle:
    the handle of the segment to be unlocked.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    

    WindowRelease


    Purpose

    WindowRelease releases ownership of a co-processor adapter shared storage window.

    Category Code: F0h
    Function Code: 44h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       reserved                       BYTE
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter shared storage window to be released.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Ah = ERROR_ICA_WIN_RESERVED
    
    Remarks

    The WindowRelease function releases ownership of the shared storage window of the co-processor adapter, leaving the window free for acquisition by another adapter. The selector created for referencing the window is removed from the process's Local Descriptor Table.

    WindowReserveNoWait


    Purpose

    WindowReserveNoWait requests ownership of a co-processor adapter shared storage window. The call returns if the window is already owned.

    Category Code: F0h
    Function Code: 43h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Base address of window        DWORD
       PID                            WORD
       Thread ID                      WORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter shared storage window to be reserved.

    Base address of window:
    a double word pointer to the start of the co-processor adapter's shared storage window.

    PID:
    the process ID of the owning thread if the window is already owned.

    Thread ID:
    the thread ID of the owning thread if the window is already owned.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Ah = ERROR_ICA_WIN_RESERVED
    
    Remarks

    The WindowReserveNoWait function requests ownership of the shared storage window for the given co-processor adapter. If the window is already owned by another thread, the function returns immediately with the process ID and thread ID of the window owner. If the call is successful, a double word pointer to the shared storage window is returned to the calling thread; this pointer can be used to read or write to the co-processor adapter memory. A selector is added to the process's Local Descriptor Table for referencing the shared storage window.

    WindowReserveWait


    Purpose

    WindowReserveWait requests ownership of a co-processor adapter shared storage window; the call is blocked if the window is already owned.

    Category Code: F0h
    Function Code: 42h

    Parameter Packet Format

       Field                         Length
    --------------------------------------------
       Co-processor adapter number    BYTE
       Time-out                      DWORD
       Reserved                      DWORD
    
    Data Packet Format
       Field                         Length
    --------------------------------------------
       Base address of window        DWORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter shared storage window to reserve.

    Time-out:
    the length of time in milliseconds to wait for ownership of the window.

    Base address of window:
    a double word pointer to the start of the co-processor adapter's shared storage window.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF0Bh = ERROR_ICA_TIMEOUT
    
    Remarks

    The WindowReserveWait function requests ownership of the shared storage window for the given co-processor adapter. If another thread owns the window, the calling thread is blocked until either the window is released or the wait times out. If the call is successful, a double word pointer to the shared storage window is returned to the calling thread. This pointer can be used to read and write to the co-processor adapter memory. A selector is added to the process's Local Descriptor Table for referencing the shared storage window.

    WriteString


    Purpose

    WriteString writes an application buffer to the given co-processor adapter's memory.

    Category Code: F0h
    Function Code: 46h

    Parameter Packet Format

       Field                         Length
    -------------------------------------------
       Co-processor adapter number    BYTE
    
    Data Packet Format
       Field                         Length
    -------------------------------------------
       Length                         WORD
       Offset                         WORD
       Segment/page                   WORD
       Address format                 BYTE
       Source buffer pointer         DWORD
    
    Field Definitions

    Co-processor adapter number:
    the logical number of the co-processor adapter.

    Length:
    the number of bytes to write to co-processor adapter memory. A value of 0 indicates that 64KB should be written.

    Offset:
    the offset of the memory address. See the definition of the Address format field for more information.

    Segment/page:
    the segment or page of the memory address. See the definition of the Address format field for more information.

    Address format:
    the control field determining the address format. If the field contains 00, the Segment/page field is a segment in co-processor adapter memory, and the Offset field is an offset in that segment. If the field contains FFh, the Segment/page field contains the page number of the read, and the Offset field contains the page offset of the read. If the field contains 01, the high-word field contains the high-word of the 32-bit physical address and the low-word field contains the low-word of the 32 bit physical address. If the field contains 01h, the Segment/page and offset fields are a 32-bit physical address. The least significant 16-bits are in the offset field.

    Note:

    Logical segment:offset addresses are converted to page:offset addresses assuming that there is direct memory mapping on Realtime Interface Co-Processor Portmaster Adapter/A. Physical page:offset addresses should be used when physical Realtime Interface Co-Processor Portmaster Adapter/A memory is remapped in the 80186 logical address space. The application is responsible for ensuring that the physical memory on the Realtime Interface Co-Processor Portmaster Adapter/A adapter can be addressed.

    Source buffer pointer:
    a double word pointer to the buffer to copy to co-processor adapter memory.
    Returns
    IF      AX=0 then NO error
    ELSE    AX=error code
    
    FF05h = ERROR_ICA_INVALID_COPROC
    FF07h = ERROR_ICA_INVALID_PAGE
    FF08h = ERROR_ICA_INVALID_OFFSET
    FF09h = ERROR_ICA_INVALID_FORMAT
    FF1Ch = ERROR_ICA_BAD_ADDRESS
    
    Remarks

    The WriteString function writes a system unit buffer to co-processor adapter memory. The address of the co-processor adapter memory can be specified either as a segment and offset or as a page and offset. The Format parameter should have a value of FFh for page and offset addresses; a value of 00 designates a segment and offset address; a value of 01 designates a 32-bit physical address.


    Chapter 9. Online Dump Facility

    The Online Dump Facility is a debugging tool that dumps the memory contents and I/O port values of a co-processor adapter to a disk file. This disk file can then be formatted using the FRMTDUMP.EXE file in the Dump Formatter Facility supplied with your OS/2 Support Version 1.03.4 product. Dump data can be dumped to fixed disk or to multiple diskettes, either interactively by the user or automatically with the AutoDump feature.

    Note:

    The Online Dump Facility can be invoked only in a protect mode session of OS/2.

    Starting the Online Dump Facility

    The following commands invoke the Online Dump Facility:

          ICADPRIC [n...] [ARM(n...)] [DMP(n...)] [d:] [HELP]
             OR
          ICADPRIC n d: U
    
          where:
            n        = coprocs to dump
            ARM(n..) = coprocs to arm
            DMP(n..) = coprocs to AutoDump
            d:       = dump drive
            HELP     = help information
            U        = unattended dump
    
    If a number is entered on the command line, the Online Dump Facility writes the corresponding co-processor adapter's data to a disk file. If the ARM string is entered on the command line, the list of numbers in parentheses that follow are interpreted as co-processor adapters to arm for later dumps. If the DMP string is entered on the command line, the list of numbers in parentheses that follow are interpreted as co-processor adapters to arm for AutoDump. If a drive letter is entered as a command line parameter, the Online Dump Facility writes all dump data to this drive. If the HELP string is entered on the command line, the calling format of the Online Dump Facility is displayed.

    If the letter U is entered as a command line parameter, the Online Dump Facility will dump the adapter immediately and return to the operating system. This option is used to run the dump facility in a non-interactive, unattended mode. When this option is used, there are no messages to the console and no keyboard input is required.


    Output Files

    The Online Dump Facility produces a system file and one or more memory files. The system file has the format ICASYSn.DMP where "n" is the hexadecimal number of the co-processor adapter that was dumped. The memory files have the format ICAMEnii.DMP where "n" is the hexadecimal number of the co-processor adapter that was dumped. The "ii" is the diskette number of the memory data; this is not used if the data is dumped to fixed disk.


    Dumping a Co-Processor Adapter

    Users can dump co-processor adapters to get their state at any time. This can be done at invocation of the Online Dump Facility by entering the co-processor adapter number as a command line parameter. This can also be done through the menus of the Online Dump Facility. This section describes the Online Dump Facility menus for dumping a co-processor adapter.

    To dump a co-processor adapter through the menus, press 3 to choose the dump option in the main menu.

          Press
            1   to arm a co-proc
            2   to restore a co-proc
            3   to dump a co-proc
            4   to enable AutoDump on a co-proc
            5   to change the dump drive
            9   to return to OS/2
    
    A menu is displayed for choosing the logical number of the co-processor adapter to dump. The co-processor adapter number is determined by the order of the records in the parameter file.
          Press
            0   to dump co-proc 0
            1   to dump co-proc 1
            2   to dump co-proc 2
            3   to dump co-proc 3
            4   to dump co-proc 4
            5   to dump co-proc 5
            6   to dump co-proc 6
            7   to dump co-proc 7
            9   to return to the main menu
          Enter to switch co-proc sets
    
    The Enter key allows the user to select the next set of co-processor adapters. The Realtime Interface Co-Processor Operating System/2 Support software is designed to support up to 16 co-processor adapters. If the Enter key is pressed, the following menu is displayed:
          Press
            0   to dump co-proc 8
            1   to dump co-proc 9
            2   to dump co-proc 10
            3   to dump co-proc 11
            4   to dump co-proc 12
            5   to dump co-proc 13
            6   to dump co-proc 14
            7   to dump co-proc 15
            9   to return to the main menu
          Enter to switch co-proc sets
    
    If the Enter key is pressed again, control returns to the first selection menu. Pressing the 9 key returns control to the main menu.

    When the user has selected the co-processor adapter to dump and has pressed the appropriate key, one of two messages is displayed. If the dump drive is a fixed disk, the following message is displayed:

          Writing dump data to fixed disk d:
    
    The d: is the drive letter. In this case, the dump begins immediately. If the dump drive is a diskette drive, the following message is displayed:
          Writing dump data to diskette d:
    
    The d: is the destination drive of the dump data. In this case, the following menu is displayed:
          Place diskette 0 in drive d:
    
          Press
            1   to continue dump of co-proc n
            9   to abort dump and return to main menu
    
    The number n is the logical number of the co-processor adapter to dump. To abort the dump, press the 9 key; otherwise, make sure that the drive is ready for the data, and press the 1 key to continue. The Online Dump Facility dumps the co-processor adapter's memory contents and I/O port values to the diskette. If there is not enough space on the diskette for all of the dump data, the Online Dump Facility prompts the user for another diskette; if this occurs, insert a new diskette in the diskette drive and press 1 to continue.

    When all the co-processor adapter's memory and I/O ports have been dumped, the following message is displayed:

            Dump completed
    
    Control then returns to the main menu where the user can select the next action.

    Arming a Co-Processor Adapter

    Users can arm a co-processor adapter for a later dump. If a co-processor has been armed by the Online Dump Facility, it requests a dump after a Level 1 error occurs on the co-processor adapter.

    To arm a co-processor adapter by using the menus, press 1 to choose the dump option on the main menu.

          Press
            1   to arm a co-proc
            2   to restore a co-proc
            3   to dump a co-proc
            4   to enable AutoDump on a co-proc
            5   to change the dump drive
            9   to return to OS/2
    
    A menu is displayed for choosing the number of the co-processor adapter to arm:.
          Press
            0   to arm co-proc 0
            1   to arm co-proc 1
            2   to arm co-proc 2
            3   to arm co-proc 3
            4   to arm co-proc 4
            5   to arm co-proc 5
            6   to arm co-proc 6
            7   to arm co-proc 7
            9   to return to the main menu
          Enter to switch co-proc sets
    
    The Enter key allows the user to select the next set of co-processor adapters. The architecture of the Realtime Interface Co-Processor Operating System/2 Support software supports up to 16 co-processor adapters. If the Enter key is pressed, the following menu is displayed:
          Press
            0   to arm co-proc 8
            1   to arm co-proc 9
            2   to arm co-proc 10
            3   to arm co-proc 11
            4   to arm co-proc 12
            5   to arm co-proc 13
            6   to arm co-proc 14
            7   to arm co-proc 15
            9   to return to the main menu
          Enter to switch co-proc sets
    
    If the Enter key is pressed again, control returns to the first selection menu. Pressing the 9 key returns control to the main menu.

    When the user has selected the co-processor adapter to arm and pressed the appropriate key, the Online Dump Facility acquires the breakpoint and watchdog timer vectors on the co-processor; it also sets the watchdog timer to a time-out length of approximately 12 milliseconds. When the watchdog timer expires or a breakpoint is hit, the co-processor adapter requests a dump. When a co-processor adapter requests a dump, the Online Dump Facility displays its logical number at the start of the action menus. See "Dumping a Co-Processor Adapter" for information on dumping the co-processor adapter after it has requested a dump.


    Restoring a Co-Processor Adapter

    Users can restore a co-processor adapter after it has been armed. This restores the watchdog timer to its previous state, and restores the breakpoint and watchdog timer vectors to their previous values.

    To restore a co-processor adapter using the menus, press 2 to choose the restore option in the main menu.

          Press
            1   to arm a co-proc
            2   to restore a co-proc
            3   to dump a co-proc
            4   to enable AutoDump on a co-proc
            5   to change the dump drive
            9   to return to OS/2
    
    A menu is displayed for choosing the number of the co-processor adapter to restore.
          Press
            0   to restore co-proc 0
            1   to restore co-proc 1
            2   to restore co-proc 2
            3   to restore co-proc 3
            4   to restore co-proc 4
            5   to restore co-proc 5
            6   to restore co-proc 6
            7   to restore co-proc 7
            9   to return to the main menu
          Enter to switch co-proc sets
    
    The Enter key allows the user to select the next set of co-processor adapters. The architecture of the Realtime Interface Co-Processor Operating System/2 Support software supports up to 16 co-processor adapters. If the ENTER key is pressed, the following menu is displayed:
          Press
            0   to restore co-proc 8
            1   to restore co-proc 9
            2   to restore co-proc 10
            3   to restore co-proc 11
            4   to restore co-proc 12
            5   to restore co-proc 13
            6   to restore co-proc 14
            7   to restore co-proc 15
            9   to return to the main menu
          Enter to switch co-proc sets
    
    If the Enter key is pressed again, control returns to the first selection menu. Pressing the 9 key returns control to the main menu.

    When the user presses a key to restore the co-processor adapter, the Online Dump Facility restores the breakpoint and watchdog timer vectors on the co-processor and the watchdog timer to its previous state.


    Arming a Co-Processor Adapter for AutoDump

    Users can arm a co-processor adapter so its memory and I/O ports are dumped automatically to disk when a Level 1 error occurs on the co-processor adapter. This section describes the Online Dump Facility menus for arming a co-processor adapter for AutoDump.

    To arm a co-processor adapter for AutoDump using the menus, the 4 key chooses the dump option on the main menu.

          Press
            1   to arm a co-proc
            2   to restore a co-proc
            3   to dump a co-proc
            4   to enable AutoDump on a co-proc
            5   to change the dump drive
            9   to return to OS/2
    
    A menu is displayed for choosing the number of the co-processor adapter to arm for AutoDump.
          Press
            0   to AutoDump co-proc 0
            1   to AutoDump co-proc 1
            2   to AutoDump co-proc 2
            3   to AutoDump co-proc 3
            4   to AutoDump co-proc 4
            5   to AutoDump co-proc 5
            6   to AutoDump co-proc 6
            7   to AutoDump co-proc 7
            9   to return to the main menu
          Enter to switch co-proc sets
    
    The Enter key allows the user to select the next set of co-processor adapters. The architecture of the Realtime Interface Co-Processor Operating System/2 Support software supports up to 16 co-processor adapters. If the ENTER key is pressed, the following menu is displayed:
          Press
            0   to AutoDump co-proc 8
            1   to AutoDump co-proc 9
            2   to AutoDump co-proc 10
            3   to AutoDump co-proc 11
            4   to AutoDump co-proc 12
            5   to AutoDump co-proc 13
            6   to AutoDump co-proc 14
            7   to AutoDump co-proc 15
            9   to return to the main menu
          Enter to switch co-proc sets
    
    If the Enter key is pressed again, control returns to the first selection menu. Pressing the 9 key returns control to the main menu.

    When the user selects the co-processor adapter to arm for AutoDump and presses the appropriate key, the Online Dump Facility acquires the breakpoint and watchdog timer vectors on the co-processor; it also sets the watchdog timer to a timeout length of approximately 12 milliseconds. When the watchdog timer expires or a breakpoint is hit, the co-processor adapter is automatically dumped without user intervention. The user should verify that the dump drive has enough free storage before arming a co-processor adapter for AutoDump.


    Changing the Dump Drive

    Users can change the disk or diskette drive being used for dumping co-processor adapter data. This section describes the Online Dump Facility menus for changing the dump drive.

    To select a new dump drive through the menus, press 5.

          Press
            1   to arm a co-proc
            2   to restore a co-proc
            3   to dump a co-proc
            4   to enable AutoDump on a co-proc
            5   to change the dump drive
            9   to return to OS/2
    
    The Online Dump Facility then prompts the user for a new dump drive letter.
             Enter dump drive letter:
    
    Type the letter corresponding to the desired dump drive. This changes the drive where dump data is written.

    Chapter 10. Dump Formatter Facility

    The Dump Formatter Facility converts the machine-readable images generated by the OS2 Support Online Dump Facility into a format for viewing and printing. This Dump Formatter Facility organizes the dump data into an easy-to-read format, using headers and blocks to group related information.

    The Dump Formatter Facility is provided with the Realtime Interface Co-Processor OS/2 Support product; it is an EXE file named FRMTDUMP.EXE. Along with this file, a profile is provided to allow the selection of configuration parameters; that file is named FRMTDUMP.PRO.

    The Dump Formatter also provides a Copy and Combine function. This function is used when the data files generated by the Online Dump Facility are stored on several diskettes. In this case, the data files must be combined into a single disk or diskette before the files can be formatted by the Dump Formatter Facility. If the source drive and the destination drive are both diskette drives, the Copy and Combine function requires that they be different drives. However, if the source drive and destination drive are on a fixed disk, they may be on the same disk.


    Output Files

    The Dump Formatter Facility creates at least two files when formatting a dump of a co-processor adapters memory and I/O image:

    1. One file containing the memory image. This file is named MEMORYn.PRT, where n is the logical co-processor adapter number (hexadecimal).

    2. One file containing the I/O image. This file is named SYSINFOn.PRT, where n is the logical co-processor adapter number (hexadecimal).
    MEMORYn.PRT contains the formatted contents of co-processor adapter memory. SYSINFOn.PRT contains all information, other than the contents of memory, which includes co-processor adapter software version numbers, microprocessor register contents, I/O ports, the free-memory listing, and task information.

    Dump Formatter Facility Invocation

    If the dump files are on multiple diskettes, use the Copy and Combine function to create a single file before using the formatting function to format the file.

    Invoking the Copy and Combine Function

    To invoke the Dump Formatter Facility's Copy and Combine function, the following syntax is required:

    FRMTDUMP CC n < source < dest. > >

    
         Where:
    
             n = the logical co-processor adapter number
                            (hexadecimal).
    
    < source > = the path of the source dump data.
    
     < dest. > = the path of the destination (combined)
                 file.
    
    The following rules apply:

    1. If you specify only one path, it is assumed to be the source specification. The destination is assumed to be the current directory.

    2. If no drive or path is given, it is assumed that the root directory of drive A is the source and the current directory is the destination.

    3. The source drive cannot be the same as the destination drive if the drive is a diskette drive.

    4. Once the files are in their combined form (that is, they only have a single digit in the file name), they can be used to generate the final Dump Formatter Facility output files--SYSINFOn.PRT and MEMORYn.PRT.

    5. The source files must have the file names given them by the Online Dump Facility. The memory files (ICAMEnii.DMP) and the system file (ICASYSn.DMP) are required for the Copy and Combine operation.

    Invoking the Formatting Function

    To invoke the Dump Formatter Facility's Formatting function, the following syntax is required:

    FRMTDUMP n <M> <S> </O>

    
         Where:
    
           n  = the logical co-processor adapter number
                           (hexadecimal).
    
          <M> = causes the generation of MEMORYn.PRT.
    
          <S> = causes the generation of SYSINFOn.PRT.
    
         </O> = is the profile override feature.
    
    The following rules apply:

    1. If neither "M" nor "S" is specified, only the file MEMORYn.PRT is generated.

    2. The generated output files of the Dump Formatter Facility are placed in the current directory on the current drive.

    3. The /O override feature allows the user to enter new values for the following profile parameters: TITLE, USER_SEG, MEMLIST, and TASKLIST. Setting new parameter values does not alter the profile.
    The file FRMTDUMP.MSG contains the error messages for the Dump Formatter Facility.

    Dump Formatter Facility Profile

    You can tailor the Dump Formatter Facility output for different printers and different co-processor adapter dumps by setting variables in the Dump Formatter Facility profile (FRMTDUMP.PRO). You can use an ASCII text editor to change the profile. Before the Dump Formatter Facility generates SYSINFOn.PRT or MEMORYn.PRT, it attempts to locate FRMTDUMP.PRO. It examines the following directories in this order:

    If the Dump Formatter Facility (FRMTDUMP.EXE) is renamed, the filename of the profile must be changed to the same name. For example, changing the executable module name to "FORMDUMP.EXE" would cause the Dump Formatter Facility to look for the profile in "FORMDUMP.PRO".

    If the profile cannot be found, the default parameters are used. The default printer-specific parameters are for the IBM Graphics Printer.

    The following conventions apply to profile parameters:


    Profile Parameters

    Following is a list of the Dump Formatter Facility profile parameters:

    BOXCHARS
    - Printer codes for box characters.

    You can also specify the printer codes for generating box characters in the output files. Add the following line to the profile to set these parameters:

         BOXCHARS  = nn [,] nn [,] nn [,] nn [,] nn [,] nn
                     [,] nn [,] nn [,] nn [,] nn [,] nn
    

    Each "nn" represents the ASCII character code of a box character. The 11 codes are assigned in the order listed in the following table. The printer codes for the IBM Graphics Printer are also listed in the table. If the codes are not set or if there is an error in the list of codes, they default to the box characters of the IBM Graphics Printer.

         Vertical Bar         Default value = B3h (179 decimal)
    
         Horizontal Bar       Default value = C4h (196 decimal)
    
         Upper-left corner    Default value = DAh (218 decimal)
    
         Upper-right corner   Default value = BFh (191 decimal)
    
         Lower-right corner   Default value = D9h (217 decimal)
    
         Lower-left corner    Default value = C0h (192 decimal)
    
         Horizontal line      Default value = C3h (195 decimal)
         stops on vertical
         line from right
    
         Horizontal line      Default value = B4h (180 decimal)
         stops on vertical
         line from left
    
         Vertical line        Default value = C2h (194 decimal)
         stops on horizontal
         line from bottom
    
         Vertical line        Default value = C1h (193 decimal)
         stops on horizontal
         line from top
    
         Horizontal-vertical  Default value = C5h (197 decimal)
         line cross
    

    FORM_FEED
    - Printer formfeed sequence.

    This is the printer sequence for generating a formfeed. To set this parameter, add the following line to the profile:

         FORM_FEED = NONE | nn[[,]nn]...
    
    A list of up to 16 ASCII character codes can be entered for the formfeed sequence. This allows the user to set the profile for whatever printer is being used. If more than 16 codes are specified, or if any code exceeds 255, the default value 0Ch (12 decimal) is used. 0Ch is the standard ASCII code for formfeed.

    Specifying FORM_FEED = NONE indicates that no formfeed character exists for the printer being used. Instead, blank lines are printed in place of the formfeed character to bring the printer to the top of the next page. The PAGE_LINES parameter tells the Dump Formatter Facility how many blank lines to print.

    LONG
    - Complete memory listings

    If the keyword LONG is included in the profile, every line of memory is displayed regardless of the contents of memory. Omitting the keyword LONG can make the memory file MEMORYn.PRT shorter because redundant lines of memory are not redisplayed.

    MEMLIST - Memory dumped by location

    This parameter affects the contents of MEMORYn.PRT, but not of SYSINFOn.PRT. It specifies which blocks of memory are to be included in the output.

    To set this parameter, add the following line to the profile:

         MEMLIST = [ ALL ] [ NONE ] [ (NN [,]
         [+]NN) [,] ] ...
    
    Specifying ALL means that all co-processor adapter memory locations will be displayed in MEMORYn.PRT. Specifying NONE means that none of co-processor adapter memory will be displayed in MEMORYn.PRT.

    Ranges of co-processor adapter memory can be specified in terms of paragraphs (16 bytes). Ranges can be either a lower and upper bound or a lower bound and a length. Specifying (NN1 NN2) gives memory contents from paragraphs NN1 to NN2, inclusive. NN1 and NN2 specify paragraph boundaries and are numbers with the same range as described earlier. Either can be the smaller number, or they do not need to be ordered.

    Specifying (NN1 +NN2) gives memory contents starting at paragraph NN1 and continuing for NN2 paragraphs. For example,

         MEMLIST = (1000h, +20h)
    
    designates a total of 20h consecutive paragraphs, starting at paragraph 1000h (start address = 1000:0000).

    Some examples of the MEMLIST line follow:

         MEMLIST = ALL
    
    gives the contents of all installed co-processor adapter memory.
         MEMLIST = (1000h, 1FFFh) (3000h, 3FFFh)
    
    gives the memory contents of memory addresses 1000:000 through 1FFF:000F; also gives memory addresses 3000:0000 through 3FFF:000F.

    Note: Memory addresses 2000:0000 through 2FFF:000F are not generated.

         MEMLIST = (1000h, +1000h) (3000h, +1000h)
    
    gives the same results as the previous example.

    The default value for MEMLIST is NONE. The keywords ALL or NONE override parameters to the left of them. If conflicting keywords are found, the last (right-most) one overrides the others.

    PAGE_LINES - The Number of lines per page

    If a formfeed code is not available on your printer, this allows the Dump Formatter Facility to compute how many blank lines to generate.

    To set this parameter, add the following line to the profile:

         PAGE_LINES = nn
    
    The default value is 66 lines per page.

    POSTSTRING - Printer postfix sequence

    This sequence comes last in the MEMORYn.PRT and SYSINFOn.PRT files. Use it to return the printer to a desired state (for example, 80 character-per-line mode and 8 lines per inch).

    To set this parameter, add the following line to the profile:

         POSTSTRING = NONE | [nn[,]...]
    
    Specifying NONE results in no string being generated at the end of MEMORYn.PRT or SYSINFOn.PRT.

    The length of this string cannot exceed 256 bytes. If more than 256 integers are entered, or if any integer exceeds a value of 255, the default sequence of POSTSTRING is used.

    The default sequence is as follows:

         POSTSTRING = 12h
    
    This character sequence stops compressed character mode printing on the IBM Graphics Printer.

    PRESTRING - Printer prefix sequence

    This is the sequence that comes first in the MEMORYn.PRT and SYSINFOn.PRT files. Use it to force the printer into a desired state.

    To set this parameter, add the following line to the profile:

         PRESTRING = NONE | [ nn [,] ...]
    
    Specifying NONE results in no string being presented at the start of MEMORYn.PRT or SYSINFOn.PRT. The file then begins with formatted output, instead of printer-specific information.

    The length of this string cannot exceed 256 bytes; that is, no more than 256 integers can be presented on the line in FRMTDUMP.PRO. If more than 256 integers are presented, or if any integer exceeds a value of 255, the default sequence of PRESTRING is used.

    The Dump Formatter Facility defaults to the following:

         PRESTRING = 18h, 0Fh, 1Bh, 41h, 12, 1Bh, 32h,
                     1Bh, 36h, 1Bh, 39h, 1Bh, 43h, 66, 1Bh,
                     46h, 1Bh, 48h, 1Bh, 54h, 1Bh, 55h, 0
    
    This character sequence is for the IBM Graphics Printer and performs the following in this order:

    1. Clears the printer buffer
    2. Shifts the printer to compressed character mode (132 characters per line)
    3. Sets line spacing to six lines per inch
    4. Selects character set 2 on the IBM Graphics Printer
    5. Cancels any ignore paper end command
    6. Sets the page length to 66 lines per page
    7. Turns off printing in emphasized mode
    8. Turns off printing in double strike mode
    9. Turns off printing in superscript mode or subscript mode
    10. Sets the printer for bidirectional printing.

    Printer codes are explained in depth in the user's printer manual.

    PRINT_LINES - The Number of lines to print per page

    This parameter allows you to set the actual number of lines you want printed on a page. This parameter applies to SYSINFOn.PRT and MEMORYn.PRT. It cannot exceed the value of the PAGE_LINES parameter.

    To set this parameter, add the following line to the profile:

         PRINT_LINES = nn
    
    The default value is 60 lines per page.

    REPCHARSET - Representable character set

    Use this parameter to control characters.

    Characters are entered as a series of ASCII character code ranges or individual ASCII character codes. ASCII character code ranges are represented as two integers separated by a comma or a space, inside parentheses. All the characters within the range, including the lower and upper bounds, are added to the representable character set. Integers represent individual ASCII character codes.

    To set this parameter, add the following line to the profile:

         REPCHARSET = [(nn[,]nn) | nn[,]...]
    
    For example, a representable character set of 30 and the range 32 through 255 might be entered as follows:
         REPCHARSET = 30,(32,255)
    
    The period (.) cannot be removed from the set, even if it is omitted from the REPCHARSET parameter.

    TASKLIST - Task memory dumped
    This parameter affects only the contents of MEMORYn.PRT. It specifies a list of the tasks to be included in the output. If a task is included in the list, all of its memory is stored in formatted form in MEMORYn.PRT.

    To set this parameter, add the following line to the profile:

         TASKLIST = [ ALL ] [NONE ] [[-|+] nn ] [,] ...
    
    where nn is a task number.

    Specifying ALL adds all tasks and their associated memory to MEMORYn.PRT. Specifying NONE subtracts all task-related output from MEMORYn.PRT. The list of tasks to be included may be modified by specifying task numbers individually. A minus sign (-) in front of a task number removes it from the list of tasks being printed. A plus sign (+) in front of a task number adds it to the list of tasks being printed.

    Note: If a task number does not have a "+" or a "-" preceding it, "+" is assumed.

    Some examples of the TASKLIST line follow. The first example shows how to display all tasks except task 210.

         TASKLIST = ALL -210
    
    The second example shows how to display tasks 15h and 16h.
         TASKLIST = 15h 16h
    
    The default setting for TASKLIST is NONE.

    TITLE - Title for formatted output

    This parameter assigns a title to the Dump Formatter Facility output files. This title is printed at the top of each page in the MEMORYn.PRT and SYSINFOn.PRT files.

    To set this parameter, add the following line to the profile:

         TITLE = title_string
    
    The title string ends with a carriage return; that is, it must fit on a single line.

    TITLE has the character string "Untitled" as its default.

    USER_SEG - User-Selected Segment

    This parameter sets a special field indicating memory addresses with an offset from a user-selected segment.

    An address falling in the 64KB block of memory starting at this selected segment appears in the form segment:offset. The offset is from the beginning of the user-selected segment. Memory addresses outside the 64KB block are not displayed since different segment values are required to represent these addresses.

    To set this parameter, add the following line to the profile:

         USER_SEG = NN
    
    The default for this parameter is segment 0044h, which is the start of the co-processor adapter Interface Block (IB).

    Supplied Profile

    The following profile is supplied under filename FRMTDUMP.PRO. This profile contains default values (the values are assumed if FRMTDUMP.PRO cannot be found). The profile need not be present for the Dump Formatter Facility to work.

    Note: Printer-specific parameters are for the IBM Graphics Printer.

    Supplied FRMTDUMP.PRO profile.

    BOXCHARS = B3H,C4H,DAH,BFH,D9H,C0H,C3H,B4H,
               C2H,C1H,C5H
    FORM_FEED = 0CH
    MEMLIST = NONE
    PAGE_LINES = 66
    POSTSTRING =  12H
    PRESTRING = 18H,0FH,1BH,41H,12,1BH,32H,1BH,
                36H,1BH,39H,1BH,43H,66,1BH,
                46H,1BH,48H,1BH,54H,1BH,55H,0
    PRINT_LINES= 60
    REPCHARSET =  (32, 255)
    TASKLIST =  NONE
    TITLE = Untitled
    USER_SEG = 44H
    

    Appendix A. Message List


    Information Messages

    The Realtime Interface Co-Processor Operating System/2 Support information messages are arranged alphabetically. An explanation and recommended action accompanies each message.

    AutoDump beginning....

    Cannot close device driver

    Co-processor adapter nn requested a dump

    Dump completed

    Dump of coproc nn canceled

    Dump request: coproc nn. Press any key to continue.

    Enter co-processor adapter number:

    Enter dump drive letter:

    Enter file name:

    Enter tasknum [,start [,highlow [,bound [,msg]]]]:

    Format: ICADPRIC [n] [ARM(n..)] [DMP(n..)] [d:] [HELP]
    where:
      n        = co-proc to dump
      ARM(n..) = co-proc to arm
      DMP(n..) = co-proc to AutoDump
      d:       = dump drive
      HELP     = display help message
    

    ICARICIO.SYS initializing co-processor adapters...

    ICARICIO.SYS installed and running

    No co-processor adapters have requested a dump

    Normal termination. Task xx loaded on coproc yy

    Place diskette xx in drive d
    
    Press
      1   to continue dump of coproc yy
      9   to cancel dump and return to main menu
    
    Press
      1   to arm a coproc
      2   to restore a coproc
      3   to dump a coproc
      4   to enable AutoDump on a coproc
      5   to change the dump drive
      9   to return to OS/2
    
    Press
      0   to dump coproc 0
      1   to dump coproc 1
      2   to dump coproc 2
      3   to dump coproc 3
      4   to dump coproc 4
      5   to dump coproc 5
      6   to dump coproc 6
      7   to dump coproc 7
      9   to return to main menu
    ENTER to switch coproc sets
    
    Press
      0   to arm coproc 0
      1   to arm coproc 1
      2   to arm coproc 2
      3   to arm coproc 3
      4   to arm coproc 4
      5   to arm coproc 5
      6   to arm coproc 6
      7   to arm coproc 7
      9   to return to main menu
    ENTER to switch coproc sets
    
    Press
      0   to restore coproc 0
      1   to restore coproc 1
      2   to restore coproc 2
      3   to restore coproc 3
      4   to restore coproc 4
      5   to restore coproc 5
      6   to restore coproc 6
      7   to restore coproc 7
      9   to return to main menu
    ENTER to switch coproc sets
    
    Press
      0   to AutoDump coproc 0
      1   to AutoDump coproc 1
      2   to AutoDump coproc 2
      3   to AutoDump coproc 3
      4   to AutoDump coproc 4
      5   to AutoDump coproc 5
      6   to AutoDump coproc 6
      7   to AutoDump coproc 7
      9   to return to main menu
    ENTER to switch coproc sets
    

    The following co-processor adapters have requested a dump: n1 n2 n3

    Warning: Dump data will be lost.
    
    Are you sure you want to cancel the dump?
    
    Press
      0  No
      1  Yes
    

    Writing dump data to diskette d:

    Writing dump data to fixed disk d:


    Error Messages

    The Realtime Interface Co-Processor Operating System/2 Support error messages are arranged by message number. An explanation and recommended action accompanies each message.

    ICA0001E: Parameter file open error. Error code = nnnn

    ICA0002E: Parameter file read error. Error code = nnnn

    ICA0003E: Parameter file close error. Error code = nnnn

    ICA0006E: Invalid interrupt level. Level = nn

    ICA0007E: Invalid parameter file entry

    ICA0008E: Invalid character in parameter file. Char = 'c'

    ICA0009E: Invalid parameter file format. Extra records ignored.

    ICA0010E: ICARICIO.SYS found no valid co-proc and did not install

    ICA0013E: Invalid character in command line, remaining line ignored. Char = 'x'

    ICA0014E: Missing open parenthesis

    ICA0015E: Entry for ignored card found in parameter file. Card number = nn

    ICA0017E: Co-processor I/O error - co-processor ignored. Base I/O address = nnnn

    ICA0018E: Co-processor POST test failed - co-processor ignored. Base I/O address = nnnn

    ICA0019E: Unsupported window size - co-processor ignored. Base I/O address = nnnn

    ICA0031E: Error opening xxxxxxxx.xxx. Return code = nnnn

    ICA0032E: Error reading xxxxxxxx.xxx. Return code = nnnn

    ICA0033E: Error closing xxxxxxxx.xxx. Return code = nnnn

    ICA0034E: RCM Version 1.3 required for enhanced function

    ICA0035E: Invalid character on command line: 'c'

    ICA0036E: ICARICIO.SYS returned error code nnnn

    ICA0037E: Invalid task number. Task number = nn

    ICA0038E: Severe device error. Coproc = nn

    ICA0039E: Task 0 already loaded. Status = nn

    ICA0040E: Task 0 invalid status. Status = nn

    ICA0041E: Task 0 not loaded and initialized. Status = nn

    ICA0042E: Task 0 found error. Status = nn

    ICA0043E: Task error flag on. Status = nn

    ICA0044E: Task already loaded. Status = nn

    ICA0045E: Invalid task format. File = xxxxxxxx.xxx

    ICA0046E: Task 0 output buffer size invalid. Status = nn

    ICA0047E: Command not accepted. Status = nn

    ICA0048E: Cannot start task - task not loaded. Status = nn

    ICA0049E: File relocation error.

    ICA0053E: No device response. Coproc = nn. Status = nn

    ICA0054E: Invalid PC Select Byte. PC Select = nn

    ICA0055E: ICARICIO.SYS not resident

    ICA0056E: Invalid task length. Length = nnnn

    ICA0057E: Invalid co-processor adapter number: nn

    ICA0058E: Operating System/2 error code = nnnn

    ICA0059E: Invalid driver version

    ICA0098E: Too many diskettes

    ICA0099E: Unable to perform dump. Coproc nn not responding.

    ICA0100E: Unable to arm coproc. Coproc nn not responding.

    ICA0101E: Unable to restore coproc. Coproc nn not responding.

    ICA0102E: Unable to enable AutoDump on coproc. Coproc nn not responding.

    ICA0103E: Coproc nn is not installed

    ICA0104E: Dump data will not fit on fixed disk d:
    Dump of coproc nn canceled
    
    
    

    ICA0105E: Diskette full. Use another diskette.

    ICA0106E: Invalid dump drive

    ICA0107E: Invalid command line parameter

    ICA0108E: Device driver not installed

    ICA0109E: Cannot close device driver.

    ICA0110E: OS/2 error encountered. Error code = nnnn

    ICA0114E: AutoDump data will not fit on drive d:


    Appendix B. Tips and Techniques

    The following tips and techniques are provided for programmers who are developing software for the co-processor adapter. For a more complete discussion of these topics, refer to the following related publications:


    Online Message Help

    The Realtime Interface Co-Processor Operating System/2 Support uses the online message help service offered by Operating System/2. It does this with the message file ICAH.MSG. ICAH.MSG contains an explanation and recommended action for each error message displayed by the software modules in the &prod.; these same explanations and recommended actions are also found in Appendix A. "Message List". To display the explanation and action for a particular message, enter the following command:

         > HELP ICAnnnn
    
    where nnnn is the number of the message. In the following example, help is requested for message 0001:
         > HELP ICA0001
    
    ICA0001E: Parameter file open error.  Error code = nnnn
    
    Explanation: The ICARICIO.SYS device driver was unable
                 to open the parameter file.
    
    Action:      Make sure that the path specified in the
                 CONFIG.SYS file is correct.
    

    Setting the Shared Storage Window

    The shared storage window for a co-processor adapter must be located on an 8KB boundary where no other memory or adapters exist. The addresses where the window can be located are in the adapter space below 1 megabyte (physical address 0C0000h to 0DFFFFh) or in the area above the system unit's memory. Once the address is decided, it should be converted to Meg and Page values in the parameter file record.

    To convert a shared storage location to a Meg and Page value for the parameter file, first calculate the physical address of the window location. If the shared storage window is to be located at segment C000h in the adapter space, the physical address would be 0C0000h. The high digit is the megabyte value; in the case of physical address 0C0000h, the Meg Value is 0. Divide the bottom five digits of the physical address by 2000h to get the Page value. In the case of physical address 0C0000h, the Page value is 60h.

    In another example, if there are 3MB of system unit memory, the shared storage window may be located at 4MB. This yields a physical address of 400000h. The Meg value is 4, and the Page value is 00h.


    System Configuration

    The Realtime Interface Co-Processor Multiport/2, the Realtime Interface Co-Processor Multiport Adapter, Model 2, and the X.25 Interface Co-Processor/2 use Programmable Option Select (POS) for configuration instead of jumpers. The configuration information for the Realtime Interface Co-Processor Multiport/2 is contained in the file @EFF0.ADF which is provided on an option diskette. The Meg and Page values are set in this configuration and override the values set in the parameter file. See the IBM Realtime Interface Co-Processor Multiport/2 Guide To Operations, the IBM X.25 Interface Co-Processor/2 User's Guide and the IBM Realtime Interface Co-Processor Portmaster Adapter/A Guide to Operations for more configuration information.


    Developing Tasks

    Co-processor adapter tasks may be developed under DOS or OS/2. These tasks may also be developed with either the IBM Macro Assembler or the IBM Macro Assembler/2. There are a few restrictions that should be noted.

    See the IBM Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport and Realtime Interface Co-Processor Multiport/2 Technical Reference, and the IBM Realtime Interface Co-Processor Firmware Technical Reference for specific information on task development.


    Tasks and System Unit Applications

    There are guidelines to follow for communication between system unit applications and co-processor adapter tasks. System unit applications issue commands to tasks with the IssueCommand Generic IOCtl call or the ICADevIssueCommand dynamic link routine. These routines perform the same function; they copy parameter bytes to the task's output buffer and write a command code to the command code field in the task's Buffer Control Block. The task responds to the command by placing the return parameters in its input buffer and then interrupting the system unit. A system unit application can ask to be notified of interrupts from a certain task by registering a system semaphore with the device driver. This is done with the RegisterSemaphore Generic IOCtl call or the ICADevRegSemaphore dynamic link routine.

    Task developers should note that, if two successive interrupts are issued to the system unit from the same task, system unit applications waiting on interrupts from that task may miss the second interrupt. OS/2 semaphores do not keep a counter; instead, they have one of two states--set or cleared. Thus, there should be some type of signal from the system unit application that it has received the first interrupt before the task interrupts again. This could take the form of a command to the task.

    An example of a system unit application that issues commands to a task is given in the file ICASAMP.ASM. This application issues a command to Realtime Control Microcode on co-processor adapter 0 to query the amount of free memory. Other applications should follow the same steps when communicating with a co-processor adapter task.

    1. Open the device driver with the DosOpen OS/2 call.

    2. Create a system semaphore with the DosCreateSem OS/2 call. If the semaphore already exists, it can be opened with the DosOpenSem OS/2 call.

    3. Set the system semaphore with the DosSemSet OS/2 call because semaphores are in the cleared state when they are created.

    4. Register the semaphore with the device driver with the ICADevRegSemaphore dynamic link routine.

    5. Issue the command to the task using the ICADevIssueCommand dynamic link routine.

    6. Wait on the semaphore with the DosSemWait OS/2 call for a response from the task.

    7. Read the return parameters using the ICADevGetInBuf dynamic link routine.

    When the system unit application is finished communicating with the task, it should release the semaphore and device driver handle, as follows:

    1. Remove the system semaphore from the device driver using the ICADevRemSemaphore dynamic link routine.

    2. Release the system semaphore using the DosCloseSem OS/2 call.

    3. Close the device driver with the DosClose OS/2 call.

    For more information on task structures and communication with tasks, see the IBM Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport and Realtime Interface Co-Processor Multiport/2 Technical Reference, the IBM Realtime Interface Co-Processor Firmware Technical Reference, and the IBM Realtime Interface Co-Processor Developer's Kit.


    Appendix C. Error Codes

    The following error codes are returned by the device driver, generic IOCTL routines and dynamic link library routines:

    FF03h
    ERROR_ICA_DEV_NOT_CLOSED
    The device driver is not closed.

    FF04h
    ERROR_ICA_COPROC_NOT_ACTIVE
    The co-processor adapter is installed in the system but not active.

    FF05h
    ERROR_ICA_INVALID_COPROC
    The co-processor adapter is not installed.

    FF06h
    ERROR_ICA_INVALID_TASK_STATUS
    The task number is out of range, the task is not loaded, or the task's status is invalid.

    FF07h
    ERROR_ICA_INVALID_PAGE
    The page number is out of range. For an 8K page, valid page numbers are in the range 0 through 7Fh. For a 16K page, valid page numbers are in the range 0 through 3Fh. For a 32K page, valid page numbers are in the range 0 through 1Fh. For a 64K page, valid page numbers are in the range 0 through 0Fh.

    FF08h
    ERROR_ICA_INVALID_OFFSET
    The page offset is out of range. For an 8K page, valid page offsets are in the range 0 through 1FFFh. For a 16K page, valid page offsets are in the range 0 through 3FFFh. For a 32K page, valid page offsets are in the range 0 through 7FFFh. For a 64K page, all page offsets are valid.

    FF09h
    ERROR_ICA_INVALID_FORMAT
    The address format byte had a value other than 0 or FFh.

    FF0Ah
    ERROR_ICA_WIN_RESERVED
    The shared storage window is already reserved by another process.

    FF0Bh
    ERROR_ICA_TIMEOUT
    The call timed out and failed. If this code was returned after issuing a command, RCM did not respond to the command in time. If this code was returned after requesting a shared storage window, the window was not released by the previous owner before time expired.

    FF0Ch
    ERROR_ICA_STATUS_NOT_READY
    The secondary status buffer could not be read because the secondary status available bit in the task's primary status byte was not set.

    FF0Dh
    ERROR_ICA_INVALID_CONTROL
    The control bit fields were invalid.

    FF0Eh
    ERROR_ICA_BAD_GENIOCTL
    An invalid category code or function code was passed to the device driver. Check the description of the desired command in this chapter for the correct category and function codes.

    FF0Fh
    ERROR_ICA_WIN_NOT_RSRVD
    The window request was canceled by a call to TaskFlush or ICADEVTASKFLUSH from another thread in the calling process.

    FF10h
    ERROR_ICA_WIN_NOT_OWNED
    The shared storage window is not owned by the calling thread.

    FF11h
    ERROR_ICA_BAD_PCSELECT
    The command could not be issued because the PC Select byte in the Interface Block was invalid.

    FF12h
    ERROR_ICA_CMD_REJECTED
    The Realtime Control Microcode returned an error after the command was issued.

    FF13h
    ERROR_ICA_NO_CMD_RESPONSE
    The co-processor adapter did not respond after the command was issued.

    FF14h
    ERROR_ICA_OB_TOO_SHORT
    The number of parameter bytes exceeded the length of the task's output buffer; the command aborted.

    FF15h
    ERROR_ICA_SEM_FULL
    The semaphore cannot be registered with the device driver because there is no more room in the device driver. A maximum of 255 semaphores may be registered with the device driver.

    FF16h
    ERROR_ICA_NO_PEER_HAND
    No free peer handles were available on the peer open call. A maximum of 32 peer handles may be opened with the device driver.

    FF17h
    ERROR_ICA_BAD_HANDLE
    An invalid peer handle was passed to the routine.

    FF18h
    ERROR_ICA_REQS_REMAIN
    A disposition code to save requests was specified on peer close and there were still unreceived request blocks for the peer handle.

    FF19h
    ERROR_ICA_NO_REQS
    There are no peer request blocks available to receive.

    FF1Ah
    ERROR_RCV_SEQ_ERR
    The order of peer receive and peer receive done calls is out of sequence.

    FF1Ch
    ERROR_ICA_BAD_ADDRESS
    An invalid address was passed to the driver. Either the application does not have proper access to the addressed memory, or an address in a task buffer control block is invalid.

    FF1Dh
    ERROR_ICA_BAD_SEMAPHORE
    An invalid semaphore handle was passed to the driver.

    FF1Eh
    ERROR_ICA_NOT_ENOUGH_MEMORY
    There is insufficient memory to complete the request.

    FF1Fh
    ERROR_ICA_UNKNOWN_DISPOSITION
    An invalid disposition code was passed to the driver in the peer close call.

    FF20h
    ERROR_ICA_UNKNOWN_PEER
    An unknown peer handle was specified.

    FF21h
    ERROR_ICA_BAD_PARM
    A parameter in the peer request block is invalid.

    FF22h
    ERROR_ICA_TOO_MANY_SEMAPHORES
    The maximum number of semaphores supported by the driver has been reached.
    The following error codes are returned by the device loader.
    30
    ICA_LOAD_SUCCESSFUL
    31
    ERROR_ICA_OPEN_FILE
    32
    ERROR_ICA_READ_FILE
    33
    ERROR_ICA_CLOSE_FILE
    34
    ERROR_ICA_RCP_ENHAN
    35
    ERROR_ICA_INVALID_PARM
    36
    ERROR_ICA_DRIVER_ERROR
    37
    ERROR_ICA_INVALID_TASK
    38
    ERROR_ICA_SEVERE_DEVICE_ERR
    39
    ERROR_ICA_RCM_LOADED
    40
    ERROR_ICA_RCM_STATUS
    41
    ERROR_ICA_RCM_NOT_LOADED
    42
    ERROR_ICA_RCM_FOUND_ERROR
    43
    ERROR_ICA_TASK_ERR_FLAG
    44
    ERROR_ICA_TASK_LOADED
    45
    ERROR_ICA_FILE_FORMAT
    46
    ERROR_ICA_RCM_OUTBUF
    47
    ERROR_ICA_RCM_NOT_READY
    48
    ERROR_ICA_NOT_STARTED
    49
    ERROR_ICA_RELOCATION
    50
    ERROR_ICA_COPROC
    51
    ERROR_ICA_TASKFILE
    52
    ERROR_ICA_TASKNUM
    53
    ERROR_ICA_NO_RESPONSE
    54
    ERROR_ICA_PC_SELECT
    55
    ERROR_ICA_NO_DRIVER
    56
    ERROR_ICA_TASK_LENGTH
    57
    ERROR_ICA_INVALID_COPROC
    58
    ERROR_ICA_OS2_ERROR

    Appendix D. The Ignore Feature

    The OS/2 Support device driver incorporates a feature that provides the capability to ignore certain Realtime Interface Co-Processor (ARTIC) cards.

    The invocation of the ignore feature is accomplished as follows. In the CONFIG.SYS, after ICARICIO.SYS and after the ICAPARM.PRM entry, type the following on the same command line: either an upper or lower case I, then a left parenthesis '(', followed by the physical card number (in hexadecimal) of the card you would like to ignore.

    Note:

    The ARTIC at Base I/O address 2A0 has a physical card number of 0. Physical card numbers are explained under "Co-Processor Adapter Base I/O Address".

    If you would like to ignore more than one ARTIC card, separate the physical card numbers by either commas or spaces. When all physical card numbers are entered, conclude the config.sys line with a right parenthesis ')'.

    For example, if you wanted to ignore physical cards 0 and 2, but not 1, you would type the following:

      device=c:\artic\icaricio.sys c:\artic\icaparm.prm I(0,2)
    
    To ignore physical cards 4 and B:
      device=c:\artic\icaricio.sys c:\artic\icaparm.prm I(4,B)
    
    Because the ignore feature distinguishes the ARTICs by physical card numbers, and the ARTICs cannot be physically numbered higher than F, the only valid entries for the ignore feature are 0 through 9 and A through F (upper or lower case). Any other entries passed to the ARTIC OS/2 Support device driver (ICARICIO.SYS) will be flagged as errors and not used.

    Note:

    An ARTIC card that appears in the ICAPARM.PRM (parameter) file will not be ignored. Therefore, if the card you want to ignore appears in your ICAPARM.PRM file, that card's entry must be removed.

    Footnotes:

    (1)

    (1)  Operating System/2 and OS/2 are registered trademarks
         of the International Business Machines Corporation
         in the USA and other countries.
    
    (2)
    (2)  IBM is a registered trademark of International Business
         Machines Corporation in the USA and other countries.
    
    (3)
    (3)  IBM Macro Assembler/2 and C/2 are trademarks of
         International Business Machines Corporation
         in the USA and other countries.
    
         Microsoft is a trademark of Microsoft Corporation.
    
     

    Last modified: March 25, 1999