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.
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:
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 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.
Supervisor Calls (SVCs) are requested through the Realtime Control Microcode to perform functions for application tasks executing on the co-processor adapter. SVCs may be called from a task's mainline code and from software interrupt handlers.
For specific details relating to a particular SVC, refer to the list on the following pages and the SVCs by name within this chapter.
An SVC is invoked via a call to interrupt vector INT 56h with the requested SVC number in register AH. Register AH and other registers are used to pass parameters to the SVC handler, which invokes the appropriate module to perform the requested function. All user registers (except register AL on error detection) are preserved unless specified by the particular SVC.
+--------------------------------------------------+ | List of Supervisor Calls | +-----+------+---------+---------------------------+ | Int | AH | Name | Function | | No. | Reg | | | +-----+------+---------+---------------------------+ | 56h | 37h | INTPC | Interrupts the | | | | | system unit | +-----+------+---------+---------------------------+ | 56h | 38h | UNLOAD | Unloads specified task | +-----+------+---------+---------------------------+ | 56h | 39h | BUILD | Simulates a task | | | | | load from the | | | | | system unit | +-----+------+---------+---------------------------+ | 56h | 3Ah | START | Starts the specified task | +-----+------+---------+---------------------------+ | 56h | 3Bh | STOP | Stops the specified task | +-----+------+---------+---------------------------+ | 56h | 3Ch | WAIT | Places requesting task | | | | | into an idle or | | | | | "wait" state | +-----+------+---------+---------------------------+ | 56h | 3Dh | SUSPEND | Suspends task | +-----+------+---------+---------------------------+ | 56h | 3Eh | RESUME | Cancels the suspended | | | | | status of a task | +-----+------+---------+---------------------------+ | 56h | 3Fh | POST | Places the task on the | | | | | dispatch queue | +-----+------+---------+---------------------------+ | 56h | 40h | ASAP | Causes a dispatch | | | | | cycle to occur | +-----+------+---------+---------------------------+ | 56h | 41h | STAYRES | Terminates requesting | | | | | task; task remains | | | | | resident | +-----+------+---------+---------------------------+ | 56h | 42h | READVEC | Reads an interrupt vector | +-----+------+---------+---------------------------+ | 56h | 43h | TIMERP | Starts a periodic | | | | | software timer | +-----+------+---------+---------------------------+ | 56h | 44h | TIMER | Starts a software timer | +-----+------+---------+---------------------------+ | 56h | 45h | CANCEL | Cancels the specified | | | | | software timer | +-----+------+---------+---------------------------+ | 56h | 46h | ALLOC | Allocates one of a | | | | | co-processor adapter's | | | | | resources such as | | | | | an interrupt vector, | | | | | storage block, DMA | | | | | channel, communication | | | | | port, queue, or hard- | | | | | ware or software timer | +-----+------+---------+---------------------------+ | 56h | 47h | RETURN | Deallocates a co-processor| | | | | adapter resource | +-----+------+---------+---------------------------+ | 56h | 48h | INITCOMP| Tells the Realtime | | | | | Control Microcode that | | | | | initialization of the | | | | | task is complete | +-----+------+---------+---------------------------+ | 56h | 49h | QFREEST | Queries the largest | | | | | available free | | | | | storage size | +-----+------+---------+---------------------------+
The Realtime Control Microcode sets the carry flag on and sets register AL to an error code when an error is detected in a supervisor call. The Realtime Control Microcode returns to the requesting task when the first error condition is found. Other error conditions may exist; therefore, the call parameters should be checked before the SVC is executed again. The SVC error codes set by the Realtime Control Microcode are as follows.
+--------------------------------------------------+ | List of SVC Error Codes | +------+-------------------------------------------+ | AL | Meaning | | Code | | +------+-------------------------------------------+ | 01h | Non-valid SVC/SVI number | | 02h | Unused | | 03h | Unused | | 04h | Interface board not present | | 05h | Access denied | | 06h | Port interface mismatch | | 07h | Communications chip mismatch | | 08h | Insufficient storage | | 09h | Interrupt busy | | 0Ah | No response from system unit | | 0Bh | Interrupt rejected | | 0Ch | Requested action was already performed | | 0Dh | No resource available | | 0Eh | Unknown EMM handle | | 0Fh | EMM logical page number out of range | | 10h | Page Frame page number out of range | | 11h | Physical address mapped, but unallocated | | 12h | Address out of range | | 13h | Non-valid data | | 14h | Non-valid task number | | 15h | Non-valid timer number | | 16h | Non-valid queue number | | 17h | Name not found | | 18h | Non-valid port number/duplicate name | | 19h | Device number not available/clocking | | | option selected in hardware | | 1Ah | Insufficient expanded memory pages | | 1Bh | Stack overflow/underflow | | 1Ch | Requested hook access not available | | 1Dh | Task suspended by Realtime Control | | | Microcode - cannot be resumed | | 1Eh | Unused | | 1Fh | Unused | +------+-------------------------------------------+
A description of each supervisor call is provided in the remainder of this chapter.
Interrupts the system unit.
INVOCATION: INT 56h, AH = 37h
----------------------------------------------------
FUNCTION:
This SVC generates an interrupt to the system unit from the requesting task. There are five options with this SVC. The entry parameter (AL register) to select these options is bit-sensitive; therefore, tasks can combine options into one call.
Entry Parameters
INT 56h
AH = 37h
AL = xxxA BCDE
where: A = 1, Request system restart of the system unit
B = 1, infinite retry on interrupt presentation
and response
B = 0, CX = maximum interrupt retry count
(must be greater than 0)
C = 1, "output buffer busy" is reset to 0
D = 1, "busy" is reset to 0
E = 1, task is "waited" after interrupt
x = not used
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command interrupt
handler
09h Interrupt busy -The retry count (number
of attempts) has expired
and the interrupt cannot
be presented to the
system unit. Due to prior
interrupt pending.
0Ah No response from -No system unit response
system unit to the interrupt was
received, and the retry
count has expired
13h Non-valid data -Retry count specified
is not valid (CX = 0)
Example Call
MOV AH,37h ;interrupt system unit
; SVC
MOV AL,0Fh ;
;***********************************************************
;* With 0Fh in AL, the following options are turned on: *
;* Option 2: Infinite retry on interrupt presentation *
;* and response. *
;* Option 3: Output buffer busy is reset to 0. *
;* Option 4: Busy bit is reset to 0 in the primary status *
;* bit of the IB after the interrupt is raised. *
;* Option 5: Task is waited after SVC. If posted flag is *
;* not 0, wait does not occur. *
;***********************************************************
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error AL = error code
;Get here after next post
Unloads specified task.
INVOCATION: INT 56h, AH = 38h
----------------------------------------------------
FUNCTION:
The SVC unloads the specified task from the co-processor adapter storage. If the task is not already stopped, it is stopped as described in the Stop SVC. 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. If any errors are detected, the service is not performed.
Entry Parameters
INT 56h AH = 38h AL = Task number to be unloaded
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
--------------------------------------------------------------
AL Code Meaning Causes
--------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called from
an I/O interrupt handler
or command interrupt
handler
-Task is permanent
14h Non-valid task number -Specified task is not
loaded or is out of range
Example Call
MOV AH,38h ;unload task SVC
MOV AL,01h ;unload task number 1
INT 56h ;interrupt Realtime
Control Microcode
JC ERROR_HAN ;if error, AL = error code
Simulates a task load from the system unit.
INVOCATION: INT 56h, AH = 39h
----------------------------------------------------
FUNCTION:
This SVC is the mechanism that a co-processor adapter task uses to create another task on the co-processor adapter.
The task that issues this SVC becomes the parent task. When a task builds another task, the building task is considered to be a parent task and the task that is built is the child task. A child task may not build a task. A task can build another task without the parent/child relationship if the built task is in storage that was acquired by the building task. In this case, the BX register must point to the offset address in the building task header, which is the storage resource block for the acquired storage in which the task to be built resides; otherwise, BX must be 0.
Restrictions:
The size in the built task's header must be the same size of the storage block in which the task is to be built. If this size is incorrect and the built task is subsequently unloaded, the incorrect amount of storage is returned to the free storage pool. The Realtime Control Microcode cannot detect this error because the built task does not have to reside in storage at Build time, only at Start time. This restriction applies only if no parent/child relationship exists (BX not equal to 0). Tasks cannot be built in expanded memory.
Entry Parameters
INT 56h
AH = 39h
AL = Task number to build
ES = Segment of the built task's task header
BX = 0 indicates task that is built is a child task
BX = Address of the storage resource block in the parent
task that describes the storage in which the built
task resides. This storage resource block (the
control block used to allocate the storage) is removed
from the building task's resource block chain and
becomes the resident storage of the built task. The
pointer to the storage resource block is used to
acquire the storage in which the peer task resides.
The built task is not a child task of the building
task in this case.
DX = Offset of the built task's task header
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
-Child task attempted to
build a task
13h Non-valid data -BX register is not 0,
and does not point to a
valid storage resource
block
-DX is not on a paragraph
boundary
14h Non-valid task number -Task is out of range
-Task is already loaded
Example Call
MOV AH,39h ;build task SVC MOV AL,02h ;build task number 2 MOV BX,CS ;COM file implementation MOV ES,BX ;ES = CS XOR BX,BX ;BX = 0, build as child task MOV DX,OFFSET TSK2 ;header of task 2 INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Starts the specified task.
INVOCATION: INT 56h, AH = 3Ah
----------------------------------------------------
FUNCTION:
This SVC starts the specified task. A task is started by building a Task Control Block (TCB) from the task header. The task must have been previously loaded from the system unit or built by the Build SVC. The Start command causes the task to be entered at its initial entry point.
If the task is already started, no operation is performed.
When the task is entered the first time, the task's registers are set up as follows:
Register Contents
-------- --------
AX Undetermined
BX Undetermined
CX Undetermined
DX Undetermined
DI Undetermined
SI Undetermined
BP Undetermined
SP Stack Pointer value from task header
logically ANDed with FFFFEh
CS Initial segment from task header
DS Data segment value from the task header
ES Segment of the task header
SS Stack segment value from the task header
IP Initial offset value from the task header
Flags Carry = 0
Parity = 0
Auxiliary carry = 0
Zero = 0
Sign = 0
Trap = 0
Interrupt = 1 (enabled)
Direction = 0
Overflow = 0
Entry Parameters
INT 56h AH = 3Ah AL = Task number to start
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
0Ch Requested action -Task is already started
already performed
13h Non-valid data (from -Task size is less than
task header) 28 bytes or greater
than 1Mb
-Task priority is greater
than MAXPRI or equal to
0
-Task number in header
does not match the
requested task number
-Resource Block pointer
is not 0
-Byte 5 of the task
header is not 0
-Task Debug flag in the
task header is non-zero
This flag is reserved for
future use but must be
reset to 0
14h Non-valid task -Task has not been loaded
number -Task is out of range
Example Call
MOV AH,3Ah ;start task SVC MOV AL,01h ;start task number 1 INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Stops the specified task.
INVOCATION: INT 56h, AH = 3Bh
----------------------------------------------------
FUNCTION:
This SVC stops the specified task. All resources except the storage in which the task resides are returned to the Realtime Control Microcode. If the task is already stopped, the SVC performs no operation. A stopped task may be restarted by the Start SVC or Start command from the system unit. The effect of Stop puts a task into the loaded state and removes its TCB from the Realtime Control Microcode storage area. All child tasks of the specified task are unloaded.
Entry Parameters
INT 56h AH = 3Bh AL = Task number to stop
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
-Task is permanent
0Ch Requested action -Task is already stopped
already performed
14h Non-valid task number -Task is out of range
-Task is not loaded
Example Call
MOV AH,3Bh ;stop task SVC MOV AL,01h ;stop task number 1 INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Puts a task in an idle or wait state.
INVOCATION: INT 56h, AH = 3Ch
----------------------------------------------------
FUNCTION:
This SVC puts a task in an idle or wait state. It may be made active by a post SVC or POSTI service interrupt from an interrupt handler or another task. While idle, it may only service interrupts.
If the task's posted flag (in its TCB) is set, the Wait call will return immediately. The task's posted flag must be clear for the Wait SVC to put the task in an idle state.
Entry Parameters
INT 56h AH = 3Ch
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
Example Call
MOV AH,3Ch ;wait task SVC INT 56h ;interrupt Realtime Control Microcode ;Get here when posted JC ERROR_HAN ;if error, AL = error code
Suspends the specified task.
INVOCATION: INT 56h, AH = 3Dh
----------------------------------------------------
FUNCTION:
The SVC suspends the specified task and the suspended flag in the task's s state byte in the task's TCB is set to 1. If the suspended task is on the dispatch queue, it is removed from the dispatch queue. After a task is suspended, it may be posted. However, this post does not take effect until that task is resumed. To take a task out of the suspended state, it must be resumed.
If the task is already suspended, no operation is performed.
Entry Parameters
INT 56h AH = 3Dh AL = Task number to be suspended
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
0Ch Requested action -Task is already suspended
already performed
14h Non-valid task number -Task is out of range
-Task is not started
Example Call
MOV AH,3Dh ;suspend task SVC MOV AL,01h ;suspend task number 1 INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Cancels the suspended state of a task.
INVOCATION: INT 56h, AH = 3Eh
----------------------------------------------------
FUNCTION:
This SVC cancels the suspended state of a task. If the task was posted when it was suspended or has been posted since it was suspended, the Resume puts the specified task on the dispatch queue. If the task is not suspended, no operation is performed. This SVC does not resume tasks suspended by the Realtime Control Microcode because error conditions exist.
Entry Parameters
INT 56h AH = 3Eh AL = Task number to resume
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
0Ch Requested action -Task is not suspended
already performed
14h Non-valid task number -Task is out of range
-Task is not started
1Dh Task cannot be -Task was suspended by the
resumed Realtime Control Microcode
Example Call
MOV AH,3Eh ;resume task SVC MOV AL,01h ;resume task number 1 INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Places the task on the dispatch queue.
INVOCATION: INT 56h, AH = 3Fh
----------------------------------------------------
FUNCTION:
This SVC puts the task on the dispatch queue (if it is not suspended). If the task is already posted, only the post code and posted flag in the TCB is changed. If the task is suspended, the post code (PSTCD) is set to the requested value, the posted flag (POSTED) is set to 1, and the queued bit in the state byte (STB) is set, but the task is not put on the dispatch queue until the task is resumed. The posted flag must be reset to 0 by the task for the task to be able to "wait" itself.
Entry Parameters
INT 56h
AH = 3Fh
AL = Task number to post
DX = Post code
The following parameters are optional. This is a recommended
format only.
DH = Task number posting
DL = pppp ABCD
where: A = Posted by the I/O Interrupt Handler
DL = pppp 1000 where p = user-defined post code
B = Posted by timer expiration
DL = pppp p100 where p = user-defined post code
C = Posted by command subroutine
DL = pppp pp10 where p = user-defined post code
D = General post
DL = pppp ppp1 where p = user-defined post code
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
14h Non-valid task number -Target task is not started
-Task is out of range
Example Call
MOV AH,3Fh ;post task SVC
MOV AL,01h ;post task number 1
MOV DX,0AAAh ;post code, optional and
; specific to implementation
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error, AL = error code
Causes a dispatch cycle to occur.
INVOCATION: INT 56h, AH = 40h
----------------------------------------------------
FUNCTION:
This is an SVC in which no operation is performed. It is used to share execution time with other tasks. A task should use this SVC to force a dispatch cycle to occur and allow other tasks to execute. In the event a task does not return control to the Realtime Control Microcode, the Realtime Control Microcode executes a time-slice after 10 milliseconds to force a dispatch cycle to occur.
Entry Parameters
INT 56h AH = 40h
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
Example Call
MOV AH,40h ;asap SVC INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Terminates the task, but the task remains resident.
INVOCATION: INT 56h, AH = 41h
----------------------------------------------------
FUNCTION:
This SVC causes the calling task to be terminated but to remain in storage.
After successful completion of this SVC, this task may not be started, stopped, posted, suspended, resumed, waited, or unloaded. The task has no TCB. A parent or child task may not be terminated with this SVC. The requesting task must not own any user interrupt vectors. This call may be used for installing interrupt handlers. One example would be a time-of-day routine.
Entry Parameters
INT 56h AH = 41h
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
-Attempt made to terminate
a parent or child task
-The requesting task owns a
user-interrupt vector
Example Call
MOV AH,41h ;stay resident SVC INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Reads an interrupt vector.
INVOCATION: INT 56h, AH = 42h
----------------------------------------------------
FUNCTION:
This SVC returns the current doubleword value of an interrupt vector.
Entry Parameters
INT 56h AH = 42h AL = Interrupt vector number to read
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
ES = Segment value of the vector
DX = Offset value of the vector
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called from
an I/O interrupt handler
or command interrupt handler
Example Call
MOV AH,42h ;read vector SVC
MOV AL,0C0h ;read interrupt vector C0h,
; pointer to EBCDIC-to-ASCII
; table
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error, AL = error code
;If here:
; ES = Segment value of the vector
; DX = Offset value of the vector
Starts a periodic software timer.
INVOCATION: INT 56h, AH = 43h
----------------------------------------------------
FUNCTION:
This SVC starts a software timer that automatically restarts itself when it times out. This timer calls the user's timer vector on each time-out. When the timer expires, the supplied vector is called via a FAR CALL. Your task executes a RET FAR at the end of the subroutine. This timer can be cancelled in the same manner as a nonperiodic timer, by using the CANCEL SVC or the CANCELI SVI.
Entry Parameters
INT 56h
AH = 43h
AL = Software timer number
CX = Time period in milliseconds (0001h-FFFFh) in multiples
of 5 milliseconds
Example: 1 = 5 milliseconds
2 = 10 milliseconds
ES = Segment of subroutine to call
DX = Offset of subroutine to call
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command interrupt
handler
-Timer does not belong to
this task.
13h Non-valid data -Timer period is 0
15h Non-valid timer number -Timer number is out of range
-Timer is already running
Example Call
MOV AH,43h ;start periodic software
; timer SVC
MOV AL,01h ;software timer 1
MOV CX,0005h ;time out in 25 milliseconds
MOV BX,CS ;COM file implementation
MOV ES,BX ;ES = CS
MOV DX,OFFSET TIMER_HANDLER ;offset of subroutine,
; specific to implementation
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error, AL = error code
Starts a software timer.
INVOCATION: INT 56h, AH = 44h
----------------------------------------------------
FUNCTION:
This SVC starts a software timer. The parameters are timer number, duration, and a 32-bit vector that receives control when the timer expires. When the timer expires, the supplied vector is called via a CALL FAR. Your task must execute a RET FAR at the end of this section of code. The timer can be cancelled with the CANCEL SVC or the CANCELI SVI.
The duration of one count of the timer is 5 milliseconds.
Entry Parameters
INT 56h AH = 44h AL = Software timer number CX = Duration (0001h to FFFFh) ES = Segment of subroutine to call DX = Offset of subroutine to call
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
-Timer does not belong to
this task
13h Non-valid data -Timer period is 0
15h Non-valid timer number -Timer is out of range
-Timer is already running
Example Call
MOV AH,44h ;start software timer
; SVC
MOV AL,01h ;software timer 1
MOV CX,0001h ;time out in 5 milliseconds
MOV BX,CS ;COM file implementation
MOV ES,BX ;ES = CS
MOV DX,OFFSET TIMER_HANDLER ;offset of subroutine,
; specific to implementation
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error, AL = error code
Cancels the specified software timer.
INVOCATION: INT 56h, AH = 45h
----------------------------------------------------
FUNCTION:
This SVC cancels the specified software timer. If the timer is not running, no operation is performed. This SVC cancels both periodic and nonperiodic software timers.
Entry Parameters
INT 56h AH = 45h AL = Software timer number
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
15h Non-valid timer -Timer is out of range
number
Example Call
MOV AH,45h ;cancel software timer
; SVC
MOV AL,01h ;cancel software timer 1
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error, AL = error code
Allocates one of a co-processor adapter's resources.
INVOCATION: INT 56h, AH = 46h
----------------------------------------------------
FUNCTION:
This SVC allocates one of a co-processor adapter's resources-&dashsuch as an interrupt vector, storage block, communication port, user queue, or hardware or software timer. A pointer to the resource block is passed as a parameter. The resource block is used to specify which resource is requested. Only one resource may be requested at a time. For further details, see
Entry Parameters
INT 56h AH = 46h ES = Segment of resource block DX = Offset of resource block
Note:
The resource block for a given resource type is defined in detail under Refer to , and .
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
04h Interface board -Co-processor has no interface
not present board or the interface board
has non-conformance on-board
ROM
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
-Resource cannot be
allocated
-Attempt is made to allocate
interrupt vector that is used
by the Realtime Control Microcode
or by the hardware
06h Port interface -Port interface type requested
mismatch is not the same as the port
interface type present on the
interface board
07h Communications -Communications chip type
chip mismatch present is not the same as
the Communications chip
type present on the interface
board
08h Insufficient -Insufficient storage for
storage a storage allocation
request
13h Non-valid data -Requesting task number is
not the task in execution
-The resource block segment
is not the requesting
task's task header segment
-Byte 7 of the resource
block is non-zero
-Block descriptor is out
of range
-Non-valid communication port
requested
15h Non-valid timer -The requested timer number
number is greater than MAXTIME
(maximum number of timers)
16h Non-valid queue -The requested queue number
number is greater than MAXQUEUE
(maximum number of queues)
1A Insufficient -Insufficient expanded memory
expanded memory pages for the allocation request
pages
1C Requested access -The service requested is not
not available supported or is disabled
Example Call
MOV AH,46h ;allocate resource SVC
MOV BX,CS ;COM file implementation
MOV ES,BX ;ES = CS
MOV DX,OFFSET RS-232-C_PORT_1 ;offset of resource block,
; specific to implementation
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error, AL = error code
Deallocates a specified resource.
INVOCATION: INT 56h, AH = 47h
----------------------------------------------------
FUNCTION:
This SVC is used to return one resource at a time-&dashsuch as an interrupt vector, storage block, communication port, user queue, or timer to the Realtime Control Microcode's control.
Entry Parameters
INT 56h
AH = 47h
ES = Segment of resource block that describes resource
to be returned.
DX = Offset of resource block that describes resource
to be returned.
Note:
The resource block for a given resource type is defined in detail under , and .
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
0Eh Unknown EMM -Expanded memory handle is
handle not allocated
13h Non-valid data -Resource does not belong
to this task
-Requesting task number is
not the task in execution
-Resource block segment is
not the requesting task's
task header segment
-Block descriptor is out
of range
-The return size is greater
than the block size. This
message is generated when
a task is returning a
partial storage block
-Non-valid communications port
requested
15h Non-valid timer -The requested timer number
number is greater than MAXTIME
(maximum number of timers)
16h Non-valid queue -The requested queue number
number is greater than MAXQUEUE
(maximum number of queues)
Example Call
MOV AH,47h ;return resource SVC
MOV BX,CS ;COM file implementation
MOV ES,BX ;ES = CS
MOV DX,OFFSET RS-232-C_PORT_1 ;offset of resource block,
MOV DX,OFFSET RS-232-C_PORT_1 ;offset of resource block,
; specific to implementation
INT 56h ;interrupt Realtime Control Microcode
JC ERROR_HAN ;if error, AL = error code
Tells the Realtime Control Microcode that initialization of the task is complete.
INVOCATION: INT 56h, AH = 48h
----------------------------------------------------
FUNCTION:
This SVC tells the Realtime Control Microcode that a task has finished its initialization. The initialized state bit is set to 1 in the task's primary status byte in the interface block. This is usually done at the end of the code that was entered by the Start command or Start SVC.
The task may be marked as permanent via this SVC. A permanent status says that this task cannot be stopped or unloaded. If a child task is marked as permanent, the parent task is also assigned a permanent status.
If the task is already initialized, no operation is performed.
Entry Parameters
INT 56h
AH = 48h
AL = 0 indicates task can be unloaded;
non-zero indicates task is to be
marked as permanent
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
Errors
---------------------------------------------------------------
AL Code Meaning Causes
---------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
0Ch Requested action -The Initialize bit in
already performed the task's primary status
Byte in the interface block
is already set to 1
Example Call
MOV AH,48h ;init. complete SVC MOV AL,00h ;task can be unloaded INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code
Gets the largest available free storage size.
INVOCATION: INT 56h, AH = 49h
----------------------------------------------------
FUNCTION:
This SVC returns the pointer to the largest free storage block along with the size of that block and the total amount of free storage.
This service only reports on the storage in base memory, not expanded memory.
Entry Parameters
INT 56h AH = 49h
Exit Parameters
Carry flag = 0 if no error;
1 if error
AL = Unchanged if no error;
error code if error
BX = Segment of largest available storage block
CX = Number of paragraphs in the largest storage block
DX = Total number of free storage paragraphs
Errors
------------------------------------------------------------
AL Code Meaning Causes
------------------------------------------------------------
01h Non-valid SVC number -SVC number out of range
05h Access denied -SVC cannot be called
from an I/O interrupt
handler or command
interrupt handler
Example Call
MOV AH,49h ;query free storage SVC INT 56h ;interrupt Realtime Control Microcode JC ERROR_HAN ;if error, AL = error code ;If here: ; BX = Segment of largest available storage block ; CX = Number of paragraphs in the largest storage block ; DX = Total number of free storage paragraphs
Service interrupts (SVIs) 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. In general, these routines are designed to be used by I/O interrupt handlers because I/O handlers are prevented from using Supervisor Calls (SVCs) to perform these functions. The service interrupts perform many of the same functions as the SVC modules, but do not cause a dispatch cycle to occur.
For specific details relating to a particular SVI, refer to the list on the following pages and the SVIs by name within this chapter.
The service interrupts are accessed via even-numbered interrupts 60h through 74h.
The following tables list each service interrupt along with differences between support provided in Realtime Control Microcode Version 1 and Realtime Control Microcode Version 2.
+------------------------------------------------------------------------+ | List of Service Interrupts | +------+-------+----------------+----------------------------------------+ | Int | AH | | | | No. | Value | Name | Function | +------+-------+----------------+----------------------------------------+ | 60h | --- | SEG2PAG | Translates a segment and offset | | | | | into page and offset | | | | | | | 62h | --- | PAG2SEG | Translates page and offset into | | | | | segment and offset | | | | | | | 64h | --- | POSTI | Places a task on the dispatch queue | | | | | | | 66h | --- | RESUMEI | Cancels the suspended state of a task | | | | | | | 68h | --- | CANCELI | Cancels the specified software timer | | | | | | | 6Ah | --- | RECQUEUE | Gets the pointer to the first | | | | | element in a user queue | | | | | | | 6Ch | --- | ADDQUEUE | Adds an element to a user queue | | | | | | | 72h | 0Ch | PHYSICAL | Operation is identical to the ADDQUEUE| | | | ADDQUEUE | SVI except that it takes the 32-bit | | | | | physical address of an element rather | | | | | than an 80186 logical address. | | | | | | | 6Eh | --- | REMQUEUE | Removes the first element from a | | | | | user queue | | | | | | | 70h | --- | TRANSEG | Translates a segment address into | | | | | an offset from a supplied segment | | | | | address | | | | | | | 72h | 00h | DISABLE | Disables task preemption | | | | PREEMPT | | | | | | | | 72h | 01h | ENABLE | Enables task preemption | | | | PREEMPT | | | | | | | | 72h | 02h | GET TASK IN | Returns the task number of the | | | | EXECUTION | current task in execution | | | | | | | 72h | 0Dh | GET/SET | Used to get/set the system time | | | | SYSTEM TIME | | | | | | | | 72h | 03h | PEER REQUEST | Used to send a peer request to | | | | | another task | | | | | | | 72h | 10h | GET CALLABLE | Return the addresses of selected | | | | ADDRESSES | Realtime Control Microcode routines | | | | | | | 72h | 0Eh | GET INTERRUPT | Returns the current depth of hardware | | | | COUNT | interrupts | | | | | | | 72h | 0Fh | GET RESOURCE | Return a pointer to a structure | | | | COUNT | containing a list of hardware and | | | | | software resources | | | | | | | 72h | 11h | GET NEXT | Accepts as input a hardware or | | | | AVAILABLE | software resource type | | | | RESOURCE | | | | | | | | 72h | 04h | GET PAGE | Used to get the logical segment | | | | FRAME SEGMENT | address and number of pages in the | | | | ADDRESS | expanded memory page frame | | | | | | | 72h | 05h | GET | Returns the number of unallocated | | | | UNALLOCATED | pages and the total number of | | | | PAGE COUNT | expanded memory pages | | | | | | | 72h | 06h | MAP/UNMAP EMM | Maps or unmaps logical expanded | | | | HANDLE PAGES | memory pages to a page frame page | | | | | | | 72h | 07h | MAP/UNMAP | Maps or unmaps physical expanded | | | | PHYSICAL | memory pages to a page frame page | | | | MEMORY | | | | | | | | 72h | 08h | EMM HANDLE TO | Used to convert an EMM handle, logical| | | | PHYSICAL | page number, and offset to a 32-bit | | | | ADDRESS | physical address | | | | | | | 72h | 09h | EMM HANDLE TO | Used to convert a EMM handle, | | | | PAGE OFFSET | logical page number, and offset to a | | | | ADDRESS | 32-bit page offset address | | | | | | | 72h | 0Ah | PUSH PAGE MAP | Saves the contents of the page | | | | | mapping registers for the entire page | | | | | frame on the stack | | | | | | | 72h | 0Bh | POP PAGE | Used to restore the expanded memory | | | | MAP | page frame mapping previously saved | | | | | by a PUSH PAGE MAP call | | | | | | | 74h | | LCLS | Logical control line services: | | | 00h | | HALF RATE SELECT CONTROL | | | 01h | | TRANSMIT CONTROL | | | 02h | | RTS/DTR CONTROL | | | 03h | | QUERY EXTERNAL/STATUS INPUTS | | | 04h | | EXTERNAL/STATUS INTERRUPT CONTROL | | | 05h | | CLEAR EXTERNAL/STATUS INTERRUPT | | | 06h | | READ/WRITE CIO BITS | | | 07h | | CLOCKING OPTION CONTROL | +------+-------+----------------+---------------------------------------+
+----------------------------------------------------------------+ | Support Differences for Service Interrupts | +---------------+---------------+-----------------+--------------+ | Name | Modified for | Supported Only | Supported | | | Realtime | in Realtime | Only on | | | Control | Control | Portmaster | | | Microcode 2.x | Microcode 2.x | Adapter/A | +---------------+---------------+-----------------+--------------