Firmware Technical Reference
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.
Part 1. Volume I - System Interfaces and Functions
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/2The following terms, DENOTED BY A DOUBLE ASTERISK (**), used in this publication, are trademarks of other companies as follows:
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.
This manual:
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.
The IBM Realtime Interface Co-Processor Firmware Technical Reference is organized into three volumes.
Volume I contains the following:
Introduces the co-processor adapter software architecture.
References functions performed by software in the system unit for support of the co-processor adapter. It describes system initialization, system unit program initialization, system unit program to Realtime Control Microcode communication, and asynchronous error handling.
Describes modules available to system unit programs that request various modes and controls from the co-processor adapter.
Describes operations that must be performed to communicate with tasks on the co-processor adapter. These include co-processor adapter setup, interrupt handling, sending commands to a task, task data transfer, and loading and starting the Realtime Control Microcode.
Volume II contains the following:
Describes functions available to tasks on the co-processor adapter. These include system unit interrupts, task management, task initialization, and programming. These functions cause a dispatch cycle to occur.
Describes functions available to tasks executing on the co-processor. These functions are designed for use by interrupt handlers because interrupt handlers are prevented from using Supervisor Calls (SVCs). These services do not cause a dispatch cycle to occur.
Describes modules available to tasks and the Realtime Control Microcode residing in the co-processor adapter's programmable ROM (PROM). These modules provide services such as SCC port and CIO port initialization and programming, DMA initialization, and ASCII/EBCDIC translation. These functions do not cause a dispatch cycle to occur.
Provides tables of the hardware initialization upon exit from ROS Power On.
Describes modules available to tasks and the Realtime Control Microcode. These modules provide diagnostic testing at power-on time and are not dependent on the Realtime Control Microcode. They include tests and checks on RAM storage, timers, DMAs, interrupt handlers, and interfaces. These functions do not cause a dispatch cycle to occur.
Volume III contains the following:
Describes functions available to tasks on the Realtime Interface Co-Processor, the Realtime Interface Co-Processor Multiport, and the Realtime Interface Co-Processor Multiport/2 adapters. These functions include resource management, task management and services, task communications with the system unit, error handling, and interrupt handling.
Provides the link between an interrupt vector number code and the procedures assigned to service interrupts associated with that vector number code for the Realtime Interface Co-processor, the Realtime Interface Co-Processor Multiport, and the Realtime Interface Co-Processor Multiport/2 adapters.
Describes functions available to tasks on the Realtime Interface Co-Processor Portmaster Adapter/A and the Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters. These functions include resource management, task management and services, task communications with the system unit, error handling, and interrupt handling.
Provides the link between an interrupt vector number code and the procedures assigned to service interrupts associated with that vector number code for the Realtime Interface Co-Processor Portmaster Adapter/A and the Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.
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.
You may need to use one or more of the following publications for reference with this manual:
Volume I contains the following:
Introduces the co-processor adapter software architecture.
References functions performed by software in the system unit for support of the co-processor adapter. It describes system initialization, system unit program initialization, system unit program to Realtime Control Microcode communication, and asynchronous error handling.
Describes modules available to system unit programs that request various modes and controls from the co-processor adapter.
Describes operations that must be performed to communicate with tasks on the co-processor adapter. These include co-processor adapter setup, interrupt handling, sending commands to a task, task data transfer, and loading and starting the Realtime Control Microcode.
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:
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.
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.
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:
A task that is executing is in actual control of the co-processor adapter.
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).
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.
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.
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.
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.
A suspended task is not on the dispatch queue. The only way to get it back in the queue is to first RESUME it.
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 |
+-------------------+
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.
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:
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 communication is accomplished through the Realtime Control Microcode in the following ways:
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:
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:
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:
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 2These parameters can be passed together and in any order (that is, they are not mutually exclusive and not order dependent).
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.
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:
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:
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:
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 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:
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.
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.
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:
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.
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.
The Dump Formatter Facility formats the output from the Online Dump Facility.
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.
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.
The OS/2 Support Device Driver performs the same functions as the DOS Support Interrupt Handler. The Device Driver file is called ICARICIO.SYS.
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.
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.
The Dump Formatter Facility formats the output from the Online Dump Facility.
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 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.
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.
The following topics are discussed in this section:
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:
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
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
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
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
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 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.
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.
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 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) |
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.
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.
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.
A description of each system unit to co-processor adapter command is provided in the remainder of this chapter.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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:
Each of these operations is described in the following sections.
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.
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.
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.
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:
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:
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:
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