VERSION 1.03.5 (JUNE 1996)
Chapter 1. General Product Description
Chapter 2. Installing the Software
Chapter 3. Parameter File Description
Chapter 4. Device Driver Description
Chapter 5. Application Loader Utility
Chapter 6. Preparing/Installing Application Tasks
Chapter 7. Dynamic Link Routines
Chapter 8. Device Driver Functions
Chapter 9. Online Dump Facility
Chapter 10. Dump Formatter Facility
Appendix B. Tips and Techniques
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.
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 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.
The Realtime Interface Co-Processor OS/2 Support User's Guide is organized as follows:
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 books in the Realtime Interface Co-Processor library include:
This guide provides instructions for installing the Realtime Interface Co-Processor and Realtime Interface Co-Processor Multiport and describes the features of each. It also describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both hardware and software introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and anyone who needs to understand the use and operation of the co-processor adapter.
This guide provides instructions for installing the hardware necessary to use the Realtime Interface Co-Processor Multiport/2 and describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both hardware and software introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and anyone who needs to understand the use and operation of the co-processor adapter.
This guide provides instructions for installing the hardware necessary to use the X.25 Interface Co-Processor/2 and describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both hardware and software introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and anyone who needs to understand the use and operation of this co-processor adapter.
This guide provides instructions for installing the Realtime Interface Co-Processor Portmaster Adapter/A, describes the product features, and provides problem determination procedures.
This manual provides both introductory and reference information, and is intended for hardware designers who need to understand the design and operating characteristics of this co-processor adapter. (See also the Realtime Interface Co-Processor Firmware Technical Reference.)
This manual provides detailed information on the programmer interfaces to the Realtime Control Microcode for the family of Realtime Interface Co-Processor adapters. It is intended for hardware and software designers who need to understand the design and operating characteristics of the control microcode.
This manual is used in conjunction with either the Eight Port RS-232 Interface Board/A Hardware Maintenance Library or the Eight Port RS-422 Interface Board/A Hardware Maintenance Library. This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are also provided.
This kit is required for maintenance of the Realtime Interface Co-Processor Portmaster Adapter/A or the Realtime Interface Co-Processor Multiport Adapter, Model 2 when an RS-232 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This kit is required for maintenance of the Realtime Interface Co-Processor Portmaster Adapter/A or the Realtime Interface Co-Processor Multiport Adapter, Model 2 when an RS-422 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This guide provides instructions for installing the Realtime Interface Co-Processor Multiport Adapter, Model 2, describes the product features, and provides problem determination procedures.
This manual provides both introductory and reference information, and is intended for hardware designers who need to understand the design and operating characteristics of this co-processor adapter. (See also the Realtime Interface Co-Processor Firmware Technical Reference.)
This manual provides detailed information on the programmer interfaces to the Realtime Control Microcode for the family of Realtime Interface Co-Processor adapters. It is intended for hardware and software designers who need to understand the design and operating characteristics of the control microcode.
This manual is used in conjunction with either the Eight Port RS-232 Interface Board/A Hardware Maintenance Library or the Eight Port RS-422 Interface Board/A Hardware Maintenance Library. This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are also provided.
This kit is required for maintenance of the Realtime Interface Co-Processor Multiport Adapter, Model 2 or the Realtime Interface Co-Processor Portmaster Adapter/A when an RS-232 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This kit is required for maintenance of the Realtime Interface Co-Processor Multiport Adapter, Model 2 or the Realtime Interface Co-Processor Portmaster Adapter/A when an RS-422 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This guide is available only as part of the Realtime Interface Co-Processor C Language Support product. The guide provides information on using the C Language Support product, a productivity aid that allows programmers to develop code for the system unit or the co-processor adapter in the C programming language. It explains the C interface routines and the method of compiling and linking C tasks for the co-processor adapter.
This guide explains the installation and loading of software, event management services, intertask communications services, asynchronous and synchronous communications support; provides information necessary for Realtime Interface Co-Processor Extended Services to interface with co-processor adapters; and describes the functions and capabilities of Realtime Interface Co-Processor Extended Services.
You may need to use one or more of the following publications for reference with this guide:
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.
The following are minimum hardware requirements for the Realtime Interface Co-Processor OS/2 Support product:
The following are minimum software requirements for the Realtime Interface Co-Processor Operating System/2 Support product:
This chapter provides a guide for installing the software for the IBM co-processor adapter.
The installation procedures include doing the following:
During the installation steps, the following apply in explaining commands entered at the OS/2 level:
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".)
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:
Note:
Records that do not begin with a # are treated as comments and are valid.
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.
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".
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:
device=[d:][\path1\]ICARICIO.SYS [[d:][\path2\]configfile]where:
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.
IBM Realtime Interface Co-Processor OS/2 Support
Copyright IBM Corp. 1988, 1992
ICARICIO.SYS initializing co-processor adapters
ICARICIO.SYS installed and running
For further information on the device driver, refer to "Chapter 4. Device Driver Description".
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".)
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.
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:
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 ; | +----------+----------------------+--------+-----------------+
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.
This section defines each parameter field of the ICAPARM.PRM file.
+---------------+------------------------------------------+ | Length | One character # (number sign) | +---------------+------------------------------------------+ | Range | # | +---------------+------------------------------------------+ | Description | The first character of each record must | | | be a #. | +---------------+------------------------------------------+
+---------------+-----------+------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
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 | | | +------------------------+-----------------+----------------+
+---------------+------------------------------------------+ | 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. | +---------------+------------------------------------------+
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
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:
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.
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:
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:
device=[d:][\path1\]ICARICIO.SYS [[d:][\path2\]configfile]
[-R][I(X,Y,Z)]
where:
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.
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.
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:
Realtime Control Microcode Version 2.01 or later allows a user to disable peer services by specifying an optional parameter of 1 (one) when invoking the application loader utility. For example:
> ICALDRIC 0 ICARCM.COM 0 ( 1
Realtime Control Microcode Version 2.02 or later allows a user to specify an optional parameter of 2 (two) to enable a 32KB portion of random access memory specifically for EIB use. This parameter may be specified when invoking the application loader utility. For example:
> ICALDRIC 0 ICARCM.COM 0 ( 2
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.
> ICALDRIC 0 ICARCM.COM 0 ( 1 2
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.
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]Where
[,BOUND][,MSG][(PARMS]
Note:
RCM V1.3 or greater must be installed to use this option.
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.
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
This chapter provides overview information on preparing and installing application tasks. Additional information on loading tasks is in "Chapter 5. Application Loader Utility".
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.
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".
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 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 ICADevChangePageWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF07h = ERROR_ICA_INVALID_PAGE FF0Ah = ERROR_ICA_WIN_RESERVEDRemarks
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
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 ICADevGetExtParmsWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROCRemarks
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 BYTEField Definitions
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
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
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 ICADevGetInBufWhere:
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 ADDRESSRemarks
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
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 ICADevGetParmsWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROCRemarks
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 BYTEField Definitions
Index Interrupt Level
----- ---------------
0 3
1 4
2 7
3 9
4 10
5 11
6 12
7 15
Size Code Window Size
--------- -----------
0 8KB
1 16KB
2 32KB
3 64KB
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
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 ICADevGetSecStatusWhere:
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_PARMSRemarks
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
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 ICADevGetVersionWhere:
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
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 ICADevInputBufferWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK_STATUSRemarks
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
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 ICADevIssueCommandWhere:
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_PCSELECTRemarks
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
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_ADDRESSRemarks
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
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 ICADevNotifyWhere:
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_SEMAPHORERemarks
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
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 ICADevOutputBufferWhere:
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_ADDRESSRemarks
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
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 ICADevPeerCloseReturns
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_PEERRemarks
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
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 ICADevPeerOpenReturns
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_SEMAPHORESRemarks
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
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_HANDLERemarks
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
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 ICADevPeerReceiveReturns
IF AX=0 then NO error ELSE AX=error code FF17h = ERROR_ICA_BAD_HANDLE FF1Ah = ERROR_RCV_SEQ_ERRRemarks
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
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 ICADevPeerSendReturns
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_ADDRESSRemarks 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
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 ICADevPrimaryStatusWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK_STATUSRemarks
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
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 ICADevPutOutBufWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK_STATUSRemarks
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
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 ICADevReadStringWhere:
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_ADDRESSRemarks
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
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 ICADevRegSemaphoreWhere:
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_SEMAPHORERemarks
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:
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
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 ICADevRemNotifyWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Dh = ERROR_ICA_INVALID_CONTROL FF1Dh = ERROR_ICA_BAD_ADDRESSRemarks
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
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 ICADevRemSemaphoreWhere:
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_SEMAPHORERemarks
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
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 ICADevResetWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROCRemarks
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
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 ICADevSecStatusWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK_STATUSRemarks
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
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 ICADevTaskFlushWhere:
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
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 ICADevUnLockReturns
IF AX=0 then NO error ELSE AX=error code FF1Ch = ERROR_ICA_BAD_ADDRESSRemarks
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
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 ICADevWinReleaseWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Ah = ERROR_ICA_WIN_NOT_OWNEDRemarks
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
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 ICADevWinResNoWaitWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Ah = ERROR_ICA_WIN_RESERVEDRemarks
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
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 ICADevWinResWaitWhere:
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Bh = ERROR_ICA_TIMEOUTRemarks
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
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 ICADevWriteStringWhere:
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_ADDRESSRemarks
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
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.
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.
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 BYTEData Packet Format
Field Length ------------------------------------------- Old page number BYTEField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF07h = ERROR_ICA_INVALID_PAGE FF0Ah = ERROR_ICA_WIN_RESERVEDRemarks
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.
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.
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) BYTEData Packet Format
Field Length -------------------------------------------- Adapter code BYTE Physical slot number BYTE EIB 0 ID BYTE EIB 1 ID BYTE Clocking options (0,1) BYTEField Definitions
Note:
Refer to the Realtime Interface Co-Processor Firmware Technical Reference for the values of the identification byte.
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
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROCRemarks
The GetExtParameters function returns extra parameter information for each card.
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 WORDData Packet Format
Field Length -------------------------------------------- Destination buffer pointer DWORDField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK FF1Ch = ERROR_ICA_BAD_ADDRESSRemarks
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.
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 BYTEData 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 BYTEField Definitions
Index Interrupt Level
----- ---------------
0 3
1 4
2 7
3 9
4 10
5 11
6 12
7 15
Size Code Window Size
--------- -----------
0 8KB
1 16KB
2 32KB
3 64KB
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROCRemarks
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.
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 BYTEData Packet Format
Field Length ------------------------------------------- Destination buffer pointer DWORDField Definitions
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_ADDRESSRemarks
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.
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 BYTEField Definitions
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.
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 BYTEData Packet Format
Field Length -------------------------------------------- Length WORD Offset WORD Page BYTEField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK_STATUSRemarks
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.
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 WORDData Packet Format
Field Length ------------------------------------------- Parameter pointer DWORDField Definitions
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_RESPONSERemarks
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.
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 WORDData Packet Format
Field Length --------------------------------------------- Lock handle DWORD Physical address DWORDField Definitions
IF AX=0 then NO error ELSE AX=error code FF1Ch = ERROR_ICA_BAD_ADDRESS
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 DWORDData Packet Format
Field Length ------------------------------------------ reserved WORDField Definitions
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_SEMAPHORERemarks
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.
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:
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 BYTEData Packet Format
Field Length -------------------------------------------- Length WORD Offset WORD Page BYTEField Definitions
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_ADDRESSRemarks
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.
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 DWORDData Packet Format
None
Field Definitions
IF AX=0 then NO error ELSE AX=error code FF17h = ERROR_ICA_BAD_HANDLE FF18h = ERROR_ICA_REQS_REMAIN
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 DWORDData Packet Format
Field Length --------------------------------------------- Peer handle WORD Reserved DWORDField Definitions
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 ReservedThe fields in the peer segment are defined as follows.
IF AX=0 then NO error ELSE AX=error code FF16h = ERROR_ICA_NO_PEER_HANDLE
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 WORDData Packet Format
None
Field Definitions
IF AX=0 then NO error ELSE AX=error code FF21h = ERROR_ICA_BAD_PARMThe 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.
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 BYTEData Packet Format
Field Length ------------------------------------------- Primary status byte BYTEField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK_STATUSRemarks
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.
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 WORDData Packet Format
Field Length ------------------------------------------ Source buffer pointer DWORDField Definitions
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_ADDRESSRemarks
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.
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 BYTEData Packet Format
Field Length ----------------------------------------- Length WORD Offset WORD Segment/page WORD Address format BYTE Destination buffer pointer DWORDField Definitions
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.
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_ADDRESSRemarks
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.
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 DWORDData Packet Format
Field Length ------------------------------------------- reserved WORDField Definitions
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_SEMAPHORERemarks
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:
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 DWORDData Packet Format
Field Length ------------------------------------------ Reserved WORDField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Dh = ERROR_ICA_INVALID_CONTROL FF1Dh = ERROR_ICA_BAD_SEMAPHORERemarks
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.
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 DWORDData Packet Format
Field Length ------------------------------------------ Reserved WORDField Definitions
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_SEMAPHORERemarks
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.
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 BYTEData Packet Format
Field Length ------------------------------------------- Reserved BYTEField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROCRemarks
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).
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 BYTEData Packet Format
Field Length ------------------------------------------ Length WORD Offset WORD Page BYTEField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF06h = ERROR_ICA_INVALID_TASK_STATUSRemarks
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.
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 BYTEData Packet Format
Field Length ------------------------------------------- Reserved BYTEField 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.
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 DWORDData Packet Format
None
Field Definitions
IF AX=0 then NO error ELSE AX=error code FF1Ch = ERROR_ICA_BAD_ADDRESS
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 BYTEData Packet Format
Field Length ------------------------------------------- reserved BYTEField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Ah = ERROR_ICA_WIN_RESERVEDRemarks
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.
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 BYTEData Packet Format
Field Length ------------------------------------------- Base address of window DWORD PID WORD Thread ID WORDField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Ah = ERROR_ICA_WIN_RESERVEDRemarks
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.
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 DWORDData Packet Format
Field Length -------------------------------------------- Base address of window DWORDField Definitions
IF AX=0 then NO error ELSE AX=error code FF05h = ERROR_ICA_INVALID_COPROC FF0Bh = ERROR_ICA_TIMEOUTRemarks
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.
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 BYTEData Packet Format
Field Length ------------------------------------------- Length WORD Offset WORD Segment/page WORD Address format BYTE Source buffer pointer DWORDField Definitions
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.
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_ADDRESSRemarks
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The Dump Formatter Facility creates at least two files when formatting a dump of a co-processor adapters memory and I/O image:
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.
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:
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:
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 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:
Following is a list of the Dump Formatter Facility profile parameters:
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
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.
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.
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.
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.
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.
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:
Printer codes are explained in depth in the user's printer manual.
To set this parameter, add the following line to the profile:
PRINT_LINES = nn
The default value is 60 lines per page.
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.
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.
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.
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).
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
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:
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
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 information
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:
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:
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.
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.
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.
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.
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.
When the system unit application is finished communicating with the task, it should release the semaphore and device driver handle, as follows:
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.
The following error codes are returned by the device driver, generic IOCTL routines and dynamic link library routines:
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.
(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