Realtime Interface Co-Processor

Firmware Technical Reference

Volume 1 - System Interfaces and Functions

Volume 2 - Functions
Volume 3 - Data Structures

Second Edition (July 1990)

INTERNATIONAL BUSINESS MACHINES PROVIDES THIS MANUAL "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 new editions 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 material may contain reference 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.


Table of Contents

  • Special Notices
  • Purpose
  • Audience
  • Organization
  • Related Publications
  • Reference Publications
  • Conventions

  • Part 1. Volume I - System Interfaces and Functions

  • Chapter 1. Software Structure
  • Co-Processor Adapter Software and Firmware Components
  • Realtime Control Microcode
  • Programmable Read-Only Memory (PROM) Modules
  • Application Tasks
  • System Unit Support Software Components
  • IBM Realtime Interface Co-Processor DOS Support
  • IBM Realtime Interface Co-Processor OS/2 Support
  • Application Programs
  • Chapter 2. System Unit Support Software Functions
  • System Initialization
  • Bootstrap Loader and Realtime Control Microcode Implementation
  • Co-Processor Adapter Task Loading
  • Task Control Commands
  • Watchdog Timer Initialization
  • System Time Initialization
  • Asynchronous Error Handling
  • Realtime Control Microcode Secondary Status Field Error Codes for Asynchronous Errors
  • Chapter 3. System Unit Commands
  • List of System Unit to Co-Processor Adapter Commands
  • General Error Handling
  • Primary Status Byte Definition
  • Task 0 Secondary Status Field Definition
  • Descriptions of System Unit to Co-Processor Adapter Commands
  • Initialize
  • Request Task Load
  • Free Buffer
  • Request Task Load with Boundary
  • Query Free Storage
  • Start Task
  • Stop Task
  • Unload Task
  • Set Watchdog Timer Duration
  • Enable Watchdog Timer
  • Disable Watchdog Timer
  • Read Watchdog Timer Duration
  • Request Task Load Low
  • Set Time
  • Get Time
  • Chapter 4. Co-Processor Adapter Communications
  • Co-Processor Adapter Setup
  • Realtime Control Microcode Storage
  • Starting the Realtime Control Microcode
  • Passing Commands to a Co-Processor Adapter Task
  • Co-Processor Adapter Task Data Transfer
  • Handling Co-Processor Adapter Interrupts

  • Special Notices

    References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates.

    Any reference to an IBM licensed program or other IBM product in this publication is not intended to state or imply that only IBM's program or other product may be used.

    IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license enquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Armonk, N.Y. 10504.

    The following terms, DENOTED BY AN ASTERISK (*), used in this publication, are trademarks or service marks of IBM Corporation in the United States and/or other countries:

    IBM                   OS/2                 PS/2
    Operating System/2    Personal System/2
    
    The following terms, DENOTED BY A DOUBLE ASTERISK (**), used in this publication, are trademarks of other companies as follows:

    Intel
    Intel is a trademark of Intel Corporation.

    Signetics
    Signetics is a trademark of Signetics Corporation.

    Zilog
    Zilog is a trademark of Zilog Inc.

    Lotus
    Lotus is a trademark of Lotus Development Corporation.

    Microsoft
    Microsoft is a trademark of Microsoft Corporation.


    About This Book

    This book contains software technical reference information concerning the IBM Realtime Interface Co-processor Adapter, Multiport Adapter, Multiport/2 Adapter, Portmaster Adapter/A, and the Multiport Adapter, Model 2.

    Note:

    Technical reference information for the IBM X.25 Interface Co-Processor/2 adapter is in the IBM X.25 Interface Co-Processor/2 Technical Reference.

    Throughout the book, the term "co-processor adapter" refers to the above adapter types.


    Purpose

    This manual:


    Audience

    This book contains introductory and reference information for software designers, programmers, and anyone with a knowledge of programming who needs to understand the use and operation of the co-processor adapter.

    You should be familiar with the system unit, your application, and programming. Only the terms that apply specifically to the co-processor adapter are explained.


    Organization

    The IBM Realtime Interface Co-Processor Firmware Technical Reference is organized into three volumes.

    Volume I contains the following:

    Volume II contains the following:

    Volume III contains the following:


    Related Publications

    Related books in the Realtime Interface Co-Processor library are as follows:

    IBM Realtime Interface Co-Processor Guide to Operations

    Provides instructions for installing the Realtime Interface Co-Processor features. It also describes problem-determination procedures.

    IBM Realtime Interface Co-Processor Adapter Hardware Maintenance and Service

    Used to isolate and repair 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.

    IBM Realtime Interface Co-Processor Multiport Adapter Guide to Operations

    Provides instructions for installing the Realtime Interface Co-Processor Multiport Adapter features. It also describes problem-determination procedures.

    IBM Realtime Interface Co-Processor Multiport Adapter Hardware Maintenance and Service

    Used to isolate and repair 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.

    IBM Realtime Interface Co-Processor Multiport/2 Adapter Guide to Operations

    Provides instructions for installing the Realtime Interface Co-Processor Multiport/2 Adapter features. It also describes problem-determination procedures.

    IBM Realtime Interface Co-Processor Multiport/2 Adapter Hardware Maintenance and Service

    Used to isolate and repair 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.

    IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 Guide to Operations

    Provides instructions for installing the Realtime Interface Co-Processor Multiport Adapter, Model 2 features. It also describes problem-determination procedures.

    IBM Realtime Interface Co-Processor Portmaster Adapter/A Guide to Operations

    Provides instructions for installing the hardware necessary to use the Realtime Interface Co-Processor Portmaster Adapter/A and describes problem-determination procedures.

    Realtime Interface Co-Processor Portmaster Adapter/A, Multiport Adapter, Model 2 Hardware Maintenance Library

    Used to isolate and repair any failure of a field-replaceable unit (FRU) for the Portmaster Adapter/A or the Multiport Adapter, Model 2. It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.

    IBM Realtime Interface Co-Processor DOS Support

    Provides information necessary to interface the co-processor adapter through the system unit DOS. It describes all functions, capabilities, and installation of the Realtime Interface Co-Processor DOS Support software.

    IBM Realtime Interface Co-Processor OS/2 Support

    Provides information necessary to interface the co-processor adapter through the system unit Operating System/2* (OS/2*). It describes all functions, capabilities, and installation of the Realtime Interface Co-Processor OS/2 Support software.

    Realtime Interface Co-Processor C Language Support User's Guide

    Describes the C Language Support product-&dasha productivity aid that allows programmers to develop code for the co-processor adapter and the system unit in the C Programming Language. This guide explains the C-interface routines and the method of compiling and linking C-tasks for the co-processor adapter and your system unit.

    IBM Realtime Interface Co-Processor Extended Services, Version 1.01

    Describes the Extended Services product-&dasha productivity aid that provides the system developer with a variety of services to ease the writing of systems applications for the Realtime Interface Co-Processor family of adapters. It includes numerous task, event, resource, and communications services that allow the system developer to concentrate on the application instead of the system.


    Reference Publications

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


    Conventions


    Part 1. Volume I - System Interfaces and Functions

    Volume I contains the following:


    Chapter 1. Software Structure

    This chapter introduces the overall structure of the co-processor adapter software and provides an overview of the software residing on both the co-processor adapter and the system unit.

    Co-processor adapter software is divided into two major areas:


    Co-Processor Adapter Software and Firmware Components

    The software components on the co-processor adapter are:

    Note:

    The Realtime Control Microcode and application tasks physically reside in the co-processor adapter storage after being loaded from the system unit. The Programmable Read-Only Memory modules are resident in the physical PROM on the co-processor adapter.

    Realtime Control Microcode

    The Realtime Control Microcode is the on-board multitasking supervisory control program (Task 0) for the co-processor adapter. The program can be found on the Realtime Interface Co-Processor Diagnostics and Realtime Control Microcode diskette that came with your co-processor adapter.

    The Realtime Control Microcode supports the co-processor adapters through two versions. Version 1.x is named ICAAIM.COM. It provides support for the Realtime Interface Co-processor Adapter, the Multiport Adapter, and the Multiport/2 Adapter. Version 2.x is named ICARCM.COM. It provides support for the Portmaster Adapter/A and the Multiport Adapter, Model 2.

    The Realtime Control Microcode supports user-written application tasks executing on the co-processor adapter while supporting the interface between application programs on the system unit and application tasks on the co-processor adapter.

    The co-processor adapter performs the following support functions for application tasks:

    Each of these functions is described here.

    Task Management

    The Realtime Control Microcode supports up to 248 concurrent tasks (1-248). The execution of these tasks is controlled by the Realtime Control Microcode according to each task's assigned priority.

    After a task is installed, it may be in one of several states:

    Executing

    A task that is executing is in actual control of the co-processor adapter.

    Initialized

    A task that is initialized can receive commands from the system unit or be posted by another task. An initialized task has an entry in task control block table (TCBTAB) and task table (TASKTAB).

    Loaded

    After a task is loaded, it resides in storage and has an entry in the TASKTAB; it has not been started. After a task is started and has returned to the Realtime Control Microcode with the INITCOMP Supervisor Call (SVC), it is considered to be initialized.

    Queued (Dispatchable)

    A queued task is in the dispatch queue and is dispatched when it has the highest dispatchable priority or its turn comes in round-robin dispatching.

    Resident

    A resident task is one that has been initialized and has terminated but remains resident. The task takes up storage, but has no TCB or entry in the TASKTAB. The only way this task may be entered is via an interrupt or a direct jump to it. A resident task becomes a loaded subroutine or a Realtime Control Microcode extension. A resident task may not issue SVCs.

    Stopped

    A task that is stopped has been removed from TCBTAB but still has an entry in TASKTAB. This task may be restarted by the system unit or another task. The stopped state and the loaded state are actually the same.

    Suspended

    A suspended task is not on the dispatch queue. The only way to get it back in the queue is to first RESUME it.

    Waiting

    A task that is waiting is idle and is ready to be posted. A task may be posted by its command subroutine interrupt handler, a hardware or software interrupt handler, or by another task.

    The chart on the next page demonstrates the progression of a typical task through various states.

    The stopped, resident, and suspended states are exceptional states and are not shown.

          TASK STATE:            RESULTED FROM:
    
         +-------------------+    Load command or Build SVC
         |                   |    received by the Realtime
         |      Loaded       |    Control Microcode for task x.
         +---------+---------+
                   |
         +---------+---------+    Start command or Start SVC
         |                   |    received by the Realtime
         |     Started       |    Control Microcode for task x.
         +---------+---------+
                   |
         +---------+---------+    Task x placed on dispatch
         |                   |    queue by the Realtime Control
         |      Queued       |    Microcode at successful
         |                   |    completion of Start
         +---------+---------+    command or Start SVC.
                   |
         +---------+---------+    Task x's priority became
         |                   |    highest dispatchable priority.
         |     Executing     |    Task given control of initial
         +---------+---------+    entry vector.
                   |
         +---------+---------+    Task x requests Initcomp SVC
         |                   |    after completing its setup to
         |    Initialized    |    indicate that it is ready to
         +---------+---------+    accept commands.
                   |
         +---------+---------+    Task x's priority became
         |                   |    highest dispatchable priority.
    +--->|     Executing     |    Control returned to task at the
    |    +---------+---------+    instruction following Initcomp
    |              |              SVC or Wait SVC.
    |    +---------+---------+
    |    |                   |    Task x requested that it
    |    |      Waiting      |    wait by issuing a Wait SVC.
    |    +---------+---------+
    |              |
    |    +---------+---------+    Task x was posted by a Post SVC
    |    |                   |    or Posti service interrupt.
    +----+      Queued       |
         +-------------------+
    

    Priority Queue Management

    The Realtime Control Microcode supports up to 255 task priorities. The highest priority is 1 and the lowest priority is 255. The assigned priority dictates when and in what order in the task queue management architecture a task is to be executed. The priority of a task is specified in its task control block (TCB) and is initially set to the value specified in its task header. The TCB is built from information supplied in the task header of the task. All tasks may have either the same priority or a mix of priorities. Tasks that have the same priority are dispatched in a round-robin fashion by the dispatcher. The dispatch queue determines the order in which application tasks execute. The operation of the dispatcher is transparent to the user. Functions performed by the dispatcher are as follows:

    If a dispatch cycle does not occur within 10 milliseconds, the Realtime Control Microcode forces one to occur. This is called time slicing.

    Resource Management

    The Realtime Control Microcode is responsible for allocating co-processor adapter resources to a user application task. Resources may be requested on a dynamic basis, although a typical task probably acquires the resources it needs during the initialization phase.

    Resources that may be acquired by a task include:

    Watchdog Timer Management

    The watchdog timer is used to signal an error condition when the co-processor adapter processor fails and cannot report an error. It is a free-running hardware timer that interrupts both the co-processor adapter and system unit when it expires. The watchdog timer duration may be set from the system unit via commands to the Realtime Control Microcode and may be enabled or disabled by the system unit application program; the default state is disabled. The duration of the watchdog timer is from 1.1111 milliseconds to 72.8166 seconds. The movement or "tick" of the watchdog timer is 1.1111 milliseconds. When the watchdog timer times out, the Realtime Control Microcode sets its status to indicate a watchdog time-out and stops all tasks.

    Task Interface

    Task interface communication is accomplished through the Realtime Control Microcode in the following ways:

    First-Level Interrupt Handling

    The Realtime Control Microcode controls the handling of interrupts that occur on the co-processor adapter. The Realtime Control Microcode initially sets the interrupt vectors for each I/O interrupt to point to the Realtime Control Microcode first-level interrupt handler. When a task requests a hardware resource, the resource block that accompanies that request contains the address(es) of the task's interrupt handler routine(s) for that hardware resource.

    The Realtime Control Microcode stores the address(es) from the resource block in a separate internal table so that the Realtime Control Microcode has quicker access and processing to the task's interrupt handler (which is called the second-level interrupt handler).

    Asynchronous Error Handling

    Asynchronous monitoring of certain errors is handled by the Realtime Control Microcode. When an error of this type is detected, the Realtime Control Microcode takes appropriate action to shut down the co-processor adapter and notify the system unit.

    Types of error conditions that may be detected are as follows:

    Types of exception conditions that may be detected are:

    For further explanation of asynchronous error handling, see Chapter 2, "System Unit Support Software Functions" in this manual.

    Supervisor Call Support

    Supervisor Calls (SVCs) is a set of Realtime Control Microcode functions that may be requested by an application task on the co-processor adapter. An SVC module is invoked via Interrupt 56h with the desired SVC number in register AH.

    All Realtime Control Microcode SVCs cause a dispatch cycle to occur and the watchdog timer to be retriggered.

    The individual SVC interface modules perform the following functions:

    Intpc
    Interrupts the system unit

    Unload
    Unloads the specified task

    Build
    Simulates a task load from the system unit

    Start
    Starts the specified task

    Stop
    Stops the specified task

    Wait
    Places the requesting task into an idle or wait state

    Suspend
    Suspends the specified task

    Resume
    Cancels the suspended state of a task

    Post
    Places a task on the dispatch queue

    Asap
    Causes a dispatch cycle to occur

    Stayres
    Terminates the requesting task (the task remains resident)

    Readvec
    Reads an interrupt vector

    Timerp
    Starts a periodic software timer

    Timer
    Starts a software timer

    Cancel
    Cancels the specified software timer

    Alloc
    Allocates one of the co-processor adapter's resources such as an interrupt vector, storage block, communication port, queue, or timer

    Return
    Deallocates a co-processor adapter resource

    Initcomp
    Tells the Realtime Control Microcode that initialization of the task is complete

    Qfreest
    Queries the largest available free-storage size

    System Unit to Co-Processor Adapter Command Support

    The system unit may issue commands to the Realtime Control Microcode to gain various modes of control. These modules can be called by programs that reside in the system unit. Commands are passed to the Realtime Control Microcode via a command byte code.

    The commands are:

    Service Interrupt Support

    The service interrupts can be accessed through the Realtime Control Microcode to perform various task services and are available to application tasks executing on the co-processor adapter. These routines were designed to be used by I/O interrupt handlers because I/O interrupt handlers cannot request SVCs but may still need Realtime Control Microcode services. The service interrupts do not cause a dispatch cycle to occur.

    The service interrupts perform the following functions:

    Parameters

    Realtime Control Microcode Version 1.x does not support the passing of parameters.

    Realtime Control Microcode Version 2.x, supports the following parameters:

    Parameter 1 -- Disabling Peer Services
    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 either of the system support application loader utilities. For example:

         ICALOAD 0 ICARCM.COM 0   ( 1
    

    (Refer to the Realtime Interface Co-Processor DOS Support Version 1.03 User's Guide or the OS/2 Support Version 1.03 User's Guide for information on the operation of the application loader utilities.)

    This parameter causes Realtime Control Microcode to bypass the building of peer-related tables. The memory normally used by these tables, remains in the free storage pool. Calls to the peer request SVI return an access denied error.

    This feature is not available on versions of Realtime Control Microcode prior to Version 2.01. (Ref #1.)

    Parameter 2 -- Reserved RAM for Interface Board Usage
    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 interface board use. This parameter may be specified when invoking either of the system support application loader utilities. For example:

         ICALOAD 0 ICARCM.COM 0   ( 2
    

    (Refer to the Realtime Interface Co-Processor DOS Support Version 1.03 User's Guide or the OS/2 Support Version 1.03 User's Guide for information on the operation of the application loader utilities.)

    The memory that is set aside for EIB use is not available for use by the Realtime Control Microcode or user tasks. This parameter is meaningful only on a 1MB Portmaster Adapter/A. It is ignored on a 512KB or a 2MB Portmaster Adapter/A, or on a Multiport Adapter, Model 2.

    This parameter should not be used with applications that require maximum RAM space.

    Electrical interface boards that require this memory to be reserved may be used only with a 1MB Portmaster Adapter/A.

    Note:

    Parameters 1 and 2 can be used at the same time by separating the parameters with a blank. For example:
         ICALOAD 0 ICARCM.COM 0   ( 1 2
    

    These parameters can be passed together and in any order (that is, they are not mutually exclusive and not order dependent).


    Programmable Read-Only Memory (PROM) Modules

    The Programmable Read-Only Memory (PROM) modules reside on the co-processor adapter and do not require the presence of the Realtime Control Microcode.

    The PROM modules include the following group of modules:

    Each function is described in the following paragraphs.

    Power-On Diagnostic Tests and Bootstrap Loader

    The power-on diagnostic testing begins execution as soon as the power stabilizes. The following functions are performed:

    The Bootstrap Loader functions include the following:

    Diagnostic Test Modules

    These modules are intended for use by IBM-supplied diagnostic modules or application tasks residing on the co-processor adapter. These modules are callable via interrupt vector INT FEh with the subroutine number in register AH.

    The diagnostic test modules perform the following functions:

    PROM Services

    Modules supporting I/O to the system unit, SCC ports, CIO ports, DMAs, and CIO timers are located in PROM. These routines are accessible to the Realtime Control Microcode for SVCs, to tasks for I/O services, and to diagnostics for diagnostic testing.

    The PROM services subsystem consists of individual free-standing routines that provide functions for the Realtime Control Microcode, advanced diagnostics, or application tasks running on the co-processor adapter. These modules are invoked through interrupt vector calls beginning with A0h.

    The PROM Services modules are as follows:

    Online Dump Facility Support Modules

    The PROM contains modules to enable a dump of the co-processor adapter's storage, CPU registers, and I/O ports. These modules work in conjunction with the Online Dump Facility, which is part of the system unit support software.


    Application Tasks

    Application tasks are programs written specifically for an application to be executed on the co-processor adapter; that is, the application resides in co-processor adapter storage. Examples of tasks that you might want to write are as follows:


    System Unit Support Software Components

    This section is an introductory discussion of the components of the software packages that reside in the system unit and support the functions provided on the co-processor adapter.


    IBM Realtime Interface Co-Processor DOS Support

    The IBM* Realtime Interface Co-Processor DOS Support product supports communication to and from the co-processor adapter in the DOS environment. It requires IBM DOS Version 3.3 or later. The components of the IBM Realtime Interface Co-Processor DOS Support are an Interrupt Handler, Application Loader Utility, Online Dump Facility, Assembler Language Macros, and a manual that details the functions of each. An overview of each of these components follows.

    Interrupt Handler

    The co-processor adapter Interrupt Handler's main functions are to manage the shared interrupts coming from the co-processor adapter and to signal the system unit application program when interrupts occur from the co-processor adapter. The Interrupt Handler file is called ICAINTH.COM.

    The Interrupt Handler's functions include:

    Application Loader Utility

    The Application Loader utility loads the Realtime Control Microcode and the co-processor adapter application tasks onto the co-processor adapter. The Application Loader Utility is called ICALOAD.COM.

    The Application Loader's job is to:

    The Application Loader Utility can be executed from the keyboard, from another program using a DOS function call, or from a .BAT file. Either .COM or .EXE files can be loaded if the task is written for the co-processor adapter environment.

    Online Dump Facility

    The Online Dump Facility enables the dump of the co-processor adapter environment including registers and memory. It aids in the development of co-processor adapter application tasks. The Online Dump Facility is called ICADUMP.COM.

    Dump Formatter Facility

    The Dump Formatter Facility formats the output from the Online Dump Facility.

    Assembler Language Macros

    The Assembler Language Macros provide an interface to the Interrupt Handler from system unit application programs which need to communicate with the co-processor adapter. Either .COM or .EXE programs may use these macros. Assembler Language Macros are defined in these files: ICAMAC.MAC, ICACMAC.LIB, and ICAEMAC.LIB.


    IBM Realtime Interface Co-Processor OS/2 Support

    The IBM Realtime Interface Co-Processor Operating System/2 (OS/2) Support product supports communication to and from the co-processor adapter in the OS/2 environment. It requires the IBM OS/2 Standard Edition version 1.1 or above. The components of the IBM Realtime Interface Co-Processor OS/2 Support are the Device Driver, Application Loader Utility, Online Dump Facility, Dynamic Link Routines, and a manual that details the functions of each of these. An overview of each of these components follows.

    Device Driver

    The OS/2 Support Device Driver performs the same functions as the DOS Support Interrupt Handler. The Device Driver file is called ICARICIO.SYS.

    Application Loader Utility

    The Application Loader utility loads the Realtime Control Microcode and the co-processor adapter application tasks onto the co-processor adapter. The Application Loader Utility is called ICALDRIC.EXE.

    The Application Loader's job is to:

    The Application Loader Utility can be executed from the keyboard, from another program using an OS/2 function call, or from a .CMD file. Either .COM or .EXE files can be loaded if the file is written for the co-processor adapter environment.

    Online Dump Facility

    The Online Dump Facility enables the dump of the co-processor adapter environment including registers and memory. It aids in the development of co-processor adapter application tasks. The Online Dump Facility file is called ICADPRIC.EXE.

    Dump Formatter Facility

    The Dump Formatter Facility formats the output from the Online Dump Facility.

    Dynamic Link Routines

    The Dynamic Link Routines provide an interface to the device driver from system unit application programs that need to communicate with co-processor adapters. The Dynamic Link Routines are defined in the ICARICDL.LIB file.


    Application Programs

    Application programs residing in the system unit storage can be designed to perform user-defined functions.

    Typical functions might include:

    The system unit application programs can be written in Assembler language to interface with the system software and the co-processor adapter software. You may choose to write your application program in a high-level language and link to user-written Assembler language macro modules that handle the system software and co-processor adapter interface for you.


    Chapter 2. System Unit Support Software Functions

    This chapter provides a reference to functions that are performed by software in the system unit to support the co-processor adapter and describes:

    A discussion of each topic supplies information to help you understand the software functions of the co-processor adapter to write your own applications. Any associated data structures are included. The chapter also contains a list of associated interface modules.


    System Initialization

    The following topics are discussed in this section:


    Bootstrap Loader and Realtime Control Microcode Implementation

    The co-processor adapter Bootstrap Loader's primary responsibility is to act as the co-processor adapter's temporary control microcode until the Realtime Control Microcode can be loaded and started. The Bootstrap Loader supplies only the minimal requirements necessary to supervise the co-processor adapter and its resources. The Bootstrap Loader is located in the PROM and performs the following functions in this sequence:

    1. The Bootstrap Loader is invoked by the PROM-resident power-on self test (POST) following successful completion of its diagnostic testing.

    2. The Bootstrap Loader initializes all interrupt vectors in low storage to point to its first-level interrupt handler designed to control interrupts until the Realtime Control Microcode is loaded.

    3. The Bootstrap Loader initializes necessary tables, a work area, and other data structures in random access memory.

    4. The Bootstrap Loader sets up a temporary buffer control block (BCB) to be used until the load of the Realtime Control Microcode.

    5. The Bootstrap Loader waits for an interrupt from the system unit.

    6. When an interrupt from the system unit is detected, the Bootstrap Loader determines if the interrupt is for Task 0. This interrupt is normally generated from the Loader Utility. If the interrupt is for Task 0 and the command is supported by the Bootstrap loader, go to step 8. If not, go to step 7 to process the error.

    7. The error condition is handled as follows:
      1. The error code to indicate a non-valid task number is placed in the Bootstrap Loader's secondary status field.
      2. The error and secondary status available bits in the Task 0 primary status byte in the interface block are set to 1's.
      3. An FEh value is written to the system unit select byte in the interface block to indicate an error condition
      4. Return to step 5.

    8. The Bootstrap Loader supports a subset of the Realtime Control Microcode command functions necessary to load a task:
      1. Initialize
      2. Request task load
      3. Start task
      4. Free buffer.

    9. When the Realtime Control Microcode (Task 0) is loaded and started correctly, it functions as the control program. Control is not returned to the Bootstrap Loader unless an error occurred in the initialization of the Realtime Control Microcode. Both the Realtime Control Microcode and PROM Bootstrap Loader are considered Task 0 when servicing commands. The term Task 0 is used to refer to either.

    ASSOCIATED INTERFACE MODULES

    ----------------------------------------
    Type       Invocation   Name
    ----------------------------------------
    System     Command      Initialize
    unit to    byte 00h
    Task 0
    command
    
    System     Command      Request Task
    unit to    byte 01h     Load
    Task 0
    command
    
    System     Command      Free Buffer
    unit to    byte 02h
    Task 0
    command
    
    System     Command      Start Task
    unit to    byte 05h
    Task 0
    command
    

    Co-Processor Adapter Task Loading

    The system unit to Realtime Control Microcode commands can be used to request task load space on a co-processor adapter. These functions are automatically performed when the Applications Loader Utility is invoked. Note that these commands only request storage on the co-processor adapter to load the co-processor adapter task. You may choose to use this storage space for buffers or other processing.

    ASSOCIATED INTERFACE MODULES

    -------------------------------------
    Type       Invocation    Name
    -------------------------------------
    System     Command       Request
    unit to    byte 01h      Task Load
    Realtime
    Control
    Microcode
    command
    
    System     Command       Request
    unit to    byte 03h      Task Load
    Realtime                 With Boundary
    Control
    Microcode
    command
    
    System     Command       Request Task
    unit to    byte 0Ch      Load Low
    Realtime
    Control
    Microcode
    command
    

    Task Control Commands

    The system unit program's primary functions are to monitor the storage media, keyboard, display, and communicate with co-processor adapter application tasks, including the Task 0 control program.

    Various functions to control and communicate with co-processor adapter tasks are provided through the system unit to Realtime Control Microcode commands and the Assembler macros.

    ASSOCIATED INTERFACE MODULES

    ------------------------------------
    Type      Invocation   Name
    ------------------------------------
    System    Command      QUERY FREE
    unit to   byte 04h     STORAGE
    Realtime
    Control
    Microcode
    command
    
    System    Command      START TASK
    unit to   byte 05h
    Realtime
    Control
    Microcode
    command
    
    System    Command      STOP TASK
    unit to   byte 06h
    Realtime
    Control
    Microcode
    command
    
    System    Command      UNLOAD TASK
    unit to   byte 07h
    Realtime
    Control
    Microcode
    command
    

    Watchdog Timer Initialization

    The watchdog timer is a free-running hardware timer used to signal an error condition when the co-processor adapter processor fails and cannot report an error. The default state of the watchdog timer is disabled. The watchdog timer may be initialized via system unit to co-processor adapter commands called from system unit application programs.

    When the watchdog timer expires, the Realtime Control Microcode sets its status to indicate a watchdog timer failure, and stops all tasks. You may want to write your own application program to re-initialize the watchdog timer and process this type of error.

    ASSOCIATED INTERFACE MODULE

    -----------------------------------------
    Type       Invocation   Name
    -----------------------------------------
    
    System     Command      Set Watchdog
    unit to    byte 08h     Timer Duration
    Realtime
    Control
    Microcode
    command
    
    System     Command      Enable Watchdog
    unit to    byte 09h     Timer
    Realtime
    Control
    Microcode
    command
    
    System     Command      Disable Watchdog
    unit to    byte 0Ah     Timer
    Realtime
    Control
    Microcode
    command
    
    System     Command      Read Watchdog
    unit to    byte 0Bh     Timer Duration
    Realtime
    Control
    Microcode
    command
    

    System Time Initialization

    A hardware timer on the co-processor adapter is used to maintain a time of day clock which can be set or read by software executing in the system unit. The system time is automatically initialized to that of the system unit by the applications loader facility when it loads the Realtime Control Microcode Version 2.0 or later (system time is not supported on earlier Realtime Control Microcode versions). If synchronization between system unit time and co-processor time is required, application software must provide for clock re-synchronization.

    ASSOCIATED INTERFACE MODULES

    -----------------------------------------
    Type       Invocation   Name
    -----------------------------------------
    
    System     Command      Set Time
    unit to    byte 0Dh
    Realtime
    Control
    Microcode
    command
    
    System     Command      Get Time
    unit to    byte 0Eh
    Realtime
    Control
    Microcode
    command
    

    Asynchronous Error Handling

    Asynchronous errors are those errors or exceptional conditions that occur unexpectedly. Asynchronous errors are usually unrecoverable errors and are often due to hardware failure. These errors are detected by the Realtime Control Microcode and many are reported to the system unit through an error interrupt. Prior to interrupting the system unit, the Realtime Control Microcode takes the necessary steps to process the error condition for the co-processor adapter software.

    The error and secondary status available bits are set to 1's in the Realtime Control Microcode's primary status field, and the interrupt ID (INTID) byte in the interface block is set to FEh value to indicate an error condition. When you configure your system, you may decide to write a special asynchronous error-handling routine for the Interrupt Handler/Device Driver to notify you if one of these errors occurs.


    Realtime Control Microcode Secondary Status Field Error Codes for Asynchronous Errors

    Following are the secondary status field error codes for asynchronous errors. See also "Task 0 Secondary Status Field Definition".

    INVALID OPERATIONS CODE CHECK

    Byte 0 = 03h:
      Non-valid operation code check (also escape (ESC) operation
      code check error)
    Byte 1:
      Task number in execution
    Bytes 2-5:
      Offset:segment of next sequential instruction
    

    CO-PROCESSOR ADAPTER STORAGE PARITY ERROR

    Byte 0 = 04h
    Byte 1:
      Task number in execution
    Bytes 2-5:
      Offset:segment of next sequential instruction
    Byte 6:
      Bits 0-1: Local master error source, 00 = 80186,
      01 = DMA Channel, 10 = Bus master channel.  Bit 1 is msb.
      Bits 2-5: DMA channel number.  Bit 5 is msb.
      Bits 6-7: DMA chip number.  Bit 7 is msb.
    Byte 7:
      Valid only when byte 6, bits 0-1 are non-zero.  Contains
      the task number of the owner of the DMA channel or the
      requestor of the bus master   transfer - zero indicates no
      owner/requestor.
    

    WATCHDOG TIMER EXPIRATION

    Byte 0 = 05h
    Byte 1:
      Task number in execution
    Bytes 2-5:
      Offset:segment of next sequential instruction
    

    TRANSLATE TABLE ERROR

    Byte 0 = 07h
    Byte 1:
      Task number in execution
    Bytes 2-5:
      Offset:Segment of next sequential instruction
    

    DAC ERROR INTERRUPT

    Byte 0 = 08h
    Byte 1:
      Task number in execution
    Bytes 2-5:
      Offset:segment of next sequential instruction
    Byte 6:
      Bit 0:  When set, DAC source is system unit or peer
      processor.  When reset, DAC source is this card.
      Bits 1-4:  When bit 0 is set, contains arb level
      of bus master.
    Byte 7:
      Bits 0-1:  Local master DAC source, 00 = 80186, 01 = DMA
      Channel, 10 = Bus master channel.
      Bits 2-3:  DMA channel chip number.
      Bits 4-7:  DMA channel number.
    

    EXTENDED NON-MASKABLE INTERRUPT ERROR

    Byte 0 = 09h
    

    ASSOCIATED INTERFACE MODULES

    None
    

    CHANNEL CHECK ERROR

    Byte 0 = 0Ah
    Byte 1:
      Bits 1-7 = Reserved.
      Bit 0:  When bit 0 = 0, a Micro Channel write or slave
      read parity error occurred while this card was a bus master.
      When this bit = 1, a Micro Channel write parity error or
      slave read parity error occurred while this card was a
      slave.
    
    Byte 2:
      Bit 0:  When bit 0 = 0, this card was a Micro Channel
      slave during a memory read operation.  The arb level
      identifier bits specify the bus master during the parity
      error cycle.  When this bit = 1, the parity error was a
      Micro Channel data parity error.
      Bit 1:  This bit only has meaning when bit 0 = 1.  When this
      bit = 1, the parity error occurred while this card was a
      bus master reading data from the channel.  When this bit = 0,
      the parity error occurred while another bus master was
      performing a write to this card.
      Bit 2:  This bit only has meaning when bit 1 = 0.  When this
      bit = 0, the error occurred during a memory write.  When
      this bit = 1, the error occurred during an I/O write.
      Bits 3-6:  These bits represent the arb level that was
      present on the Micro Channel at the time of the error.
      Bit 7:  This bit is set when the error occurred as a result
      of a write to the IO/CHCHK register.
    
    Byte 3:
      When Byte 1, bit 0 = 0, contains the task number of the peer
      service requestor when the parity error occurred.  FFh
      indicates no peer service requestor.
    

    Chapter 3. System Unit Commands

    The system unit application programs may issue commands to the co-processor adapter. These commands request various modes of control and services. Some commands are supported only by the Realtime Control Microcode, whereas others are supported by the Realtime Control Microcode and the PROM Bootstrap Loader. Commands are serviced by the PROM Bootstrap Loader until the Realtime Control Microcode is loaded and started. Once the Realtime Control Microcode is loaded and started, all commands are serviced by the Realtime Control Microcode until a reset of the co-processor adapter occurs. Both the Realtime Control Microcode and the PROM Bootstrap Loader are considered Task 0 when servicing commands. The term Task 0 is used to refer to either.


    List of System Unit to Co-Processor Adapter Commands

    List of System Unit Commands
    Command
    Byte
    Number
    Name Function
    00h Initialize Initializes Task 0 and co-processor adapter
    01h Request Task Load Requests task load space
    02h Free Buffer Frees Task 0's input buffer from the system unit
    03h Request Task Load With Boundary Requests task load space with boundary definition
    04h Query Free Storage Requests the size of the largest free storage block
    05h Start Task Starts the specified task
    06h Stop Task Stops the specified task
    07h Unload Task Unloads the specified task
    08h Set Watchdog Timer Duration Sets the watchdog timer duration
    09h Enable Watchdog Timer Enables the watchdog timer
    0Ah Disable Watchdog Timer Disables the watchdog timer (default state)
    0Bh Read Watchdog Timer Duration Returns the current watchdog timer duration
    0Ch Request Task Load Low Request task load space in low memory with boundary definition
    0Dh Set Time Set Realtime Control Microcode system time (Realtime Control Microcode Version 2.x only)
    0Eh Get Time Get Realtime Control Microcode system time (Realtime Control Microcode Version 2.x only)

    General Error Handling

    When a command request is made to the PROM Bootstrap Loader or the Realtime Control Microcode, two preliminary conditions must be met before the command is performed:

    If either of these tests fails, the command is rejected immediately. The error and secondary status available bits in Task 0's primary status byte of the interface block are set to 1's, the secondary status field is set to the appropriate error code value, and the value FEh is written to the PC select byte of the interface block to indicate that an error has occurred.

    If the command passes these two tests, FFh is written in the PC Select Byte and the command is processed. If any errors are detected, the error status code is passed back to the calling program via the Secondary Status field.

    When the system unit program sends a command request to a co-processor adapter task which is running under the Realtime Control Microcode, the Realtime Control Microcode checks to see if the task is busy. If the task is busy, the command is rejected as described in the preceding paragraph. If the task is not busy, the called task must perform any further handling. If the task detects an error in processing the command, the task must set up its own secondary status field, set the error bit in its primary status byte in the interface block, and interrupt the system unit.


    Primary Status Byte Definition

    
    Name     Bit   Description
    ----------------------------------------------------------------
    Load      0    Loaded.  This bit is set by the Realtime Control
                   Microcode when a task is loaded or built.  It
                   is reset when a task is unloaded.
    
    
    Init      1    Initialized.  This bit is set by the Realtime
                   Control Microcode when a task issues the
                   Initcomp SVC.  It is reset when a task is
                   stopped.
    
    
    Restart/  2    For Task 0, bit on indicates that the
    Input          co-processor adapter is requesting a system
                   restart of the system unit.  The system
                   unit should simulate the Ctrl+Alt+Del
                   sequence via software to cause the system
                   unit to restart.  It is reset when Task 0
                   is initialized.
    
                   Tasks may use this bit to indicate that input
                   data is ready to be read by the system unit.
                   The use of this bit is optional and not
                   checked by the Realtime Control Microcode.  If
                   the bit is used by a task, the task is
                   responsible for both setting and resetting it.
    
    
    Watchdog  3    Watchdog active if on (used by the Realtime
                   Control Microcode only; for task,
                   user-definable).  It is set when the watchdog
                   timer is active.
    
                   Tasks may use bit 3 to indicate that the task
                   is ready to receive data from the system unit.
                   The use of this bit is optional and not
                   checked by the Realtime Control Microcode.  If
                   the bit is used by a task, the bit is
                   responsible for setting and resetting it.
    
    Name     Bit   Description
    --------------------------------------------------------------
    Error     4    Bit on indicates that the task has detected an
                   error.  The task's secondary status should be
                   examined to determine the cause of the error.
                   This bit is reset by the Realtime Control
                   Microcode after receipt of a command directed
                   to this task from the system unit.  It is set
                   by the task.
    
    
    Status    5    Secondary status available.  This bit is set
                   by the task and is used to indicate that the
                   data in the task's secondary status buffer is
                   valid.  The bit is reset by the Realtime
                   Control Microcode after receipt of a command
                   directed to this task from the system unit.
    
    
    Output    6    Output buffer busy.  This bit is set by the
                   Realtime Control Microcode when a task
                   receives a command.  It indicates that the
                   task's output buffer should not be
                   overwritten.  This bit should be cleared by
                   the task.
    
    
    Busy      7    Busy.  A task cannot receive commands from
                   the system unit when this bit is set.  It is
                   set by Realtime Control Microcode when a task
                   receives a command from the system unit.  This
                   is the only interlock-type bit that must be
                   tested before single-byte commands are issued.
                   The commands that require parameters in the
                   output buffer must also check the output busy
                   bit before the parameters are written to the
                   output buffer.  This bit should be cleared by
                   the tasks.
    

    Task 0 Secondary Status Field Definition

    The location of the secondary status field is contained in the task 0 buffer control block (BCB). The Task 0 secondary status field is defined in the following table. The error codes for the system unit to Task 0 commands are located in the column where byte 0 equals 02h.

    +----------------------------------------------------------+
    
    | Task 0 Secondary Status Field                            |
    +--------+------------------+------------------------------+
    | Byte 0 | Field Name       | Byte 1                       |
    
    +--------+------------------+------------------------------+
    |  00h   | No error         | Undefined                    |
    +--------+------------------+------------------------------+
    |  01h   | Power-on         | 01h Processor error          |
    |        | diagnostic       | 02h RAM error                |
    |        | tests            | 03h Checksum error           |
    |        | errors           | 04h CIO test error           |
    |        |                  | 05h-0Ch For these values,    |
    |        |                  |     see "Task 0 Secondary    |
    |        |                  |     Status Field Definition,"|
    |        |                  |     under "Buffer Control    |
    |        |                  |     Block," in Chapter       |
    |        |                  |     10 or 12, as applicable. |
    +--------+------------------+------------------------------+
    |  02h   | System unit      | 01h Non-valid command        |
    |        | application      | 02h Insufficient storage     |
    |        | programs to      | 03h Non-valid command data   |
    |        | Task 0           | 04h Non-valid task header    |
    |        | command          | 05h Non-valid task number    |
    |        | errors           | 06h Task previously loaded   |
    |        |                  | 07h Task previously started  |
    |        |                  | 08h Non-valid task priority  |
    |        |                  | 09h Non-valid command        |
    |        |                  |     sequence                 |
    |        |                  | 0Ah Non-valid interface      |
    |        |                  |     block data               |
    |        |                  | 0Bh Task stopped by          |
    |        |                  |     debug facility           |
    |        |                  | 0Ch Task previously stopped  |
    |        |                  |     or not started           |
    |        |                  | 0Dh Task is permanent        |
    |        |                  | 0Eh Task # not available     |
    |        |                  | 0Fh Name not found           |
    |        |                  | 10h Non-valid adapter        |
    |        |                  | 11h Resource not available   |
    |        |                  | 12h Peer initialization error|
    +--------+------------------+------------------------------+
    |  03h   | Invalid operation| See note below               |
    |        | code             |                              |
    +--------+------------------+------------------------------+
    |  04h   | Parity error     | See note below               |
    +--------+------------------+------------------------------+
    |  05h   | Watchdog timer   | See note below               |
    |        | timed out        |                              |
    +--------+------------------+------------------------------+
    |  06h   | System unit      | Undefined                    |
    |        | cannot be        |                              |
    |        | interrupted      |                              |
    +--------+------------------+------------------------------+
    |  07h   | Translate table  | See note below               |
    |        | error            |                              |
    +--------+------------------+------------------------------+
    |  08h   | DAC error        | See note below               |
    +--------+------------------+------------------------------+
    |  09h   | External non     | Undefined                    |
    |        | maskable         |                              |
    |        | interrupt error  |                              |
    +--------+------------------+------------------------------+
    |  0Ah   | Channel check    | See note below               |
    |        | error            |                              |
    +--------+------------------+------------------------------+
    |  FFh   | System restart   | Undefined                    |
    |        | request          |                              |
    +--------+------------------+------------------------------+
    

    Note:

    See "Asynchronous Error Handling" for additional information on Secondary Status Field values for asynchronous errors.

    Descriptions of System Unit to Co-Processor Adapter Commands

    A description of each system unit to co-processor adapter command is provided in the remainder of this chapter.


    Initialize

    Initializes Task 0 and the co-processor adapter.

    INVOCATION: Command byte 00h

    ----------------------------------------------------

    FUNCTION:

    This command is supported by both the PROM Bootstrap Loader and the Realtime Control Microcode. If the PROM Bootstrap Loader is servicing commands, it causes the co-processor adapter and PROM Bootstrap Loader to be set to the power-on state. If the Realtime Control Microcode is servicing commands, this command initializes the Realtime Control Microcode to the started state. No application tasks remain loaded and all components are reset to defined states. If the Realtime Control Microcode is servicing commands, the Realtime Control Microcode remains loaded and all co-processor adapter resources are returned to it. This is the only command that Task 0 accepts if it is currently busy. Task 0 interrupts the system unit at the completion of the command.

    This command should not be issued to a Portmaster Adapter/A when peer services are used. Use the Reset function in Operating System Support.

    Entry Parameters

    (Task 0 output buffer)
    None
    

    Exit Parameters

    (Task 0 input buffer)
    None
    

    Errors

    None
    


    Request Task Load

    Requests task load space.

    INVOCATION: Command byte 01h

    ----------------------------------------------------

    FUNCTION:

    This command is supported by both the PROM Bootstrap Loader and the Realtime Control Microcode. A request for storage space to load an application task into co-processor adapter storage is made via this command. Task 0 returns the storage address segment of where the task is to be loaded.

    Task 0 checks for a storage block large enough to hold the task that is to be loaded. The search for the storage block begins at the high end of available co-processor adapter RAM. If a large enough block of storage is found, Task 0 removes that block of storage from the free storage chain. Task 0 indicates the segment of the storage block via Task 0's input buffer. At this point, Task 0 has allocated a storage block for the task to be loaded and considers the task to be loaded. Note that a system unit application program can use this command to obtain storage space on the co-processor adapter and not load a task to this space but instead use this storage as buffer space on the co-processor adapter. When this is done in Realtime Control Microcode Version 2.x, the first two paragraphs of storage contain storage allocation information and should not be overwritten.

    For Realtime Control Microcode Version 1.x, the user must put the task size into the first four bytes (32 bits) of the storage block (task header). This is later used by the Realtime Control Microcode to release this block.

    Task 0 interrupts the system unit at the completion of this command. This command does not load tasks into expanded memory.

    Entry Parameters

    (Task 0 output buffer)
    Task number (byte)
    Size low    (word) - Low-order word of the task size
    Size high   (word) - High-order word of the task size
    
    

    Exit Parameters

    (Task 0 input buffer)
    Location (word) - Segment value of where the task is to be
                      loaded in the co-processor adapter's storage
    

    Errors

    -----------------------------------------------
       Error Code
    Byte 0    Byte 1          Meaning
    -----------------------------------------------
    
     02h       02h            Insufficient storage
     02h       05h            Non-valid task number
     02h       06h            Task already loaded
    


    Free Buffer

    Frees Task 0's input buffer from the system unit.

    INVOCATION: Command byte 02h

    ----------------------------------------------------

    FUNCTION:

    This command is supported by both the PROM Bootstrap Loader and the Realtime Control Microcode. It tells Task 0 that its input buffer is no longer being used by the system unit.

    The system unit application program issues this command when it has finished processing the data from Task 0's input buffer. The system unit is not interrupted by Task 0 when the command is completed.

    Entry Parameters

    (Task 0 output buffer)
    None
    

    Exit Parameters

    (Task 0 input buffer)
    None
    

    Errors

    None
    


    Request Task Load with Boundary

    Requests task load space with boundary definition.

    INVOCATION: Command byte 03h

    ----------------------------------------------------

    FUNCTION:

    This command is supported by the Realtime Control Microcode only. It requests storage space on a specific paragraph boundary to load an application task into co-processor adapter storage. The Realtime Control Microcode returns the storage address segment of where the task is to be loaded.

    This function is the same as command 01h Request Task Load, except that a specific boundary for the storage space into which the task is to be loaded is also requested. The boundary, which must be a power of 2 (only one bit of this 16-bit value may be on), indicates the multiples of a paragraph that is defined for a boundary. (A paragraph is defined as sixteen 8-bit bytes.) For example, the value 0001h or 0000h indicates a one-paragraph boundary; 0002h indicates a two-paragraph or even paragraph boundary; 0200h indicates a 512-paragraph boundary, which is equivalent to an 8192-byte boundary. Task 0 interrupts the system unit at the completion of this command.

    A system unit application program can use this command to obtain storage space on the co-processor adapter and not load a task to this space but instead use this storage as buffer space on the co-processor adapter. When this is done, the first two paragraphs of storage contain storage allocation information and should not be overwritten.

    This command does not load tasks into expanded memory.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    Task number (byte)
    Size low    (word)  - Low-order word of the task size
    Size high   (word)  - High-order word of the task size
    Boundary    (word)  - Paragraph boundary requested for a task.
                          Valid range must be a power of 2.  (A
                          value of 0 or 1 results in a paragraph
                          boundary of 1.)
    
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    Location (word) - Segment value of where the task is to be
                      loaded in the co-processor adapter storage
    

    Errors

    ----------------------------------------------
       Error Code
    Byte 0    Byte 1          Meaning
    ----------------------------------------------
    
     02h       02h            Insufficient storage
     02h       05h            Non-valid task number
     02h       06h            Task already loaded
    


    Query Free Storage

    Requests the size of the largest free storage block.

    INVOCATION: Command byte 04h

    ----------------------------------------------------

    FUNCTION:

    This command is supported by the Realtime Control Microcode only. The Realtime Control Microcode locates the largest free storage block in base memory, and returns the segment and size of that block and the total number of free paragraphs to the system unit program. The co-processor adapter interrupts the system unit at command completion.

    This command reports only base memory, not expanded memory.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    None
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    Location (word) - Segment value of the storage block
    Size     (word) - Size of block in paragraphs
    Total    (word) - Total number of paragraphs of free storage
    

    Errors

    None
    


    Start Task

    Starts the specified task.

    INVOCATION: Command byte 05h

    ----------------------------------------------------

    FUNCTION:

    This command is supported by both the PROM Bootstrap Loader and the Realtime Control Microcode. If the Realtime Control Microcode is the task that is started, all further commands are serviced by the Realtime Control Microcode. When the Realtime Control Microcode services this command, it starts the specified co-processor adapter task. The task is started by building a task control block (TCB) from the task header, putting an entry into the task control block table (TCBTAB), and posting the task at its initial entry point. If any errors are detected, the command is not performed. After the task is started, the Realtime Control Microcode interrupts the system unit.

    This command performs the same function as the Start SVC.

    Entry Parameters

    (Task 0 output buffer)
    Task number (byte)
    

    Exit Parameters

    (Task 0 input buffer)
    None
    

    Errors

    ----------------------------------------------------------
       Error Code
    Byte 0    Byte 1          Meaning
    ----------------------------------------------------------
    
     02h       04h            Non-valid task header
     02h       05h            Non-valid task number
                              (also caused if task
                              is not loaded)
     02h       07h            Task already started
     02h       08h            Non-valid task priority
    


    Stop Task

    Stops the specified task.

    INVOCATION: Command byte 06h

    ----------------------------------------------------

    FUNCTION:

    This command is supported only by the Realtime Control Microcode. The specified task is stopped. All the task resources are returned to the Realtime Control Microcode and reset to a defined state. The task is removed from the task control block table (TCBTAB). The initialized bit in the task's primary status byte in the interface block is set to 0. The task is put into the same state as just having been loaded. All "child" tasks of the specified task are unloaded. If the specified task is already stopped, the command is not performed. The Realtime Control Microcode interrupts the system unit at the completion of this command.

    This command performs the same function as the Stop SVC.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    Task number (byte)
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    None
    

    Errors

    --------------------------------------------------------
       Error Code
    Byte 0    Byte 1          Meaning
    --------------------------------------------------------
    
     02h       05h            Non-valid task number
     02h       0Ch            Task previously stopped or not
                              started
     02h       0Dh            Task is permanent
    


    Unload Task

    Unloads the specified task.

    INVOCATION: Command byte 07h

    ----------------------------------------------------

    FUNCTION:

    This command is supported only by the Realtime Control Microcode. The specified task is unloaded from the co-processor adapter storage. If the task is not already stopped, it is stopped as described in the "Stop Task" command in this chapter. Then the task's resident storage is returned to the free memory pool and the loaded bit in the task's primary status byte in the interface block is reset to 0. The task is also removed from the task table (TASKTAB). If any errors are detected, the command is not performed. When the command is complete, the Realtime Control Microcode interrupts the system unit.

    This command performs the same function as the Unload SVC.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    Task number (byte)
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    None
    

    Errors

    -----------------------------------------------
       Error Code
    Byte 0    Byte 1          Meaning
    -----------------------------------------------
    
     02h       05h            Non-valid task number
     02h       0Dh            Task is permanent
    


    Set Watchdog Timer Duration

    Sets the watchdog timer duration.

    INVOCATION: Command byte 08h

    ----------------------------------------------------

    FUNCTION:

    This command is supported only by the Realtime Control Microcode. The duration of the watchdog timer is set but the timer is not started. If the watchdog timer is already running, the new duration takes effect during the next dispatch cycle. The valid range of counts is 0 through 65535. A value of 0 indicates the minimum value, which is 1. Each count equals 1.11111 milliseconds. When the command is complete, the Realtime Control Microcode interrupts the system unit.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    Counts (word) - Delay value in 1.11111 millisecond steps
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    None
    

    Errors

    None
    


    Enable Watchdog Timer

    Enables the watchdog timer.

    INVOCATION: Command byte 09h

    ----------------------------------------------------

    FUNCTION:

    This command is supported only by the Realtime Control Microcode. The watchdog timer is enabled. If the duration is not set, the default duration of 65535 counts is used. Each count in the duration is equal to 1.11111 milliseconds. When the command is complete, the Realtime Control Microcode interrupts the system unit.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    None
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    None
    

    Errors

    None
    


    Disable Watchdog Timer

    Disables the watchdog timer (default state).

    INVOCATION: Command byte 0Ah

    ----------------------------------------------------

    FUNCTION:

    This command is supported only by the Realtime Control Microcode. The watchdog timer is disabled; this is the default state. When the command is complete, the Realtime Control Microcode interrupts the system unit.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    None
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    None
    

    Errors

    None
    


    Read Watchdog Timer Duration

    Returns the current watchdog timer duration.

    INVOCATION: Command byte 0Bh

    ----------------------------------------------------

    FUNCTION:

    This command is supported only by the Realtime Control Microcode. It reads the current value of the watchdog timer duration and puts it into the Realtime Control Microcode's input buffer. When the command is complete, the Realtime Control Microcode interrupts the system unit.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    None
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    Duration (word) - Current value of watchdog timer duration
    

    Errors

    None
    


    Request Task Load Low

    Requests task load in low memory, with boundary definition.

    INVOCATION: Command byte 0Ch

    ----------------------------------------------------

    FUNCTION:

    This command requests storage for a task to be loaded on the specified boundary at the lowest available memory block of the requested size.

    This command is supported by the Realtime Control Microcode only. It requests storage space on a specific paragraph boundary to load an application task into co-processor adapter storage. The Realtime Control Microcode returns the storage address segment of where the task is to be loaded.

    The function is the same as Command 03h Request Task Load With Boundary, except that the search for the requested load space begins at the low end of the co-processor adapter memory. The boundary, which must be a power of 2 (only one bit of this 16-bit value may be on), indicates the multiples of a paragraph that is defined for a boundary. (A paragraph is defined as sixteen 8-bit bytes.) For example, the value 0001h or 0000h indicates a one-paragraph boundary; 0002h indicates a two-paragraph or even paragraph boundary; 0200h indicates a 512-paragraph boundary, which is equivalent to an 8192-byte boundary. The Realtime Control Microcode interrupts the system unit at the completion of this command.

    A system unit application program can use this command to obtain storage space on the co-processor adapter and not load a task to this space but instead use this storage as buffer space on the co-processor adapter. When this is done, the first two paragraphs of storage contain storage allocation information and should not be overwritten.

    This command does not load tasks into expanded memory.

    Entry Parameters

    (Realtime Control Microcode output buffer)
    Task number (byte)
    Size Low    (word) - Low-order word of the task size
    Size High   (word) - High-order word of the task size
    Boundary    (word) - Paragraph boundary requested for a task.
                         Valid range must be a power of 2.  (A
                         value of 0 or 1 results in a paragraph
                         boundary of 1.)
    

    Exit Parameters

    (Realtime Control Microcode input buffer)
    Location (word) - Segment value of where the task is to be loaded
                      in the co-processor adapter storage
    
    

    Errors

    -----------------------------------------------
       Error Code
    Byte 0  Byte 1            Meaning
    -----------------------------------------------
     02h     02h              Insufficient storage
     02h     03h              Non-valid command data
     02h     05h              Non-valid task number
     02h     06h              Task already loaded
    


    Set Time

    Sets co-processor system time.

    INVOCATION: Command byte 0Dh

    ----------------------------------------------------

    FUNCTION:

    This command sets the time-of-day system time on the co-processor to the values contained in Realtime Control Microcode's output buffer. It is supported in Realtime Control Microcode Version 2.x only.

    The format of the output buffer is identical to the timeb structure used by the C-ftime() function. By using this format, the C-library time functions can be used to support time conversions.

    Entry Parameters (task 0 output buffer)

     Byte     Field Name    Description
    ------------------------------------------------------
     00h-     SECONDS       Seconds since 1-1-70
     03h
     04h-     MILLISEC      Milliseconds
     05h
     06h-     TIMEZONE      Minutes from UTC, -1 = time
                            zone undefined
     07h
     08h-     DSTFLAG       Daylight savings time flag
     09h
    
    

    Exit Parameters (task 0 input buffer)

     None
    
    

    Errors (task 0 secondary status)

    -----------------------------------------------
       Error Code
    Byte 0    Byte 1     Meaning
    -----------------------------------------------
    02h       03         Non-valid command data - milliseconds
                         out of range
    


    Get Time

    Gets co-processor system time.

    INVOCATION: Command byte 0Eh

    ----------------------------------------------------

    FUNCTION:

    This command gets the time-of-day system time from the co-processor and places it in Realtime Control Microcode's input buffer. It is supported in Realtime Control Microcode Version 2.x only.

    The format of the output buffer is identical to the timeb structure used by the C-ftime() function. By using this format, the C-library time functions can be used to support time conversions.

    Entry Parameters (task 0 output buffer)

     None
    
    

    Exit Parameters (task 0 input buffer)

     Byte   Field Name    Description
    -----------------------------------------------------------
    00h-    SECONDS       Seconds since 1-1-70
    03h
    04h-    MILLISEC      Milliseconds
    05h
    06h-    TIMEZONE      Minutes from UTC, -1 = time
    07h                   zone undefined
    08h-    DSTFLAG       Daylight savings time flag
    09h
    
    

    Errors (task 0 secondary status)

     None
    

    Chapter 4. Co-Processor Adapter Communications

    There are two methods for transferring data between the system unit and the co-processor adapters. The first method is via the shared storage interface. The co-processor adapter I/O ports are used to map the adapter's storage window into system unit address space. The system unit then has addressability to the adapter's storage and can move data between its storage and co-processor adapter storage. When referring to co-processor adapter's memory, the window is called a page. A page can be configured as 8192 bytes (8KB), 16384 bytes (16KB), 32768 bytes (32KB), or 65536 bytes (64KB). Current software supports page sizes from 8KB through 64KB. The Realtime Interface Co-Processor Adapter, Multiport Adapter and Multiport Adapter, Model 2 supports 8192 bytes pages only.

    Note:

    The co-processor's window location may conflict with other adapters. In particular, an Expanded Memory System (EMS) adapter page frame location should be explicitly set not to conflict with the co-processor window.

    The second method is supported by Portmaster Adapter/As and uses the bus master capability of the microchannel. I/O ports accessible to software executing on the co-processor adapter can be programmed to transfer data between itself and the system unit (or any slave device on the microchannel).

    The PROM Bootstrap Loader, Realtime Control Microcode, and application tasks all use the shared storage interface. In this discussion, the Bootstrap Loader, the Realtime Control Microcode, and the application tasks are referred to as "tasks." There is a control block (the interface block) located at 00440h of co-processor adapter storage, which is used to communicate with tasks on the co-processor adapter. See or for details on this control block.

    Various operations must be performed to communicate with tasks that are running on the co-processor adapter. These functions may be performed using resources that are in the operating system support packages, such as the IBM Realtime Interface Co-Processor DOS Support and the IBM Realtime Interface Co-Processor Operating System/2 (OS/2) Support products. The following discussion assumes that the shared storage interface is used for data transfer and that a support product is not being used.

    The operations that must be performed to communicate with the co-processor adapter are as follows:

    1. Set up the co-processor adapter after a power-on or reset condition.

    2. Load the Realtime Control Microcode from a disk file to co-processor adapter storage.

    3. Start the Realtime Control Microcode by issuing the Start Task command to the Bootstrap Loader.

    4. Load and start co-processor adapter tasks (for a description, refer to steps 2 and 3).

    5. Pass commands to co-processor adapter tasks.

    6. Pass data to and from co-processor adapter tasks.

    7. Field interrupts coming from co-processor adapter tasks.

    Each of these operations is described in the following sections.


    Co-Processor Adapter Setup

    All the co-processor adapter setup can be handled by the IBM Realtime Interface Co-Processor DOS Support Interrupt Handler or the IBM Realtime Interface Co-Processor OS/2 Support Device Driver. The following discussion assumes that neither of these is used.

    Before the co-processor adapter can be set up, information about the system configuration must be known. This includes the base I/O address of the co-processor adapter, the desired system unit storage location for the co-processor adapter window, and the address to set the Ctrl+Alt+Del registers.

    Use the I/O address found, plus the offset for each co-processor adapter register, to read or write the co-processor adapter registers. The co-processor adapter registers are accessed via I/O input or output.

    The system unit cannot communicate with the co-processor adapter until after its power-on self test (POST) diagnostics have completed. There is a sequence of operations that must be performed to tell if the POST diagnostics are finished.

    Because at power-up time the co-processor adapter I/O is not gated to the system unit I/O space until the co-processor adapter has finished its POST diagnostics, the I/O can be checked to see when the diagnostics are finished. If a hardware reset has been issued to the co-processor adapter, the I/O is still gated on, but the diagnostics may be running. It may take up to 20 seconds for the co-processor adapter to complete all diagnostic testing. Because it is best not to wait the full 20 seconds each time, you can detect when the diagnostics are finished by examining storage locations in the co-processor adapter.

    On a Realtime Interface Co-Processor Adapter, a Multiport Adapter, or a Multiport Adapter, Model 2, to determine if the co-processor adapter I/O is gated on, write a known valid value to the Pointer Register (offset 2) in the co-processor adapter, read it back, and compare it. Multiple values should be used, because the tri-state bus of the system unit gives varying values. Values that do not cause trouble are from 0-3, 5-8, and 0Ah-0Eh. On the Multiport/2 Adapter and Portmaster Adapter/A, the ROSREADY bit indicates when the PROM has finished initialization. The ROSREADY bit is bit 6 in INITREG1 (INITREG1 may be referenced by writing 10h to the pointer register and then reading the data register).

    Before the co-processor adapter storage locations can be checked, the co-processor adapter storage must be gated on the system unit. The following paragraphs describe how to do this.

    The location of the window in system unit storage must be in an address space where there is no system ROM or RAM. If you are using an 80286-based system unit, and the co-processor adapter is set up in 16-bit bus width mode, the co-processor adapter window location requires an address space where there is no 8-bit device in the same 128K region as the co-processor adapter window.

    Normally, unused ROM space above 0C0000h is a good place to put the co-processor adapter shared storage window; however, this depends on your particular system. If there are multiple co-processor adapters installed in the same system unit, they cannot use the same window location.

    The Ctrl+Alt+Del (CAD) detection feature is activated by writing a value into the CAD registers in the co-processor adapter. For the Multiport/2 and the Portmaster Adapter/A adapters, the value written to the CAD register is a don't care. For the Realtime Interface Co-Processor, the Multiport, and the Multiport Adapter, Model 2 adapters, the value should be an address that the system unit issues during the reboot sequence. If nothing is written to these registers, the feature is inactive. On most system units, a good value for these registers is an address 16 bytes above the start of BIOS ROM in the system unit. This address is 0FE010h and is used because it is a copyright statement of BIOS that is accessed at ROM checksum time after the system is re-booted.

    On some system units, for example the IBM Personal System/2* (PS/2*), memory accesses to the BIOS are not presented to the expansion slot adapters and are not detected by the co-processor adapter. On these system units, the CAD address must be a value on a 2048-byte boundary within the system unit expansion ROM address space (0C0000h-0DFFFFh). The optimal address is one where no expansion ROM exists, because this address should only be accessed when the system unit is performing the expansion ROM detection scan, following a re-boot or power-on sequence. In this situation, a good address is the first 2048-byte boundary directly preceding the start of the co-processor adapter shared storage window. Because the system unit expansion BIOS detection scan is from low addresses to high addresses, this CAD address is accessed before the co-processor adapter shared storage window, degating the shared memory.

    For example, if the system unit has an unused expansion ROM address range from D0000h-DC000h, the co-processor adapter shared storage window could be located from D8000h-D9FFFh (page 6Ch) and the CAD address could be located at D7800h. Accessing this location causes the co-processor adapter storage to be degated and a non-maskable interrupt is sent to the co-processor adapter processor. If any programs access this location, the same action takes place. The values may need to be changed if an application program on your system unit accesses the location to which the CAD registers point.

    Once the values for the location register are known, the location register meg and page values can be written by doing I/O outputs to the correct co-processor adapter registers. To gate the co-processor adapter storage on, the CPUPAGE register must be written. When CPUPAGE is written, the co-processor adapter storage appears in the window specified by the location register values.

    To determine if the diagnostics are finished, first check the co-processor adapter I/O gating as described previously. If the I/O is gated on, next gate the co-processor adapter storage on and set the CPUPAGE register to 0. On a Realtime Interface Co-Processor or Realtime Interface Co-Processor Multiport, examine word location 040Ch (in the co-processor adapter window) for the value of ABBAh. On a Multiport Adapter, Model 2, examine word location 040Ch (in the co-processor adapter window) for the value of 5AA5h. If this value is not found, continue checking for 20 seconds. If 20 seconds has passed and the value is not there, the co-processor adapter is not functioning correctly.

    After the value is found at offset 040Ch, check byte location 047Ch in the co-processor adapter window. If it contains a value of C0h, the diagnostics are still running. If it contains a value of 03h, the Realtime Control Microcode is still installed and running, which means that the co-processor adapter was not reset and is still functioning. Continue checking offset 047Ch until the value is not C0h. If, after 20 seconds, the value is still C0h, the co-processor adapter is not functioning correctly. If the value is not C0h or has changed from C0h to some other value, the diagnostics have finished and communication with the co-processor adapter may proceed.

    On a Multiport/2 Adapter or a Portmaster Adapter/A, polling the ROSREADY bit is a sufficient verification of the PROM initialization completion.


    Realtime Control Microcode Storage

    Loading and starting the Realtime Control Microcode and other tasks can be performed using either the Application Loader Utility that is part of the IBM Realtime Interface Co-Processor DOS Support product, or the Application Loader Utility that is part of the IBM Realtime Interface Co-Processor OS/2 support product. The following discussion assumes that neither support product is being used.

    To load the Realtime Control Microcode (ICARCM.COM or ICAAIM.COM) requires that the file be read from a disk or diskette file into system unit storage. The first 4 bytes of the file are the load module length in 32-bit format. The number 12345678h would be represented as 78563412h. Only the first word (16-bits) is used because the length is always less than 64K bytes. The next word is 0000h.

    Before loading the Realtime Control Microcode to co-processor adapter storage, MAXTASK, MAXTIME, MAXQUEUE, and MAXPRI values must be set up in the interface block in co-processor adapter storage. This information is stored in the interface block by selecting co-processor adapter page 0 and moving the information directly into the interface block.

    Using the load module size of ICARCM.COM (or ICAAIM.COM) and task 0, issue a Request Task Load command to the PROM Bootstrap Loader on the co-processor adapter. The PROM Bootstrap Loader interrupts the system unit when it has completed the command. After the interrupt occurs, check the primary status for Task 0. If there are no errors and the loaded bit is on, the location (in paragraphs) in co-processor adapter storage where the task is to be put is in Task 0's input buffer.

    Using this information, translate the paragraph location value into a page and offset value. For example, when the shared storage window size is 8192 bytes, this is done by getting the low-order 9 bits of the returned location and saving them.

    Next shift the location right 9 bits. The result is the page number. Shift left 4 bits the low-order 9 bits that were saved previously. The result is the offset into the page where the task is to be loaded. Using the new page and offset values, move the data file into co-processor adapter storage. The page value in the co-processor adapter CPUPAGE register must be updated every time a page boundary is crossed.

    After the task is loaded into co-processor adapter storage, the task header must be updated with the task number and initial segment values before the task can be started. The TASKNUM byte location in the task header must be set to 0 for the Realtime Control Microcode task. The location value that was received from the Request Task Load command is put into the CMDSEG, INITSEG, DATASEG, and STKSEG word locations in the task header in co-processor adapter storage. Because the Realtime Control Microcode is a .COM file, these values could have been filled in while the task was in system unit storage and the task could have been moved to co-processor adapter storage unmodified. After all the data has been moved into co-processor adapter storage and the task header has been updated, the Realtime Control Microcode is loaded, but it is not running. The next section describes how to start the Realtime Control Microcode.


    Starting the Realtime Control Microcode

    Loading and starting the Realtime Control Microcode and other tasks can be performed using either the Application Loader Utility that is part of the IBM Realtime Interface Co-Processor DOS Support product, or the Application Loader Utility that is part of the IBM Realtime Interface Co-Processor OS/2 Support product. The following discussion assumes that neither support product is being used.

    To start the Realtime Control Microcode, issue the Start Task command to the PROM Bootstrap Loader (Task 0) after you have loaded ICARCM.COM (or ICAAIM.COM). After the Realtime Control Microcode is started, it supports all Realtime Control Microcode commands and other tasks that can be loaded.


    Passing Commands to a Co-Processor Adapter Task

    Transferring data to and from the co-processor adapter and issuing commands to the Realtime Control Microcode are made easier by use of either the Assembler Language Macros that are part of the IBM Realtime Interface Co-Processor DOS Support product, or the Dynamic Link Routines that are part of the IBM Realtime Interface Co-Processor OS/2 Support product. The following discussion assumes that neither support product is being used.

    Commands are sent to co-processor adapter tasks by writing the command byte into the first byte of a task's buffer control block (BCB) and any extra parameters in the task's output buffer. When this is done, the PC select byte at page 0 location 0440h in the co-processor adapter is written with the task number and the co-processor adapter is interrupted with the desired task number. To do this, follow these steps:

    1. Find the task's primary status byte and check for the task being loaded and initialized. To find the task's primary status byte, add the co-processor adapter task number to 047Ch. The result is the offset within page 0 of that task's primary status byte. The loaded and started bits are bits 0 and 1, and both of these bits should be on. If they are, check for busy (primary status byte bit 7). If the task is busy, you cannot issue a command to it. If the command has associated parameters that are be passed in the output buffer, the output buffer busy status (primary status byte bit 6) must also be checked. If the output buffer is busy (on) and the command requires that data be included in the output buffer, the command cannot be issued until the output buffer is not busy (off).

    2. Locate the BCB array by examining the BCB pointer at offset 045Ah in co-processor adapter page 0. This word location contains the offset, in page 0, of the BCB array. There is one task BCB for each possible task on the co-processor adapter. To find the correct task BCB, shift the task number left 4 bits and add the result to the word value from offset 045Ah. This results in the offset of the task BCB for that task within page 0. All BCBs are in page 0 of co-processor adapter storage.

    3. The output buffer is the location to which system unit programs should write command parameters. To find the output buffer location, examine 0Dh bytes in the task BCB. This word value is the offset of the task's output buffer. To get the page of the output buffer, examine the byte at 0Fh bytes in the task BCB. When this information is known, the output buffer may be accessed by writing the co-processor adapter CPUPAGE register to the page value found previously. Use the offset found here to access the task's output buffer in co-processor adapter storage through the co-processor adapter window.

    4. Write the command byte into the first byte of the task BCB. Write the extra parameters, if needed, into the task's output buffer. Note that if the output buffer crosses a page boundary in co-processor adapter storage, the co-processor adapter CPUPAGE register must be updated when the boundary is crossed while writing the data.

    5. Check the PC select byte, located at page 0 offset 0440h, for the value of FFh or FEh. If it is not one of these values, the co-processor adapter is processing a previous command. System unit interrupts should be disabled before performing this step.

    6. Write the task number into the PC select byte at page 0 offset 0440h.

    7. Interrupt the co-processor adapter by performing an 8-bit I/O write to the co-processor adapter pointer register with a value of 09h. System unit interrupts should be re-enabled after this step if they were disabled in step 5.

    8. Monitor the PC select byte at page 0 offset 0440h. When it changes from the task number to FFh or FEh, the co-processor adapter has received the command. If FEh appears in the PC select byte, the Realtime Control Microcode has detected an error in the command. A value of FFh indicates that the command was received without error.

    Co-Processor Adapter Task Data Transfer

    Transferring data to and from the co-processor adapter and issuing commands to the Realtime Control Microcode are made much easier by use of either the Assembler Language Macros that are part of the IBM Realtime Interface Co-Processor DOS Support product, or the Dynamic Link Routines that are part of the IBM Realtime Interface Co-Processor OS/2 Support product. The following discussion assumes that neither support product is being used.

    The buffer from which the system unit program receives data is called the "input buffer". To determine where data to be received by the system unit is located, do the following:

    1. Set the CPUPAGE register on the co-processor adapter to 0. This register is at an offset of 5 from the base I/O address. It is set by writing a value of 00h to the base address plus 5; this is an 8-bit I/O port.

    2. Locate the start of the buffer control block (BCB) array by examining the task BCB pointer at offset 045Ah in co-processor adapter page 0. This word location contains the offset, in page 0, of the BCB array. There is one task BCB for each possible task on the co-processor adapter. To find the correct BCB, shift the task number left 4 bits and add the result to the value from offset 045Ah. This results in the offset of the task BCB for that task within page 0. All BCBs are in page 0 of co-processor adapter storage.

    3. The 16-bit length of the input buffer is at offset 6 in the task BCB. At offset 8 in the task BCB is the 16-bit offset, in a page, of the input buffer. The 8-bit page number is at offset 0Ah in the task BCB.

    4. To access the data, set the CPUPAGE register to the page number that was found. Using the offset from the previous step, access the data at the window segment and new offset. Note that if the input buffer crosses a page boundary in co-processor adapter storage, the co-processor adapter CPUPAGE register must be updated when the boundary is crossed while reading the data.

    The buffer from which the co-processor adapter task receives data and to which the system unit program writes data is called the "output buffer." To find out where to write data to a co-processor adapter task, do the following:

    1. Find out if the output buffer is busy. If it is busy, you cannot write data to the task's output buffer. Set the CPUPAGE register in the co-processor adapter to 0. This register is at an offset of 5 from the base I/O address. It is set by writing a value of 00h to the base address plus 5; this is an 8-bit I/O port. Using the window segment and an offset of 047Ch plus the task number, read in the primary status byte. If the output buffer busy bit (bit 6) is on, you cannot write the data.

    2. Locate the start of the BCB array by examining the BCB pointer at offset 045Ah in co-processor adapter page 0. This word location contains the offset, in page 0, of the BCB array. There is one task BCB for each possible task on the co-processor adapter. To find the correct task BCB, shift the task number left 4 bits and add the result to the value from offset 045Ah. This results in the offset of the task BCB for that task within page 0. All BCBs are in page 0 of co-processor adapter storage.

    3. The 16-bit length of the output buffer is at offset 0Bh in the task BCB. At offset 0Dh in the task BCB is the 16-bit offset, in a page, of the output buffer. The 8-bit page number is at offset 0Fh in the task BCB.

    4. To access the buffer, set the CPUPAGE register to the page number that was found. Using the offset, from the previous step, write the data at the window segment and new offset. Note that if the output buffer crosses a page boundary in co-processor adapter storage, the co-processor adapter CPUPAGE register must be updated when the boundary is crossed while writing the data.

    Handling Co-Processor Adapter Interrupts

    The following functions can be performed by either the interrupt handler that is a part of the IBM Realtime Interface Co-Processor DOS Support product, or the device driver that is a part of the IBM Realtime Interface Co-Processor OS/2 Support product. The following discussion assumes that neither support product is being used.

    Before the co-processor adapter can interrupt the system unit, the co-processor adapter command register bit 4 must be set to 1. Once this bit is set, the co-processor adapter may generate interrupts to the system unit. The co-processor adapter may operate without interrupting the system unit. This type of operation would be called "polled mode." To operate in polled mode, do not set co-processor adapter command register bit 4 to 1. Polled mode operation is slower than interrupt mode; therefore, interrupt mode is recommended.

    Before enabling the co-processor adapter interrupts, the interrupt level of the co-processor adapter must be determined. To determine the co-processor adapter interrupt level, do the following: set the co-processor adapter pointer register to 8 and perform an I/O input from the data register. A value of 0-7 is returned. Use the following chart to decode the interrupt level of the co-processor adapter from the returned value:

     Value     Interrupt Level (Decimal Value)
     00h       3
     01h       4
     02h       7
     03h       2 (if 8086- or 8088-based system unit) or
               9 (if 80286- or 80386-based system unit)
     04h       10
     05h       11
     06h       12
     07h       15
    

    Interrupt levels 9 and higher are valid only for 80286- or 80386-based system units, with the exception that interrupt level 15 should not be used for a co-processor adapter in a PS/2.

    Once the co-processor adapter interrupt level is known, the correct vector must be acquired from the system unit operating system.

    The system unit has one or more programmable interrupt controller (PIC) chips to handle I/O interrupts. System units that are 8086-based or 8088-based have one PIC; system units that are 80286-based or 80386-based have two PICs. See the appropriate system unit technical reference manual for details on programming the PICs. The system unit usually masks off PIC interrupt levels that are not known to be used. To ensure that the interrupt level for the co-processor adapter is active, check the interrupt masks in the PICs and, if the interrupt level is masked off, mask it on.

    The co-processor adapter interrupts the system unit by a task or a PROM service writing the co-processor adapter task register from the co-processor adapter side. The value written in this register is the co-processor adapter task number that is interrupting the system unit. Writing of this register causes an interrupt to be generated to the system unit.

    When the interrupt occurs, assuming that the vector has been acquired, the system unit vectors into the program to which the interrupt vector points. The program should scan the co-processor adapter on that level by reading the command register from each co-processor adapter until one is found with the interrupt pending bit set. The task register for this co-processor adapter should then be read. The value read must be remembered, because the register is cleared at the time it was read. After finding the co-processor adapter that has interrupted, write FFh to location 0441h in page 0 of that co-processor adapter. This notifies the co-processor adapter that the system unit has accepted the interrupt.

    When the interrupt processing is complete, two things must be done to allow any more interrupts from the co-processor adapter or any other type of attachment on the same level as the co-processor adapter. First, the PIC(s) on the system unit must receive an "end-of-Interrupt" (EOI). Note that the 82086-based and 80386-based system units, such as the IBM 7531 Industrial Computer, have two PIC chips; if the interrupt level is 9 or higher, both PICs must receive the EOI.

    In OS/2, the operating system provides a call for issuing the EOI on a given interrupt level. For the Realtime Interface Co-Processor, the Realtime Interface Co-Processor Multiport, and the Multiport Adapter, Model 2, once the PIC has been issued an EOI, a global reset must be performed on the interrupt level on which the interrupt occurred. For the Realtime Interface Co-Processor Multiport/2 and the Portmaster Adapter/A, no global reset is necessary. To issue the global reset, an I/O output is issued to a specific I/O address. The I/O address written is determined by the level that interrupted, as follows:

     Interrupt Level       Global Reset Address
       2                     02F2h
       3                     02F3h
       4                     02F4h
       7                     02F7h
       9                     02F2h
      10                     06F2h
      11                     06F3h
      12                     06F4h
      15                     06F7h
    

    Last modified: March 25, 1999