Trailing-Edge
-
PDP-10 Archives
-
QT020_T20_4.1_6.1_SWSKIT_851021
-
swskit-documentation/sca-info.memos
There are 2 other files named sca-info.memos in the archive. Click here to see a list.
This file contains descriptions of the Systems Communications Architecture
protocol used to communicate over the CI hardware bus.
THIS FILE CONTAINS:
o The Corporate SCA Specification (SCA-CORP-SPEC.MEM)
o The LSG SCA Functional Specification (SCA.FUNCTIONAL-SPECIFICATION)
o SCA Design Specification for TOPS-20 (SCA-DESIGN.SPECIFICATION)
o SCA Design Notes (SCA-DESIGN-NOTES.TXT)
o More Design Notes (NEW-SCA-DESIGN-NOTES.TXT)
o Description of the SCS JSYS (SCS-JSYS.MEM)
o SCA Table Descriptions (SCA-TABLES.TXT)
o SCA Tester Description (SCSTST.MEM)
-------------------
SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL Page 1
File: SCA.MEM
Date: 29-March-1983
Author: William Strecker
Abstract:
This document describes a communications architecture for building
clusters of computer systems. Included are message formats,
protocols, and implementation independent interface models.
Revision: Description Author Date
0 Outline Strecker 08-Dec-80
1 Definitions Strecker 09-Jan-81
in PASCAL
2 Public Review Strecker 09-Feb-81
3 Path Blocks, H. Levy 10-Dec-81
Disconnect,
and Updates
4 Disconnect H. Levy 20-Jul-82
Changes
5 Updates Darrell Duffy 5-Oct-82
6 Minor Updates Darrell Duffy 29-Mar-83
SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL Page 2
CHAPTER 1 INTRODUCTION
CHAPTER 2 SCA TOPOLOGICAL NOTATION
2.1 NETWORK . . . . . . . . . . . . . . . . . . . . . 2-1
2.2 SCA CLUSTER . . . . . . . . . . . . . . . . . . . 2-1
2.3 COMMMUNICATIONS SERVICE . . . . . . . . . . . . . 2-1
2.4 SYSTEM ADDRESS . . . . . . . . . . . . . . . . . . 2-1
2.5 PORT . . . . . . . . . . . . . . . . . . . . . . . 2-1
2.6 PORT DRIVER . . . . . . . . . . . . . . . . . . . 2-2
2.7 INTERCONNECT . . . . . . . . . . . . . . . . . . . 2-2
2.8 POINT-TO-POINT INTERCONNECT . . . . . . . . . . . 2-2
2.9 MULTIACCESS INTERCONNECT . . . . . . . . . . . . . 2-2
2.10 PORT ADDRESS . . . . . . . . . . . . . . . . . . . 2-2
CHAPTER 3 SCA TOPOLOGY
CHAPTER 4 SCA LAYERING
CHAPTER 5 SYSAP-SCS INTERFACE NOTATION
5.1 PROCESS . . . . . . . . . . . . . . . . . . . . . 5-1
5.2 PROCESS NAME . . . . . . . . . . . . . . . . . . . 5-1
5.3 DIRECTORY . . . . . . . . . . . . . . . . . . . . 5-1
5.4 SYSTEM LIST . . . . . . . . . . . . . . . . . . . 5-1
5.5 SYSTEM BLOCK . . . . . . . . . . . . . . . . . . . 5-1
5.6 PATH BLOCK . . . . . . . . . . . . . . . . . . . . 5-1
5.7 CONNECTION . . . . . . . . . . . . . . . . . . . . 5-2
5.8 CONNECTION BLOCK . . . . . . . . . . . . . . . . . 5-2
5.9 CONNECT ID . . . . . . . . . . . . . . . . . . . . 5-2
5.10 DATAGRAM COMMUNICATION SERVICE . . . . . . . . . . 5-2
5.11 DATAGRAM BUFFER . . . . . . . . . . . . . . . . . 5-2
5.12 SEQUENTIAL MESSAGE COMMUNICATIONS SERVICE . . . . 5-2
5.13 MESSAGE BUFFER . . . . . . . . . . . . . . . . . . 5-3
5.14 QUEUED BUFFER . . . . . . . . . . . . . . . . . . 5-3
5.15 BLOCK DATA COMMUNICATIONS SERVICE . . . . . . . . 5-3
5.16 NAMED BUFFER . . . . . . . . . . . . . . . . . . . 5-3
5.17 FLOW CONTROL . . . . . . . . . . . . . . . . . . . 5-3
5.18 CREDIT . . . . . . . . . . . . . . . . . . . . . . 5-3
CHAPTER 6 SYSAP-SCS INTERFACE
6.1 TYPE DEFINITIONS . . . . . . . . . . . . . . . . . 6-2
6.2 CONFIGURATION SERVICES . . . . . . . . . . . . . . 6-5
6.2.1 System Configuration . . . . . . . . . . . . . . 6-5
6.2.2 Path Configuration . . . . . . . . . . . . . . . 6-6
6.3 CONNECTION MANAGEMENT SERVICE . . . . . . . . . . 6-8
6.3.1 Connect . . . . . . . . . . . . . . . . . . . . 6-9
6.3.2 Listen . . . . . . . . . . . . . . . . . . . . 6-10
6.3.3 Accept . . . . . . . . . . . . . . . . . . . . 6-11
SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL Page 3
6.3.4 Reject . . . . . . . . . . . . . . . . . . . . 6-11
6.3.5 Disconnect . . . . . . . . . . . . . . . . . . 6-12
6.3.6 Connect State Poll . . . . . . . . . . . . . . 6-13
6.4 DATAGRAM SERVICE . . . . . . . . . . . . . . . . 6-14
6.4.1 Send Datagram . . . . . . . . . . . . . . . . 6-14
6.4.2 Send Datagram Poll . . . . . . . . . . . . . . 6-15
6.4.3 Receive Datagram . . . . . . . . . . . . . . . 6-15
6.4.4 Receive Datagram Poll . . . . . . . . . . . . 6-16
6.4.5 Cancel Receive Datagram . . . . . . . . . . . 6-16
6.5 SEQUENTIAL MESSAGE SERVICE . . . . . . . . . . . 6-17
6.5.1 Send Message . . . . . . . . . . . . . . . . . 6-18
6.5.2 Send Message Poll . . . . . . . . . . . . . . 6-18
6.5.3 Receive Message . . . . . . . . . . . . . . . 6-19
6.5.4 Receive Message Poll . . . . . . . . . . . . . 6-19
6.5.5 Cancel Receive Message . . . . . . . . . . . . 6-20
6.5.6 Cancel Receive Message Poll . . . . . . . . . 6-20
6.6 BLOCK DATA SERVICE . . . . . . . . . . . . . . . 6-21
6.6.1 Map Buffer . . . . . . . . . . . . . . . . . . 6-21
6.6.2 Unmap Buffer . . . . . . . . . . . . . . . . . 6-22
6.6.3 Read . . . . . . . . . . . . . . . . . . . . . 6-22
6.6.4 Read Poll . . . . . . . . . . . . . . . . . . 6-23
6.6.5 Write . . . . . . . . . . . . . . . . . . . . 6-24
6.6.6 Write Poll . . . . . . . . . . . . . . . . . . 6-25
CHAPTER 7 SCS-PPD INTERFACE
7.1 DATAGRAM SERVICE . . . . . . . . . . . . . . . . . 7-1
7.1.1 Send Datagram . . . . . . . . . . . . . . . . . 7-1
7.1.2 Receive Datagram . . . . . . . . . . . . . . . . 7-2
7.1.3 Return Datagram Buffer . . . . . . . . . . . . . 7-2
7.2 VIRTUAL CIRCUIT SERVICE . . . . . . . . . . . . . 7-3
7.2.1 Start Virtual Circuit . . . . . . . . . . . . . 7-3
7.3 MESSAGE SERVICE . . . . . . . . . . . . . . . . . 7-4
7.3.1 Send Message . . . . . . . . . . . . . . . . . . 7-4
7.3.2 Receive Message . . . . . . . . . . . . . . . . 7-4
7.3.3 Return Message Buffer . . . . . . . . . . . . . 7-4
7.4 BLOCK DATA SERVICE . . . . . . . . . . . . . . . . 7-5
7.4.1 Send Data . . . . . . . . . . . . . . . . . . . 7-5
7.4.2 Request Data . . . . . . . . . . . . . . . . . . 7-6
7.5 RESPONSES . . . . . . . . . . . . . . . . . . . . 7-7
CHAPTER 8 SCS MESSAGES AND DATAGRAMS
8.1 TYPES . . . . . . . . . . . . . . . . . . . . . . 8-1
8.2 SCS CONTROL MESSAGES . . . . . . . . . . . . . . . 8-3
8.2.1 Connect Request . . . . . . . . . . . . . . . . 8-3
8.2.2 Connect Response . . . . . . . . . . . . . . . . 8-4
8.2.3 Accept Request . . . . . . . . . . . . . . . . . 8-5
8.2.4 Accept Response . . . . . . . . . . . . . . . . 8-6
8.2.5 Reject Request . . . . . . . . . . . . . . . . . 8-7
8.2.6 Reject Response . . . . . . . . . . . . . . . . 8-8
8.2.7 Disconnect Request . . . . . . . . . . . . . . . 8-9
8.2.8 Disconnect Response . . . . . . . . . . . . . 8-10
SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL Page 4
8.2.9 Credit Request . . . . . . . . . . . . . . . . 8-11
8.2.10 Credit Response . . . . . . . . . . . . . . . 8-12
8.3 APPLICATION MESSAGE . . . . . . . . . . . . . . 8-13
8.4 APPLICATION DATAGRAM . . . . . . . . . . . . . . 8-14
CHAPTER 9 SCS OPERATION
9.1 RELATION TO PPD VIRTUAL CIRCUIT . . . . . . . . . 9-1
9.2 SCS PROTOCOL VERSION RESOLUTION . . . . . . . . . 9-1
9.3 SCS CONTROL MESSAGE FLOW CONTROL . . . . . . . . . 9-1
9.4 SCS OPERATION DESCRIPTION . . . . . . . . . . . . 9-3
9.5 TYPE, VARIABLE , FUNCTION, AND PROCEDURE
DEFINITIONS . . . . . . . . . . . . . . . . . . . 9-5
9.6 CONFIGURATION SERVICE . . . . . . . . . . . . . 9-10
9.6.1 System Block . . . . . . . . . . . . . . . . . 9-10
9.6.2 Path Block . . . . . . . . . . . . . . . . . . 9-12
9.6.3 Configuration Services . . . . . . . . . . . . 9-13
9.7 CONNECTION MANAGEMENT SERVICE . . . . . . . . . 9-15
9.7.1 Connection Block . . . . . . . . . . . . . . . 9-15
9.7.2 Connection States . . . . . . . . . . . . . . 9-19
9.7.3 Connect . . . . . . . . . . . . . . . . . . . 9-21
9.7.4 Listen . . . . . . . . . . . . . . . . . . . . 9-22
9.7.5 Accept . . . . . . . . . . . . . . . . . . . . 9-22
9.7.6 Reject . . . . . . . . . . . . . . . . . . . . 9-23
9.7.7 Disconnect . . . . . . . . . . . . . . . . . . 9-23
9.7.8 State Poll . . . . . . . . . . . . . . . . . . 9-24
9.8 DATAGRAM SERVICE . . . . . . . . . . . . . . . . 9-25
9.8.1 Send Datagram . . . . . . . . . . . . . . . . 9-25
9.8.2 Send Datagram Poll . . . . . . . . . . . . . . 9-25
9.8.3 Receive Datagram . . . . . . . . . . . . . . . 9-26
9.8.4 Receive Datagram Poll . . . . . . . . . . . . 9-26
9.8.5 Cancel Receive Datagram . . . . . . . . . . . 9-27
9.9 SEQUENTIAL MESSAGE SERVICE . . . . . . . . . . . 9-28
9.9.1 Send Message . . . . . . . . . . . . . . . . . 9-28
9.9.2 Send Message Poll . . . . . . . . . . . . . . 9-29
9.9.3 Receive Message . . . . . . . . . . . . . . . 9-29
9.9.4 Receive Message Poll . . . . . . . . . . . . . 9-30
9.9.5 Cancel Receive Message . . . . . . . . . . . . 9-31
9.9.6 Cancel Receive Message Poll . . . . . . . . . 9-31
9.10 BLOCK DATA SERVICE . . . . . . . . . . . . . . . 9-33
9.10.1 Buffer Descriptor Table . . . . . . . . . . . 9-33
9.10.2 Map Buffer . . . . . . . . . . . . . . . . . . 9-34
9.10.3 Unmap Buffer . . . . . . . . . . . . . . . . . 9-34
9.10.4 Read . . . . . . . . . . . . . . . . . . . . . 9-34
9.10.5 Read Poll . . . . . . . . . . . . . . . . . . 9-35
9.10.6 Write . . . . . . . . . . . . . . . . . . . . 9-35
9.10.7 Write Poll . . . . . . . . . . . . . . . . . . 9-36
9.11 SCS SEND . . . . . . . . . . . . . . . . . . . . 9-37
9.12 SCS RECEIVE . . . . . . . . . . . . . . . . . . 9-39
CHAPTER 10 CI PPD OPERATION
10.1 PPD DATAGRAMS . . . . . . . . . . . . . . . . . 10-1
SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL Page 5
10.1.1 Start . . . . . . . . . . . . . . . . . . . . 10-1
10.1.2 Start Acknowledge . . . . . . . . . . . . . . 10-2
10.1.3 Acknowledge . . . . . . . . . . . . . . . . . 10-3
10.2 START VIRTUAL CIRCUIT . . . . . . . . . . . . . 10-4
10.3 CONFIGURATION . . . . . . . . . . . . . . . . . 10-6
10.4 OTHER PPD INTERFACE FUNCTIONS . . . . . . . . . 10-6
CHAPTER 11 NI PPD OPERATION
CHAPTER 12 BI PPD OPERATION
APPENDIX A PROCESS NAMING
APPENDIX B DIRECTORY SERVICE
B.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . B-1
B.2 LOCAL DIRECTORY MANAGEMENT . . . . . . . . . . . . B-1
B.2.1 Enter . . . . . . . . . . . . . . . . . . . . . B-1
B.2.2 Delete . . . . . . . . . . . . . . . . . . . . . B-2
B.3 REMOTE DIRECTORY ACCESS . . . . . . . . . . . . . B-2
B.3.1 Lookup Request . . . . . . . . . . . . . . . . . B-3
B.3.2 Lookup Response . . . . . . . . . . . . . . . . B-4
APPENDIX C THIRD PARTY I/O
APPENDIX D SCS/PPD TYPE AND LENGTH CODES
APPENDIX E REJECTION AND DISCONNECTION REASON CODES
APPENDIX F CI START DATA FORMAT
APPENDIX G EXAMPLE CI MESSAGE
APPENDIX H MINIMAL SUPPORT
APPENDIX I CHANGE HISTORY
CHAPTER 1
INTRODUCTION
This document describes the Systems Communications Architecture (SCA).
SCA should be contrasted with a network communications architecture
(e.g. DECNET/DNA). SCA is intended to be useful as an I/O
architecture in the traditional sense: it is optimized for high
performance. This high performance is achieved by restricting the
topologies, by specializing the function of the communications
services, and by assuming that communicating processes are highly
trustworthy. A network communications architecture, in contrast, is
designed to support varied topologies, more generalized communication
services, and less trustworthy communicating processes.
|
| This document describes an architecture and is not a functional
| specification for an implementation. An architecture document can be
| contrasted with a functional specification in several ways:
|
| o The descriptions of the interfaces (calls) and the data
| structures are general and need not be adhered to exactly in
| an implementation. They werve to specifiy the services
| present but need not restrict additional services provided.
|
| o An architecture provides a model of an implementation through
| which it describes the algorithms used in am implementation.
| It is the algorithms that are important and not the details
| of the data passing and synchronization that an
| implementation uses to embody those algorithms.
|
| Polling is used as the model of synchronization here because
| it is simple to describe and because it requires fewer
| interface calls. To describe a model using polling requires
| only calls to lower layers and not calls from lower layers to
| higher layers.
|
| The algorithms are important in so far as their results are
| visible at interfaces and in the protocol. It may be that
| implementations can modify the algorithms and achieve the
| same result.
|
| o Descriptions of protocol messages are exact and their order
| is important. These serve to allow all implementations of
| the architecture to communicate.
INTRODUCTION Page 1-2
The current revision of this document is focused on clusters of
systems interconnected with the CI. Later revisions will include
additional information on the relation of SCA to the NI and BI.
CHAPTER 2
SCA TOPOLOGICAL NOTATION
2.1 NETWORK
A set of interconnected systems that communicate using a network
communications service (e.g. DECNET/DNA NSP).
|
|
|
| 2.2 SCA CLUSTER
|
A set of interconnected systems that communicate using the Systems
Communications Services (SCS). The systems in a cluster are managed
by a single system manager and lie within a single security boundary.
2.3 COMMMUNICATIONS SERVICE
A module or process that provides a set of communications services to
a user.
2.4 SYSTEM ADDRESS
The 48-bit address of a system in a cluster or network. More
specifically, it is the address of a network communications service
and/or an SCS. Not all systems necessarily contain both a network
communications service and an SCS. The system addresses are
necessarily unique within the cluster or network and are preferably
globally unique. System addresses with bit 47 equal to 1 are not
allowed. System address 0 is not allowed.
2.5 PORT
The interface between an interconnect and the physical processor that
implements network communications services and/or SCS.
SCA TOPOLOGICAL NOTATION Page 2-2
2.6 PORT DRIVER
The software that controls a port.
2.7 INTERCONNECT
A physical communications path between ports.
2.8 POINT-TO-POINT INTERCONNECT
An interconnect joining two ports.
2.9 MULTIACCESS INTERCONNECT
An interconnect joining multiple ports that allows direct
communication between all port pairs. An n port multiaccess
interconnect is logically equivalent to n(n-1)/2 point-to-point
interconnects. The CI (Computer Interconnect) and NI (Network
Interconnect) are multiaccess interconnects.
|
|
|
| 2.10 PORT ADDRESS
|
| The 48 bit address of a port on a multiaccess interconnect. The port
| address may or may not be related to the system address. For example,
| the 48-bit NI port address is normally the system address of the
| system it interfaces.
CHAPTER 3
SCA TOPOLOGY
The basic topology supported by SCA is a fully, directly connected set
of systems. This can be realized either by a multiaccess interconnect
or an equivalent set of point-to-point interconnects. The purpose of
this restricted support is to eliminate the complexity of routing from
SCA. The multiaccess CI is the current focus for SCA:
CI
--------+---------------+---------------+--------
| | |
| | |
+-----+-----+ +-----+-----+ +-----+-----+
| system |...| system |...| system |
+-----------+ +-----------+ +-----------+
Note that the redundant dual path CI is logically a single CI.
In large clusters a single CI may have inadequate bandwidth. In this
case the acceptable topology is paralleled CI's:
CI
-----------+---------------+---------------+-----
| | |
| | CI |
--------+---------------+---------------+--------
| | | | | |
| | | | | |
+-----+--+--+ +-----+--+--+ +-----+--+--+
| system |...| system |...| system |
+-----------+ +-----------+ +-----------+
This topology retains the fully interconnected property.
SCA TOPOLOGY Page 3-2
Non-fully connected systems may be interconnected using multiple CI's.
An example would be several CPU's sharing file storage systems on a
common CI but with private paging systems on private CI's:
Common CI
--------+-----------------+-----------------+--------
| | |
| | |
+-----+------+ +-----+-----+ +------+-----+
| system X |... | system |... | system Y |
+-----+------+ +-----------+ +------+-----+
| |
pvt | | pvt
CI | | CI
| |
| |
+-----+-----+ +------+-----+
| system | | system Z |
+-----------+ +------------+
In this topology system X cannot communicate with system Z using SCS.
If the services provided by system Z are to be available to system X,
an intercept process (not part of SCA) must be provided in system Y.
CHAPTER 4
SCA LAYERING
SCA is described as a multilayer communications architecture. Layer 0
is the Physical Interconnect (PI) layer (e.g., the CI). Layer 1 is
the Port/Port (PPD) Driver layer, which controls the PI layer and
provides reliable, sequential transfers of data between ports on the
PI. (In the case of the CI, most of the PPD layer is implemented by
the CI port.) Layer 2 is the Systems Communication Services (SCS)
layer, which provides the process and system addressing, connection
management, and flow control necessary to multiplex the basic PPD data
services among multiple users. Layer 3 is the System Applications
(SYSAP) layer, which represents the users of SCS.
3. System Applications (SYSAP)
-------------------------------------
2. Systems Communications
Services (SCS)
-------------------------------------
1. Port/Port Driver (PPD)
-------------------------------------
0. Physical Interconnect (PI)
By analogy to DECNET/DNA the SCA SYSAP layer corresponds to the
DECNET/DNA Network Applications layer, SCS to NSP, and PPD to DDCMP.
CHAPTER 5
SYSAP-SCS INTERFACE NOTATION
5.1 PROCESS
A communicating entity that uses SCS: i.e., a SYSAP.
5.2 PROCESS NAME
A 16-byte string that identifies a SYSAP process within a system. See
Appendix A.
5.3 DIRECTORY
A list of SYSAP process names that exist in a system. See Appendix B.
5.4 SYSTEM LIST
A data structure that contains information on systems in a cluster.
Included are system chracteristics, system port characteristics, and
the state of port-to-port communications with the systems.
5.5 SYSTEM BLOCK
A data structure on the system list that describes the characteristics
of a system in a cluster.
5.6 PATH BLOCK
A data structure on the system list that describes the characteristics
of a particular interconnect used for port-to-port communications to a
specific system in a cluster.
SYSAP-SCS INTERFACE NOTATION Page 5-2
5.7 CONNECTION
The synchronization of two connection blocks in the same or different
systems to define a logical communications path between processes. A
process may participate in more than one connection at a time.
5.8 CONNECTION BLOCK
A data structure that contains the state of a connection.
5.9 CONNECT ID
The 32-bit identifier of a connection block within a system. This is
normally treated as a 16-bit connection number and a 16-bit sequence
number.
|
|
|
| 5.10 DATAGRAM COMMUNICATION SERVICE
|
| The transmission of an independent information unit (datagram) over a
| connection. Delivery of the datagram occurs with high probability,
| but is not guaranteed. Also, the order of delivery of a sequence of
| datagrams is not guaranteed.
5.11 DATAGRAM BUFFER
A buffer that contains (or can contain) a datagram. In SCA a datagram
buffer appears in layers 1, 2, and 3. To avoid copying between
layers, a datagram buffer is defined large enough to support layer 1,
2, and 3 data. Layer 3 ignores the layer 1 and 2 data; layer 2
ignores the layer 1 data.
|
|
|
| 5.12 SEQUENTIAL MESSAGE COMMUNICATIONS SERVICE
|
| The transmission of a sequence of independent information units
| (messages) over a connection. The messages are guaranteed to arrive
| in the order they were sent (without loss or duplication) or an error
| condition is indicated to the sender.
SYSAP-SCS INTERFACE NOTATION Page 5-3
5.13 MESSAGE BUFFER
A buffer that contains (or can contain) a message. A message buffer
is also used to contain control information for the block data
communications service. In SCA a message buffer appears in layers 1,
2, and 3. To avoid copying between layers, a message buffer is
defined large enough to support layer 1, 2, and 3 data. Layer 3
ignores the layer 1 and 2 data; Layer 2 ignores the layer l data.
5.14 QUEUED BUFFER
Either a datagram or a message buffer.
|
|
|
| 5.15 BLOCK DATA COMMUNICATIONS SERVICE
|
| The direct transmission of information (block data) between a named
| local buffer and a named destination buffer. The transmission takes
| place over a connection between the system containing the local named
| buffer and the system containing the destination named buffer. The
| block data is guaranteed to arrive completely or an error condition is
| indicated to the sender.
5.16 NAMED BUFFER
A named memory buffer used by the block data service. A buffer name
is a 32-bit value. A buffer is considered byte addressable with each
byte specified by a 32-bit unsigned offset from the beginning (byte 0)
of the buffer.
5.17 FLOW CONTROL
The method by which the rate of information flow from the sender to
the receiver is controlled. In SCS there is no flow control applied
to the datagram service. For the sequential message and block data
services, flow is controlled by a credit-based protocol that inhibits
a sender from sending information (messages, block data control, or
block data) until the receiver has provided a buffer to receive the
information.
5.18 CREDIT
A logical token held by a sending process that indicates that a
receiving process has queued a message buffer to (1) receive a message
or (2) permit a block data operation.
CHAPTER 6
SYSAP-SCS INTERFACE
The SCS interface is modelled as a set of PASCAL functions or
procedures of the form:
function FUNCTIONNAME ([var] ARGUMENTNAME:TYPE
[;[var]ARGUMENTNAME:TYPE]...):FUNCTIONSTATUS;
or
procedure PROCEDURENAME([var]ARGUMENTNAME:TYPE
[;[var]ARGUMENTNAME:TYPE]...);
where:
[] - indicates optional.
var - indicates an output argument.
FUNCTIONNAME - the name of the function.
PROCEDURENAME - the name of the procedure.
ARGUMENTNAME - the name of the argument.
TYPE - the type of the argument.
... - indicates replication.
FUNCTIONSTATUS - the status of function execution.
SYSAP-SCS INTERFACE Page 6-2
6.1 TYPE DEFINITIONS
The following PASCAL type definitions apply to the function and
procedure arguments:
| type BYTE = -128..127;
|
| WORD = -32768..32767;
|
| LONG = {32-bit} integer;
|
| QUAD = packed array [1..8] of BYTE;
|
| SEPTA = packed array [1..12] of BYTE;
|
| OCTA = packed array [1..16] of BYTE;
|
| SYSTEM = packed array [1..6] of BYTE; { system address }
|
| PORT = packed array [1..6] of BYTE; { port address }
|
| PROC_NAME = packed array [1..16] of BYTE; { process name }
|
| CONNECT_ID = record { connect id }
| INDEX: WORD;
| SEQ: WORD
| end;
|
| SB_INDEX = WORD; { system block index }
|
| PB_INDEX = WORD; { path block index }
|
| C_DATA = packed array [1..16] of BYTE; { connect data }
|
| APPL_MSG_LEN = 0..MAX_APPL_MSG; { SYSAP message length }
|
| APPL_DG_LEN = 0..MAX_APPL_DG; { SYSAP datagram length }
|
| BUF_USE = (BLK_ARG,MSG_DG); { variant record selector }
|
| MSGDG = (MSG,DG); { variant record selector }
|
| MSG_USE = (CONTROL,APPL); { variant record selector }
|
| Q_BUF_PTR = ^Q_BUFFER; { address of a queued buffer }
|
| Q_BUFFER = record { queued command buffer for message, datagram, or block transfer }
| NEXT: Q_BUF_PTR; { next buffer in queue }
| { PPD layer data }
| case BUF_USE of
|
| BLK_ARG:( { block data command }
| SEND_BLOCK_ID: WORD; { connection block index for the transfer }
| SEND_XID: WORD; { transaction number }
| DATA_LENGTH: LONG; { number of bytes to be transferred }
SYSAP-SCS INTERFACE Page 6-3
| SEND_NAME: LONG; { buffer name of source buffer }
| SEND_OFFSET: LONG; { starting byte in source buffer }
| REC_NAME: LONG; { buffer name of destination buffer }
| REC_OFFSET: LONG); { starting byte in destination buffer }
|
| MSG_DG:( { message or datagram command }
| LENGTH: WORD; { length in bytes of following fields }
| PPD_TYPE: WORD; { PPD message type code }
| SCS_TYPE: WORD; { SCS message type code }
| CREDIT: WORD; { number of credits to extend }
| REC_CONNECT_ID: CONNECT_ID; { destination connect ID }
| SEND_CONNECT_ID: CONNECT_ID; { source connect ID }
| case MSGDG of
|
| DG:( { if Datagram, just include application info. }
| DG_TEXT: packed array [1..MAX_APPL_DG]
| of BYTE);
|
| MSG:( { if Message ... }
| case MSG_USE of
|
| CONTROL:( { ... and this is SCS control message, then ... }
| MIN_CREDIT: WORD; { credit extended }
| STATUS: WORD; { reason for accept/reject }
| REC_PROC: PROC_NAME; { destination process name }
| SEND_PROC: PROC_NAME; { source process name }
| SEND_DATA: C_DATA); { connect data }
|
| APPL:( { ... else SYSAP message, so just include SYSAP stuff. }
| MSG_TEXT: packed array
| [1..MAX_APPL_MSG] of BYTE)))
| end;
|
|
| { BUF_DESCR = implementation specific named buffer descriptor }
|
|
|
| C_STATE = ( { process-to-process connection state }
| CLOSED, { connection is closed by command }
| LISTENING, { listening for connection request }
| CONNECT_SENT, { connect request was transmitted }
| CONNECT_REC, { connect request was received }
| CONNECT_ACK, { connect response was received }
| OPEN, { connection is open }
| ACCEPT_SENT, { accept request was sent }
| REJECT_SENT, { reject request was sent }
| DISCONNECT_SENT, { disconnect message was transmitted }
| DISCONNECT_REC, { disconnect message was received }
| DISCONNECT_ACK, { response received, waiting for remote disconnect }
| DISCONNECT_MATCH { waiting for matching response confirmation }
| );
|
| FSTATUS = (FAIL,SUCCESS,NULL,NOT_OPEN); { function status }
|
SYSAP-SCS INTERFACE Page 6-4
| PORT_CHAR = packed array [1..16] of BYTE; { see appropriate port specification }
|
| VC_STATE = ( { port-to-port virtual circuit state }
| MAINT, { maintenance state }
| VC_CLOSED, { virtual circuit closed }
| START_SENT, { start sequence initiated }
| START_REC, { start sequence received }
| VC_OPEN { virtual circuit is open }
| ); { virtual circuit state }{SYSAPDEF}
SYSAP-SCS INTERFACE Page 6-5
6.2 CONFIGURATION SERVICES
The configuration services allow the caller to determine the identity
of the connected systems and the number of paths to each system. A
system block is read by calling CONFIG_SYS. The system block contains
information on a remote system, its hardware and software
characteristics, and the number of connecting paths. A path block is
read by calling CONFIG_PATH. The path block contains port
characteristics and the state of port to port communications. The
REQ_ID procedure updates the port characteristics field of a path
block.
6.2.1 System Configuration
This function reads a system block:
| function CONFIG_SYS(
| ENTRY: SB_INDEX;
| var FIRST_PB: PB_INDEX;
| var SYS: SYSTEM;
| var MAX_DG: WORD;
| var MAX_MSG: WORD;
| var SW_TYPE: LONG;
| var SW_VERSION: LONG;
| var SW_INCARNATION: QUAD;
| var HW_TYPE: LONG;
| var HW_VERSION: SEPTA;
| var NODE_NAME: QUAD;
| var PORT_COUNT: WORD):
| FSTATUS;
where:
ENTRY the system list entry: entries start at one.
FIRST_PB the path block index of the first path to the
destination system.
SYS the destination system address.
MAX_DG the maximum size datagram (in bytes) supported by
the destination system.
MAX_MSG the maximum size message (in bytes) supported by
the destination system.
SW_TYPE 4-character ASCII software type of the destination
system.
SW_VERSION 4-character ASCII software version of the
destination system.
SYSAP-SCS INTERFACE Page 6-6
| SW_INCARNATION software incarnation of the destination system.
| This is initialized by the system at its boot
| time. When a ppd vc is established and the
| SW_INCARNATION changes from a previous value, it
| indicates that all of the system software state
| has been lost.
HW_TYPE the hardware type of the destination system.
HW_VERSION the hardware version of the destination system.
NODE_NAME the 8-byte ASCII node name of the destination
system.
PORT_COUNT the number of ports to the destination system.
FSTATUS SUCCESS if entry is valid; FAIL otherwise.
6.2.2 Path Configuration
This function reads a path block. The path block index for the first
path block to a destination system is determined by first calling
CONFIG_SYS for that system. Successive calls to CONFIG_PATH can be
made to scan the list of path blocks for a particular system.
function CONFIG_PATH(
ENTRY: PB_INDEX;
var STATE: VC_STATE;
var PRT: PORT;
var NEXT_PB: PB_INDEX;
var SB: SB_INDEX;
var CHAR: PORT_CHAR):
FSTATUS;
where:
ENTRY the index of the path block to be examined; path
block indices start at one.
STATE the virtual circuit state to the destination
system over this path. (MAINT, VC_CLOSED,
START_SENT, START_REC, VC_OPEN)
PRT the destination system port address.
NEXT_PB the path block index of the next path to this
system, or zero if this is the last path block.
SB the system block index of the system block to
which this path block is queued.
SYSAP-SCS INTERFACE Page 6-7
CHAR the characteristics of the destination system
port. (See the appropriate port specification.)
FSTATUS SUCCESS if entry is valid; FAIL otherwise.
Only if STATE = VC_OPEN can the connection management, datagram,
sequential message, and block data services be used.
|
| REQUEST ID REMOVED
SYSAP-SCS INTERFACE Page 6-8
6.3 CONNECTION MANAGEMENT SERVICE
| A connection exists in one of several states: CLOSED, LISTENING,
| CONNECT_SENT, CONNECT_ACK, CONNECT_REC, ACCEPT_SENT, REJECT_SENT,
| OPEN, DISCONNECT_SENT, DISCONNECT_REC, DISCONNECT_ACK and
| DISCONNECT_MATCH.
|
| There are two sides to a connection termed the active side and the
| passive side.
|
| The passive side indicates a willingness to establish a connection by
| calling LISTEN. This moves the passive side to the LISTENING state.
|
| The active side initiates a connection by calling CONNECT. A
| CONNECT_REQ message is sent and the state moves to CONNECT_SENT. A
| CONNECT_RSP is received with a status of NO_MATCH indicating that no
| such process is listening, NO_RESOURCES if no connect block is
| available, or CONNECTED if the connection can be handled by the
| destination system. The connect request is handed to the destination
| SYSAP at this point. When CONNECTED is returned, the CONNECT_ACK
| state is entered, otherwise the CLOSED state is entered.
|
| In the CONNECT_ACK state a REJECT_REQ causing the state to go to
| CLOSED or ACCEPT_REQ message can be received causing the state to go
| to OPEN.
|
| When the SYSAP on the destination receives the connect request, it
| responds with an ACCEPT causing its side to go to the ACCEPT_SENT
| state or a REJECT causing its side to go to the REJECT_SENT. The
| appropriate reply from the active side of ACCEPT_RSP causes the state
| to go OPEN, and recept of REJECT_RSP causes the state to go CLOSED.
When the connection is OPEN, the datagram, sequenced message, and
block data services may be used.
Either side initiates termination of the connection by calling
DISCONNECT. Following the DISCONNECT call, no datagram, sequential
message, or block transfer transmission operations can be performed by
the disconnecting side. Attempts to initiate a transfer will fail
with status NOT_OPEN. The sequence of states is dependent on the
order of the DISCONNECT calls. The protocol is generally asymmetric
with one side, called the active side, initiating the disconnect.
The active side calling DISCONNECT moves to the DISCONNECT_SENT state
while the passive side moves to DISCONNECT_REC state. When the active
side is notified of receipt of the disconnect request by the passive
side, it moves to DISCONNECT_ACK state. Both sides wait for the
passive SYSAP to be notified of the request and to respond with its
own DISCONNECT. When the passive SYSAP calls DISCONNECT, the passive
side moves to DISCONNECT_MATCH and notifies the active side of the
SYSAP's action. The active side moves to CLOSED state, and the
passive side moves to CLOSED upon confirmation. Should both sides
issue DISCONNECT requests simultaneously, the protocol will be
symmetric with both active sides moving through states
DISCONNECT_SENT, DISCONNECT_MATCH, and CLOSED.
SYSAP-SCS INTERFACE Page 6-9
| If there is any failure of lower SCA layers, both sides of any
| non-closed connection move to the CLOSED state.
The (local side) state of a connection is determined by calling
CONNECT_STATE_POLL. Section 9.6 contains a full state table
describing the above states and transition conditions.
|
| SYSAPs that require a minimum size for messages and datagrams operate
| in the following manner to assure that these message sizes are present
| on a connection: When the SYSAP starts, it checks the message sizes
| on the local system and does not perform a LISTEN if the message sizes
| are too small. Before a SYSAP performs a connect, it checks the
| message sizes of the remote system and does not perform the CONNECT if
| the remote systems message sizes are too small. The message sizes can
| be determined with the CONFIG_SYS request.
6.3.1 Connect
This function allocates a connection block and actively requests a
connection:
| function CONNECT(
| var CID: CONNECT_ID;
| SRC_PROC: PROC_NAME;
| DST_PROC: PROC_NAME;
| DST: SB_INDEX;
| THRSH: WORD;
| { [CREDITS: Q_BUF_PTR];... }
| DATA: C_DATA
| { [PATH: PB_INDEX] }
| ):
| FSTATUS;
where:
CID the connect id of the connection block allocated
by CONNECT.
SRC_PROC the local process name.
DST_PROC the destination process name.
DST the system block corresponding to the destination
system.
THRSH the minimum number of message buffers the
destination process should maintain for proper
operation of the SYSAP protocol.
|
| CREDITS the address of a list of message buffers that
| represent an initial credit.
SYSAP-SCS INTERFACE Page 6-10
DATA initial connection data. The format of DATA is
process specific.
PATH optional Path Block index, if SYSAP needs to
request connection over a specific interconnect.
|
| ERROR REMOVED
FSTATUS SUCCESS if a connection block is allocated; FAIL
otherwise.
6.3.2 Listen
This function allocates a connection block and passively listens for a
connection request from a destination process:
| function LISTEN(
| var CID: CONNECT_ID;
| SRC_PROC: PROC_NAME;
| DST_PROC: PROC_NAME;
| DST: SB_INDEX ):
| FSTATUS;
where:
CID the connect id of the connection block allocated
by LISTEN.
SRC_PROC the local process name.
DST_PROC the destination process name. A DST_PROC field of
all blanks indicates a willingness to connect to
any process.
DST the system block corresponding to the destination
system. A DST field of 0 indicates a willingness
to connect to any system.
|
| THRSH REMOVED
FSTATUS SUCCESS if a connection block is available; FAIL
otherwise.
SYSAP-SCS INTERFACE Page 6-11
6.3.3 Accept
This procedure accepts a requested connection:
| procedure ACCEPT(
| CID: CONNECT_ID;
| { [CREDITS: Q_BUF_PTR];...}
| THRSH : WORD;
| DATA: C_DATA);
where:
CID the local connect id.
CREDITS the address of a message buffer that represents an
initial credit.
|
| THRSH the minimum number of message buffers the
| destination process should maintain for proper
| operation of the SYSAP procotol.
DATA initial connection data. The format of DATA is
process specific.
6.3.4 Reject
This procedure rejects a requested connection:
procedure REJECT(
CID: CONNECT_ID;
REASON: WORD);
where:
CID the local connect id.
|
| REASON the reason for rejection. See Appendix E.
SYSAP-SCS INTERFACE Page 6-12
6.3.5 Disconnect
This procedure requests termination of a connection. Following a
disconnect call, further transfer requests will be returned with an
error.
procedure DISCONNECT(
CID: CONNECT_ID;
REASON: WORD);
where:
CID the local connect id.
|
| REASON the reason for disconnection. See Appendix E.
|
| /Due to the port design of the CI port, there is a restriction in the
| CI PPD layer. DISCONNECT cannot be called until all (locally
| initiated) outstanding block data transfers have completed. SCS based
| on other interconnects need not have this restriction. On some
| interconnects waiting for block transfers could be too time consuming
| to make waiting practical./
After DISCONNECT is called only the following connection related SCS
calls are valid:
1. STATE_POLL
2. SEND_DG_POLL
3. REC_DG_POLL
4. CANCEL_REC_DG
5. SEND_MSG_POLL
6. REC_MSG_POLL
7. CANCEL_REC_MSG_POLL
SYSAP-SCS INTERFACE Page 6-13
6.3.6 Connect State Poll
This procedure returns the state of a connection:
procedure STATE_POLL(
CID: CONNECT_ID;
var STATE: C_STATE;
var DST_CID: CONNECT_ID;
var DST_PROC: PROC_NAME;
var DST_SB: SB_INDEX;
var DST_PB: PB_INDEX;
var DATA: C_DATA;
var REASON: WORD);
where:
CID the local connect id.
|
| STATE the connection state. (CLOSED, LISTENING,
| CONNECT_SENT, CONNECT_ACK, CONNECT_REC,
| ACCEPT_SENT, REJECT_SENT, OPEN, DISCONNECT_SENT,
| DISCONNECT_REC, DISCONNECT_ACK, or
| DISCONNECT_MATCH.)
DST_CID the destination connect id.
DST_PROC the destination process name.
DST_SB the system block corresponding to the destination
system.
DST_PB the path block corresponding to the interconnect
over which the connection exists.
DATA connect data.
REASON the reason for rejection or disconnection.
Any queued datagram or message buffers remaining after a connection is
closed are disposed of in an implementation specific manner.
SYSAP-SCS INTERFACE Page 6-14
6.4 DATAGRAM SERVICE
A datagram is sent by calling SEND_DG. A parameter in the SEND_DG
call determines whether the buffer containing the datagram to be sent
is to be returned or queued to receive a datagram. In the former
case, the datagram buffer is returned by calling SEND_DG_POLL. A
datagram buffer is queued to receive a message by calling REC_DG.
Receipt of a datagram is checked by calling REC_DG_POLL. Return of a
queued datagram buffer is requested by calling CANCEL_REC_DG.
|
| Datagrams are queued and accounted for on a per connection basis. It
| is possible to return datagrams quickly to the receive queues when too
| many arrive for a connection and thereby make it more likely that
| datagram receive buffers are available to connections which carefully
| manage the number of datagram receive buffers they queue.
6.4.1 Send Datagram
This function sends a datagram over a connection:
function SEND_DG(
CID: CONNECT_ID;
RET_FLAG: boolean;
DLEN: APPL_DG_LEN;
PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
RET_FLAG true if the datagram buffer is to be returned,
false otherwise.
DLEN the length (in bytes) of the datagram text.
PTR the address of the datagram buffer.
FSTATUS SUCCESS if the send is queued, NOT_OPEN if the
connection has been closed.
When RET_FLAG is false, SEND_DG does an implicit Receive Datagram
since the datagram buffer is available after sending to receive a
datagram.
SYSAP-SCS INTERFACE Page 6-15
6.4.2 Send Datagram Poll
This function checks the return of a datagram sent with the RET_FLAG
true:
function SEND_DG_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
PTR the address of the datagram buffer.
FSTATUS SUCCESS if the buffer is returned; FAIL
otherwise.
Note that the original buffer contents are returned intact.
6.4.3 Receive Datagram
This function queues a datagram buffer to receive a datagram:
function REC_DG(
CID: CONNECT_ID;
PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
PTR the address of the datagram buffer.
FSTATUS SUCCESS if the receive buffer is queued, NOT_OPEN
if the connection has been closed.
SYSAP-SCS INTERFACE Page 6-16
6.4.4 Receive Datagram Poll
This function checks if a datagram has been received in a previously
queued datagram buffer:
function REC_DG_POLL(
CID: CONNECT_ID;
var DLEN: APPL_DG_LEN;
var PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
DLEN the length (in bytes) of the datagram text.
PTR the address of the datagram buffer.
FSTATUS SUCCESS if a datagram has been received; FAIL
otherwise.
6.4.5 Cancel Receive Datagram
This function dequeues a datagram buffer:
function CANCEL_REC_DG(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
PTR the address of the datagram buffer.
FSTATUS SUCCESS if a buffer is dequeued; FAIL otherwise.
SYSAP-SCS INTERFACE Page 6-17
6.5 SEQUENTIAL MESSAGE SERVICE
A message is sent by calling SEND_MSG. A parameter in the SEND_MSG
call determines whether the buffer containing the message is to be
returned or queued to receive a message. In the former case, the
message buffer is returned by calling SEND_MSG_POLL. A message buffer
is queued to receive a message by calling REC_MSG. Receipt of a
message is checked by calling REC_MSG_POLL. Return of a queued
message buffer is requested by calling CANCEL_REC_MSG. The queued
message buffer is returned by calling CANCEL_REC_MSG_POLL.
The sequential message service uses credit-based flow control.
Consider two sides of a connection X and Y. When X queues a message
buffer, Y receives a send credit. In general, if Y queues y buffers
and X queues x buffers, Y has x send credits and X has y send credits.
To send a message, a send credit is needed. When the message is sent,
the number of send credits is decremented by 1.
In order to support messages of different importance on a single
connection, a threshold mechanism is employed. A threshold parameter
appears in two places:
1. When a connection is established each side specifies a
threshold which is the minimum number of queued message
buffers the other side should maintain for proper operation
of the SYSAP protocol (i.e. the support of messages of
different importance). A CANCEL_REC_MSG call does not return
buffers that would drop the number of send credits on the
other side below the SYSAP protocol threshold.
2. A SEND_MSG call (also the READ and WRITE calls: see the
section on block data service) has a threshold number that
results in a message being sent only if at least that number
of send credits would remain after sending the message.
SYSAP-SCS INTERFACE Page 6-18
6.5.1 Send Message
This function sends a message over a connection:
function SEND_MSG(
CID: CONNECT_ID;
THRSH: WORD;
RET_FLAG: boolean;
MLEN: APPL_MSG_LEN;
PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
THRSH the message is sent only if at least this many
send flow control credits will remain. The
minimum value of THRSH is 0.
RET_FLAG true if the message buffer is to be returned;
false otherwise.
MLEN the length (in bytes) of the message.
PTR the address of the message buffer.
FSTATUS SUCCESS if the send is queued, FAIL if no flow
control credit is available, NOT_OPEN if the
connection has been closed.
When RET_FLAG is false, SEND_MSG does an implicit Receive Message
since the message buffer is available to receive a message.
6.5.2 Send Message Poll
This function checks the return of a message sent with the RET_FLAG
true:
function SEND_MSG_POLL(
CID:CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
PTR the address of the message buffer.
FSTATUS SUCCESS if a buffer is returned; FAIL otherwise.
SYSAP-SCS INTERFACE Page 6-19
Note that the original buffer contents are returned intact.
6.5.3 Receive Message
This function queues a message buffer to receive a message and extends
a flow control credit to the destination process:
function REC_MSG(
CID: CONNECT_ID;
PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
PTR the address of the message buffer.
FSTATUS SUCCESS if the buffer has been queued, NOT_OPEN if
the connection has been closed.
6.5.4 Receive Message Poll
This function checks if a message has been received in a previously
queued message buffer:
function REC_MSG_POLL(
CID: CONNECT_ID;
var MLEN: APPL_MSG_LEN;
var PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
MLEN the length (in bytes) of the message.
PTR the address of the message buffer.
FSTATUS SUCCESS if a message has been received; FAIL
otherwise.
SYSAP-SCS INTERFACE Page 6-20
6.5.5 Cancel Receive Message
This procedure requests return of a message buffer (and the associated
flow control credit from the destination process):
procedure CANCEL_REC_MSG(
CID: CONNECT_ID);
where:
CID the local connect id.
Cancellation does not occur if (1) the flow control credit has been
used by the destination process to send a message or for a block data
operation, or (2) the number of destination credits would drop below
the SYSAP protocol threshold.
6.5.6 Cancel Receive Message Poll
This function checks if a cancel operation has completed:
function CANCEL_REC_MSG_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
where:
CID the local connect id.
PTR the address of the message buffer.
FSTATUS SUCCESS if a buffer is returned; NULL if the
cancel cannot be completed; FAIL otherwise.
CANCEL_REC_MSG_POLL must be called until every cancel has a matching
SUCCESS or NULL FSTATUS. Null status indicates that the destination
would not allow the buffer to be returned in order to keep the number
of credits above threshold.
SYSAP-SCS INTERFACE Page 6-21
6.6 BLOCK DATA SERVICE
A name is associated with a named buffer by calling MAP. This name
may be used locally or passed to the other side of a connection using
one of the communications services. A name is disassociated from a
buffer by calling UNMAP.
By calling WRITE, data is transferred from the local side to the
destination side. The completion of the transfer is checked by
calling WRITE_POLL. Similarly, by calling READ, data is transferred
from the destination side to the local side. The completion of the
transfer is checked by calling READ_POLL.
To initiate a block data transfer, the local side must hold a send
credit. The send credit is used for the duration of the transfer, but
is available again after completion of the transfer.
|
| In the following description, no provision is made for cancelling
| block data transfers. An implementation must provide a cancel
| function. Due to a restriction in the CI-780 port, it is not possible
| to withdraw a block transfer that has started without shutting down
| the port to port VC. This is not the intent of SCA and should be
| viewed as an implementation restriction.
6.6.1 Map Buffer
This function associates a name with a local named buffer:
function MAP(
{BLOCK_BUF: BUF_DESCR;}
var NAME: LONG):
FSTATUS;
where:
BLOCK_BUF a descriptor of a named buffer (implementation
specific).
NAME the name of buffer returned by MAP.
FSTATUS SUCCESS if a name is associated; FAIL otherwise.
The MAP function may have additional implementation specific
parameters. An examples is a connect id that indicates that the
connection block has additional information on how to map the buffer.
This would be needed if there were multiple ports on the system with
different named buffer mapping techniques.
SYSAP-SCS INTERFACE Page 6-22
6.6.2 Unmap Buffer
This procedure disassociates a name from a named buffer:
procedure UNMAP(
NAME: LONG);
where:
NAME the buffer name.
6.6.3 Read
This function requests transfer of data from a destination named
buffer to a local block data buffer:
function READ(
CID: CONNECT_ID;
THRSH: WORD;
PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
where:
CID the local connect id.
THRSH the transfer is started only if at least this many
send flow control credits will remain. The
minimum value of THRSH is 0.
PTR the address of the message buffer containing the
block data arguments.
XID the transaction id assigned by READ.
FSTATUS SUCCESS if the transfer is queued, FAIL if no flow
control credit is available, NOT_OPEN if the
connection has been closed.
The block data arguments include:
DATA_LENGTH the number of bytes to be transferred.
SEND_NAME the name of the buffer from which the data is
read.
SEND_OFFSET the starting byte in sending buffer.
REC_NAME the name of the buffer to which the data is
written.
SYSAP-SCS INTERFACE Page 6-23
REC_OFFSET the starting byte in the receiving buffer.
6.6.4 Read Poll
This function checks if a read transfer has completed:
function READ_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
where:
CID local connect id.
PTR the address of the message buffer returned by
READ_POLL.
XID the transaction id of the completed read.
FSTATUS SUCCESS if a read has completed; FAIL otherwise.
SYSAP-SCS INTERFACE Page 6-24
6.6.5 Write
This function requests transfer of data from a local named buffer to a
destination block data buffer:
function WRITE(
CID: CONNECT_ID;
THRSH: WORD;
PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
where:
CID the local connect id.
THRSH the transfer is started only if this many send
flow control credits will remain. The minimum
value of THRSH is 0.
PTR the address of the message buffer containing the
block data arguments.
XID the transaction id assigned by WRITE.
FSTATUS SUCCESS if the transfer is queued, FAIL if no flow
control credit is available, NOT_OPEN if the
connection has been closed.
The block data arguments include:
DATA_LENGTH the number of bytes to be transferred.
SEND_NAME the name of the buffer from which the data is
read.
SEND_OFFSET the starting byte in sending buffer.
REC_NAME the name of the buffer to which the data is
written.
REC_OFFSET the starting byte in the receiving buffer.
SYSAP-SCS INTERFACE Page 6-25
6.6.6 Write Poll
This function checks if a write transfer has completed:
function WRITE_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
where:
CID the local connect id.
PTR the address of the message buffer returned by
WRITE_POLL.
XID the transaction id of the completed write.
FSTATUS SUCCESS if a write has completed; FAIL otherwise.
CHAPTER 7
SCS-PPD INTERFACE
The PPD interface is modelled as a set of function and procedure calls
of the same form as the SCS interface. The PPD interface is
essentially the CI port architecture, and the function and procedure
names (where appropriate) are the corresponding CI port command
mnemonics.
|
| REQUEST ID REMOVED
7.1 DATAGRAM SERVICE
7.1.1 Send Datagram
This procedure sends a datagram to a destination system:
procedure SNDDG(
DST: PB_INDEX;
RET_FLAG: boolean;
PTR: Q_BUF_PTR);
where:
DST the destination port path block address.
RET_FLAG true if a DGSNT response is to be generated;
false otherwise.
PTR the address of the datagram buffer.
SCS-PPD INTERFACE Page 7-2
7.1.2 Receive Datagram
This procedure queues a datagram buffer to receive a datagram:
procedure INSERT_DFREEQ(
PTR: Q_BUF_PTR);
where:
PTR the address of the datagram buffer.
7.1.3 Return Datagram Buffer
This function dequeues a datagram buffer:
function REMOVE_DFREEQ(
var PTR: Q_BUF_PTR):
FSTATUS;
where:
PTR the address of the datagram buffer.
FSTATUS SUCCESS if a buffer is dequeued; FAIL otherwise.
SCS-PPD INTERFACE Page 7-3
7.2 VIRTUAL CIRCUIT SERVICE
7.2.1 Start Virtual Circuit
This procedure requests the opening of a virtual circuit between the
local and a destination system:
procedure START_VC(
DST: PB_INDEX;
DATA: START_DATA;
MPTR1: Q_BUF_PTR;
MPTR2: Q_BUF_PTR;
DPTR: Q_BUF_PTR);
where:
DST the path block corresponding to the destination
port.
DATA start data. See Appendix G.
MPTR1 the address of a message buffer.
MPTR2 the address of a message buffer.
DPTR the address of a datagram buffer.
|
| Both message buffers, MPTR1 and MPTR2, are used to communicate between
| SCS instances to establish and maintain connections. One is used to
| send control messages and is immediately queued as a receive to
| receive the response. One buffer is queued at all times as a receive
| for commands from the other side and is queued as a transmit for the
| response. After the response transmit it is queued as a receive for
| the next incoming command. There is at most one outstanding SCS
| command being processed by the other side and one being processed by
| this side.
|
| The datagram message buffer, DPTR, is used to start the port to port
| virtual circuit and is used for both transmit and receive.
SCS-PPD INTERFACE Page 7-4
7.3 MESSAGE SERVICE
7.3.1 Send Message
This procedure sends a message to a destination system:
procedure SNDMSG(
DST: PB_INDEX;
RET_FLAG: boolean;
PTR: Q_BUF_PTR);
where:
DST the destination port path block address.
RET_FLAG true if a MSGSNT response is to be generated;
false otherwise.
PTR the address of the message buffer.
SNDMSG requires an open virtual circuit to exist to DST.
7.3.2 Receive Message
This procedure queues a message buffer to receive a message:
procedure INSERT_MFREEQ(
PTR: Q_BUF_PTR);
where:
PTR the address of the message buffer.
7.3.3 Return Message Buffer
This function dequeues a message buffer:
function REMOVE_MFREEQ(
var PTR: Q_BUF_PTR):
FSTATUS;
where:
PTR the address of the message buffer.
FSTATUS SUCCESS if a buffer is dequeued; FAIL otherwise.
SCS-PPD INTERFACE Page 7-5
7.4 BLOCK DATA SERVICE
7.4.1 Send Data
This procedure sends data from a named buffer in the local system to a
named buffer in the destination system:
procedure SNDDAT(
DST: PB_INDEX;
PTR: Q_BUF_PTR);
where:
DST the destination port path block address.
PTR the address of the message buffer containing the
block data arguments.
The block data arguments include:
DATA_LENGTH the number of bytes to be transferred.
SEND_NAME the name of the buffer from which the data is
read.
SEND_OFFSET the starting byte in sending buffer.
REC_NAME the name of the buffer to which the data is
written.
REC_OFFSET the starting byte in the receiving buffer.
SNDDAT requires a open virtual circuit to exist to DST.
SCS-PPD INTERFACE Page 7-6
7.4.2 Request Data
This procedure requests the sending of data from a named buffer in a
destination system to a named buffer in the local system:
procedure REQDAT(
DST: PB_INDEX;
PTR: Q_BUF_PTR);
where:
DST the destination port path block address.
PTR the address of the message buffer containing the
block data arguments.
The block data arguments include:
DATA_LENGTH the number of bytes to be transferred.
SEND_NAME the name of the buffer from which the data is
read.
SEND_OFFSET the starting byte in sending buffer.
REC_NAME the name of the buffer to which the data is
written.
REC_OFFSET the starting byte in the receiving buffer.
REQDAT requires a open virtual circuit to exist to DST.
SCS-PPD INTERFACE Page 7-7
7.5 RESPONSES
This function checks if a message has been sent, a message has been
received, a datagram has been sent, a datagram has been received, sent
data has been confirmed, requested data has been received, or an id
has been received.
function RSP_POLL(
var RSP: RSP_TYPE;
var DST: PB_INDEX;
var PTR: Q_BUF_PTR):
FSTATUS;
where:
RSP the response type: (MSGSNT, DGSNT, MSGREC, DGREC,
CNFREC, DATREC, IDREC, MCNFREC, MDATREC).
DST the destination port path block address.
PTR the address of a queued buffer returned by
RSP_POLL. The buffer is a messsage buffer for
MSGSNT, MSGREC, CNFREC, and DATREC and a datagram
buffer otherwise.
FSTATUS SUCCESS if a response is present; FAIL otherwise.
CHAPTER 8
SCS MESSAGES AND DATAGRAMS
8.1 TYPES
SCS messages and datagrams are of two basic types: control and
application. Control messages carry information between peer SCS
processes while application messages and datagrams carry information
between peer SYSAP processes. Control messages are of two subtypes:
request and response. A request message from SCS process X to SCS
process Y is followed by a response message from SCS process Y to SCS
process X that acknowledges the previous request and enables sending
the next request.
SCS MESSAGES AND DATAGRAMS Page 8-2
The general format of an SCS message or datagram is:
3 1
1 5 0
+---------------+---------------+
| CREDIT | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+-------------------------------+
| |
= SCS_TYPE_SPECIFIC =
| |
+-------------------------------+
where:
SCS_TYPE the message or datagram type.
CREDIT the flow control credit.
REC_CONNECT_ID the connect id of the process that is receiving
the message or datagram or on whose behalf it is
being received.
SEND_CONNECT_ID the connect id of the process that is sending the
messsage or datagram or on whose behalf it is
being sent.
SCS_TYPE_SPECIFIC depends on SCS_TYPE.
SCS MESSAGES AND DATAGRAMS Page 8-3
8.2 SCS CONTROL MESSAGES
8.2.1 Connect Request
The CONNECT_REQ request message requests a connection. The format of
CONNECT_REQ is:
3 1
1 5 0
+---------------+---------------+
| CREDIT | SCS_TYPE |
+---------------+---------------+
| 0 |
+---------------+---------------+
| SEND_CONNECT_ID |
+---------------+---------------+
| 0 | MIN_CREDIT |
+---------------+---------------+
| |
= REC_PROC =
| |
+-------------------------------+
| |
= SEND_PROC =
| |
+-------------------------------+
| |
= SEND_DATA =
| |
+-------------------------------+
where:
SCS_TYPE CONNECT_REQ.
CREDIT the initial number of flow control credits
extended. CREDIT must be non-negative.
SEND_CONNECT_ID the connect id of the process sending the connect
request.
MIN_CREDIT the minimum number of flow control credits needed.
MIN_CREDIT must be non-negative.
REC_PROC the name of the process to receive the request.
SEND_PROC the name of the process sending the request.
SEND_DATA connect data from the sending process.
SCS MESSAGES AND DATAGRAMS Page 8-4
8.2.2 Connect Response
The CONNECT_RSP response message acknowledges the CONNECT_REQ message
and enables sending the next request message. The format of
CONNECT_RSP is:
3 1
1 5 0
+---------------+---------------+
| 0 | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+---------------+---------------+
| STATUS | 0 |
+---------------+---------------+
where:
SCS_TYPE CONNECT_RSP.
REC_CONNECT_ID the connect id of the process sending the connect
request.
SEND_CONNECT_ID the connect id of the process responding to the
connect request.
|
| STATUS CONNECTED if the connect request was queued,
| NO_MATCH or NO_RESOURCES otherwise.
SCS MESSAGES AND DATAGRAMS Page 8-5
8.2.3 Accept Request
The ACCEPT_REQ request message accepts a connection request. The
format of ACCEPT_REQ is:
3 1
1 5 0
+---------------+---------------+
| CREDIT | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+---------------+---------------+
| 0 | MIN_CREDIT |
+---------------+---------------+
| |
= REC_PROC =
| |
+-------------------------------+
| |
= SEND_PROC =
| |
+-------------------------------+
| |
= SEND_DATA =
| |
+-------------------------------+
where:
SCS_TYPE ACCEPT_REQ.
CREDIT the initial number of credits extended. CREDIT
must be non-negative.
REC_CONNECT_ID the connect id of the process receiving the
request.
SEND_CONNECT_ID the connect id of the process sending the request.
MIN_CREDIT the minimum number of flow control credits needed.
MIN_CREDIT must be non-negative.
REC_PROC the name of the process receiving the request.
SEND_PROC the name of the process sending the request.
SEND_DATA connect data from the sending process.
SCS MESSAGES AND DATAGRAMS Page 8-6
8.2.4 Accept Response
The ACCEPT_RSP response message acknowledges the ACCEPT_REQ message
and enables sending the next request message. The format of
ACCEPT_RSP response is:
|
|
| 3 1
| 1 5 0
| +---------------+---------------+
| | 0 | SCS_TYPE |
| +---------------+---------------+
| | REC_CONNECT_ID |
| +-------------------------------+
| | SEND_CONNECT_ID |
| +-------------------------------+
| | REASON | 0 |
| +-------------------------------+
|
where:
SCS_TYPE ACCEPT_RSP.
REC_CONNECT_ID same as SEND_CONNECT_ID in the ACCEPT_REQ message.
SEND_CONNECT_ID same as REC_CONNECT_ID in the ACCEPT_REQ message.
| REASON reason for failure to accept connection.
| NO_RESOURCES and DISCONNECTED are possible.
| CONNECTED means that the ACCEPT_REQ is being
| processed.
SCS MESSAGES AND DATAGRAMS Page 8-7
8.2.5 Reject Request
The REJECT_REQ request message rejects a connection request. The
format of REJECT_REQ is:
|
|
| 3 1
| 1 5 0
| +---------------+---------------+
| | 0 | SCS_TYPE |
| +---------------+---------------+
| | REC_CONNECT_ID |
| +-------------------------------+
| | SEND_CONNECT_ID |
| +---------------+---------------+
| | REASON | 0 |
| +---------------+---------------+
|
|
where:
SCS_TYPE REJECT_REQ.
REC_CONNECT_ID the connect id of process receiving the request.
SEND_CONNECT_ID the connect id of the process sending the request.
|
| REASON the reason for rejection. See Appendix E.
SCS MESSAGES AND DATAGRAMS Page 8-8
8.2.6 Reject Response
The REJECT_RSP response message acknowledges the REJECT_REQ message
and enables sending the next request message. The format of
REJECT_RSP is:
3 1
1 5 0
+---------------+---------------+
| 0 | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+-------------------------------+
where:
SCS_TYPE REJECT_RSP.
REC_CONNECT_ID same as SEND_CONNECT_ID in the REJECT_REQ message.
SEND_CONNECT_ID same as REC_CONNECT_ID in the REJECT_REQ message.
SCS MESSAGES AND DATAGRAMS Page 8-9
8.2.7 Disconnect Request
The DISCONNECT_REQ request message requests disconnection. The format
of DISCONNECT_REQ is:
|
|
| 3 1
| 1 5 0
| +---------------+---------------+
| | 0 | SCS_TYPE |
| +---------------+---------------+
| | REC_CONNECT_ID |
| +-------------------------------+
| | SEND_CONNECT_ID |
| +---------------+---------------+
| | REASON | 0 |
| +---------------+---------------+
|
|
where:
SCS_TYPE DISCONNECT_REQ.
REC_CONNECT_ID the connect id of the process receiving the
request.
SEND_CONNECT_ID the connect id of the process sending the request.
|
| REASON the reason for disconnection. See Appendix E.
SCS MESSAGES AND DATAGRAMS Page 8-10
8.2.8 Disconnect Response
The DISCONNECT_RSP response message acknowledges the DISCONNECT_REQ
message and enables sending the next request message. The format of
DISCONNECT_RSP is:
3 1
1 5 0
+---------------+---------------+
| 0 | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+-------------------------------+
where:
SCS_TYPE DISCONNECT_RSP.
REC_CONNECT_ID same as SEND_CONNECT_ID in the DISCONNECT_REQ
message.
SEND_CONNECT_ID same as REC_CONNECT_ID in the DISCONNECT_REQ
message.
SCS MESSAGES AND DATAGRAMS Page 8-11
8.2.9 Credit Request
The CREDIT_REQ request message carries credits for flow control. The
format of CREDIT_REQ is:
3 1
1 5 0
+---------------+---------------+
| CREDIT | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+-------------------------------+
where:
SCS_TYPE CREDIT_REQ.
CREDIT a signed integer giving, if non-negative, the
number of additional credits extended; if
negative, the number of credits requested to be
returned.
REC_CONNECT_ID the connect id of the process receiving the
credits.
SEND_CONNECT_ID the connect id of the process sending the credits.
SCS MESSAGES AND DATAGRAMS Page 8-12
8.2.10 Credit Response
The CREDIT_RSP response message acknowledges the CREDIT_REQ message
and enables sending of the next request message. The format of
CREDIT_RSP is:
3 1
1 5 0
+---------------+---------------+
| CREDIT | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+-------------------------------+
where:
SCS_TYPE CREDIT_RSP.
CREDIT if the CREDIT field in the CREDIT_REQ message was
non-negative, then the value of CREDIT; otherwise
the negative of the number of credits actually
returned.
REC_CONNECT_ID same as SEND_CONNECT_ID in the CREDIT_REQ message.
SEND_CONNECT_ID same as REC_CONNECT_ID in the CREDIT_REQ message.
SCS MESSAGES AND DATAGRAMS Page 8-13
8.3 APPLICATION MESSAGE
The APPL_MSG application message carries a SYSAP layer message. The
format of APPL_MSG is:
3 1
1 5 0
+---------------+---------------+
| CREDIT | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+-------------------------------+
| |
= SYSAP_MSG_TEXT =
| |
+-------------------------------+
where:
SCS_TYPE APPL_MSG.
CREDIT the number of flow control credits being extended.
CREDIT must be non-negative.
REC_CONNECT_ID the connect id of the process receiving the
message.
SEND_CONNECT_ID the connect id of the process sending the message.
SYSAP_MSG_TEXT the SYSAP layer message text.
SCS MESSAGES AND DATAGRAMS Page 8-14
8.4 APPLICATION DATAGRAM
The APPL_DG datagram carries a SYSAP layer datagram. The format of
APPL_DG is:
3 1
1 5 0
+---------------+---------------+
| 0 | SCS_TYPE |
+---------------+---------------+
| REC_CONNECT_ID |
+-------------------------------+
| SEND_CONNECT_ID |
+-------------------------------+
| |
= SYSAP_DG_TEXT =
| |
+-------------------------------+
where:
SCS_TYPE APPL_DG.
REC_CONNECT_ID the connect id of the process receiving the
datagram.
SEND_CONNECT_ID the connect id of the process sending the
datagram.
SYSAP_DG_TEXT the SYSAP layer datagram text.
CHAPTER 9
SCS OPERATION
9.1 RELATION TO PPD VIRTUAL CIRCUIT
All SCS messages flow over a port-to-port virtual circuit provided by
the PPD layer. All SYSAP-SCS connections are multiplexed on this
virtual circuit. Closing the PPD virtual circuit by either system
requires closing all SCS connections. The SYSAPs are notified of
connection close by calling the STATE_POLL function.
|
|
|
| 9.2 SCS PROTOCOL VERSION RESOLUTION
|
| The start data contains a protocol version number. This allows SCA
| version upgrade in the future. The first version of SCA is version
| zero.
|
| The version field is compared in such a way to allow newer versions to
| be written to talk down to older versions as well as to their
| contemporary versions. This is done by leaving the decision of making
| the start_vc to the higher numbered version. The lower number version
| always accepts starts from the same or higher versions. Higher number
| versions always accept equal version starts and may as well accept
| starts from lower numbered versions if the higher version is willing
| to talk down to the older version. Talking down is an implementation
| decision. Accepting connects from higher versions is required.
9.3 SCS CONTROL MESSAGE FLOW CONTROL
When a port-to-port virtual circuit is opened, each system supplies 2
message buffers. The first, termed the local message buffer, is used
to send SCS control request messages and receive the associated
response control message. This buffer is initially queued on the path
block, dequeued to send a request message, and requeued after the
response is received. The second, termed the destination message
buffer, is used to receive SCS control request messages and send the
associated response control message. This buffer is initially queued
on the PPD MFREEQ, dequeued when a SCS control request is received,
and requeued after the response is sent. At most 1 request message on
SCS OPERATION Page 9-2
each direction of the virtual circuit can be outstanding at a time.
Only when the destination of the request responds with a response
message can another request message be sent.
|
| These are some descriptions of the credit variables used in the SCS
| operation description which will help to understand credit management.
|
| THRSH this value is the name of a call parameter which
| corresponds to MIN_SEND_CREDIT. When a connection
| is established, this parameter becomes
| MIN_SEND_CREDIT. In other calls when a circuit is
| running, it is compared to SEND_CREDIT and
| SEND_CREDIT must be at least this value to
| succeed.
|
| SEND_CREDIT credits extended to this side by partner for
| transmit buffers. Or the number of receives
| queued by the partner.
|
| MIN_SEND_CREDIT minimum number of credits a SYSAP expects to have
| to transmit to the other side. In other words, a
| SYSAP expects to have this many buffers queued as
| receives by its partner. This is a constant for
| each connection and is established by the partner
| SYSAP.
|
| REC_CREDITS credits this side has extended to the other side
| to transmit. The number of receives queued here.
|
| MIN_REC_CREDIT minimum number of credits the other side expects
| to have to transmit. Or the minimum number of
| receives we will keep queued here. This is a
| constant for each connection and is established by
| the SYSAP on this side.
|
| PEND_REC_CREDIT accumulated number of credits that have been
| queued as receives here but have not been sent to
| the partner in a credit message.
|
| REQ_CREDIT the number of credits sent in the last CREDIT_REQ
| message. This cell is used for the duration of
| the credit_req, _rsp pair to enable the correct
| setting of RET_NULL.
|
| RET_CREDIT number of credits actually obtained from the
| partner or deducted on this side from
| PEND_REC_CREDIT by cancel credit calls. This is
| the count of buffers that can be returned to the
| SYSAP caller requesting to cancel receives.
|
| RET_NULL the number of cancel credit requests for which no
| buffer is available because they have not been
| returned in a credit_rsp message from the other
| side.
SCS OPERATION Page 9-3
9.4 SCS OPERATION DESCRIPTION
The SCS process is described as expansions of the SCS interface calls
and as 2 subprocesses, SCS_SEND and SCS_REC.
SCS_SEND sends SCS control request messages. An SCS interface call
needing the SCS request message service queues the appropriate
connection block on the appropriate path block. The path block, if
not already queued, is placed on the SCS_SEND_Q work queue. SCS_SEND
removes the path block from the work queue and sends a request message
(using the local message buffer). The following shows the
relationship of the data structures used by SCS_SEND:
+-------+
| |-----> next system
|system | block
| block |
| |
+-------+
^
|
|
V
+-------+ +-------+ +-------+ +-------+
<-------| |<------| |<------| |------>| |
|connect| |connect| | path | | local |
| block | | block | | block | |msg buf|
| | | | | | | |
+-------+ +-------+ +-------+ +-------+
|
|
|
V
next path
block
SCS OPERATION Page 9-4
SCS_REC receives all incoming messages and datagrams and does the
following:
1. Processes and delivers SYSAP messages and datagrams; DATREC;
MDATREC; DATCNF; and MDATCNF responses.
2. Processes SCS request control messages and sends the
appropriate response.
3. Processes SCS response control messages, queues the local
message buffer on the path block, and if the CB_Q in the path
block is non-empty, queues the path block on the SCS_SEND_Q
work queue.
4. Delivers IDREC responses. If the IDREC is from a 'new'
system, calls START_VC to start the PPD virtual circuit.
The focal points of SCS operation are the path and connection blocks
that are modified by the SCS interface calls, SCS_SEND, and SCS_REC.
It is assumed that modifications to a path and connection block are
synchronized by some standard technique: e.g. all the modifications
are done at the same IPL.
SCS OPERATION Page 9-5
9.5 TYPE, VARIABLE , FUNCTION, AND PROCEDURE DEFINITIONS
The following PASCAL definitions apply to the SCS operation
description.
type
SB = record { system block definition }
SB$NEXT_SB: SB_PTR; { address of next SB }
SB$FIRST_PB: PB_INDEX; { array index of first path block }
SB$DST_PORT_COUNT: WORD; { number of interconnects to dst }
SB$DST_SYS: SYSTEM; { destination system address }
SB$DST_MAX_DG: WORD; { max. datagram size allowed }
SB$DST_MAX_MSG: WORD; { max. message size allowed }
SB$DST_SW_TYPE: LONG; { software type }
SB$DST_SW_VERSION: LONG; { software version }
SB$DST_SW_INCAR: QUAD; { software incarnation number }
SB$DST_HW_TYPE: LONG; { hardware type }
SB$DST_HW_VERSION: SEPTA; { hardware version }
SB$DST_NODE_NAME: QUAD { ASCII node name }
end;
PB = record { path block definition }
PB$NEXT_PB: PB_INDEX; { index of next path block to system }
PB$SB: SB_INDEX; { index of system block for this PB }
PB$DST_VC_STATE: VC_STATE; { state of port-to-port virtual circuit }
PB$DST_PORT: PORT; { destination port address }
PB$DG_Q: Q_BUF_PTR; { datagram return queue }
PB$MSG_PTR: Q_BUF_PTR; { scs control message pointer }
PB$CB_Q: CB_PTR; { queue of CBs requiring SCS service }
PB$DST_PORT_CHAR: PORT_CHAR { characteristics of remote port }
end;
B_STATE = ( { Connection block state for CB$BLOCK_STATE. This field is used as
an opcode to SCS_SEND, which examines it to determine what type of
control message to send. }
FREE, { connection block is unused }
ALLOC, { connection block is allocated }
CONNECT_PEND, { send a connect message }
ACCEPT_PEND, { send an accept message }
REJECT_PEND, { send a reject message }
CREDIT_PEND, { send a credit message }
DISCONNECT_PEND { send a disconnect message }
);
CB = record { connection block }
CB$NEXT_CB: CB_PTR; { address of next CB in queue }
CB$CONNECT_STATE: C_STATE; { state of process-to-process connection }
CB$BLOCK_STATE: B_STATE; { state of this connection block }
CB$SRC_CONNECT_ID: CONNECT_ID; { id of local connection block }
CB$DST_CONNECT_ID: CONNECT_ID; { id of remote connection block }
CB$SRC_PROC_NAME: PROC_NAME; { local process name }
CB$DST_PROC_NAME: PROC_NAME; { remote process name }
SCS OPERATION Page 9-6
CB$CONNECT_DATA: C_DATA; { connection data }
CB$SRC_REASON: WORD; { local reason for reject or disconnect }
CB$DST_REASON: WORD; { remote reason for reject or disconnect }
CB$SEND_CREDIT: WORD; { number of available send credits }
CB$MIN_SEND_CREDIT: WORD; { protocol threshold }
CB$REC_CREDIT: WORD; { max. unused credits held by remote side }
CB$MIN_REC_CREDIT: WORD; { min. send credits needed by remote side }
CB$PEND_REC_CREDIT: WORD; { receive buffers queued, or cancels pending }
CB$REQ_CREDIT: WORD; { credits sent but not acknowledged }
CB$RET_CREDIT: WORD; { credits actually returned from remote side }
CB$RET_NULL: WORD; { credits requested but not returned from remote side }
CB$DG_REC: WORD; { number of datagram buffers queued }
CB$RESERVED: WORD; { unused }
CB$DST_SB: SB_INDEX; { system block for destination system }
CB$DST_PB: PB_INDEX; { path block for interconnect to destination }
CB$DG_Q: Q_BUF_PTR; { queue of DGREC responses }
CB$MSG_Q: Q_BUF_PTR; { queue of MSGREC responses }
CB$READ_Q: Q_BUF_PTR; { queue of DATREC responses }
CB$WRITE_Q: Q_BUF_PTR; { queue of CNFREC responses }
CB$DG_RET_Q: Q_BUF_PTR; { queue of DGSNT responses }
CB$MSG_RET_Q: Q_BUF_PTR { queue of MSGSNT responses }
end;
CB_Q_STATE = (FILLED,WAS_EMPTY,NOW_EMPTY); { connection block queue state }
RSP_TYPE = (DGREC,DGSNT,MSGREC,MSGSNT,DATREC,CNFREC,
IDREC,MDATREC,MCNFREC); { PPD response type }
START_DATA = packed array [1..36] of BYTE;
var CBA: array [1..MAX_CB] of CB; { connection blocks }
SBA: array [1..MAX_SB] of SB; { system blocks }
PBA: array [1..MAX_PB] of PB; { path blocks }
CUR_SB: WORD; { the highest current system list entry }
CUR_PB: WORD; { the highest current path list entry }
SCS_SEND_Q: SB_PTR; { SCS_SEND work queue }
function ALLOC_CB(
var CID:CONNECT_ID):
boolean;
begin
{ allocate connect block, initialize to zero,
set CB$NEXT_CB to point to itself,
set CB$BLOCK_STATE to ALLOC, and return CID:
return true if block allocated; false otherwise }
end;{ALLOC_CB}
SCS OPERATION Page 9-7
function CB_CLOSED( { test connection state }
CID: CONNECT_ID):
boolean;
begin
{return TRUE if connection is closed,
return FALSE otherwise }
end;{CB_CLOSED}
procedure CHOOSE_PATH( { select path to system }
ENTRY: SB_INDEX;
var PATH: PB_INDEX);
begin
{ select path over which connection to
specified system is to be attempted. }
end;{CHOOSE_PATH}
function PBPTR_TO_PBINDEX( { change pointer to index }
PTR: PB_PTR): PB_INDEX;
begin
{ calculate index from address pointer }
end;{PBPTR_TO_PBINDEX}
function NEXT_XID:
WORD;
begin
{ assign a new transaction number }
end;{NEXT_XID}
function CONNECT_MATCH(
PTR: Q_BUF_PTR;
var CNCT_INDEX: WORD):
boolean;
begin
{ search for connect block in LISTENING connect
state which matches the connect request: set CB$DST_SB, CB$DST_PB }
end;{CONNECT_MATCH}
function INSERT_CB_Q(
Q: CB_PTR;
SCS OPERATION Page 9-8
PTR: CB_PTR):
CB_Q_STATE;
begin
{ insert entry whose address is PTR in queue Q:
return WAS_EMPTY if queue was previously empty;
FILLED otherwise }
end;
function REMOVE_CB_Q(
Q: CB_PTR;
var PTR: CB_PTR):
CB_Q_STATE;
begin
{ remove entry from queue Q and return address in
PTR : return NOW_EMPTY if queue is now empty;
FILLED otherwise }
end;
procedure INSERT_SCS_Q(
INDEX: PB_INDEX);
begin
{ insert path block identified by INDEX
on the SCS_SEND_Q work queue }
end;{INSERT_SCS_Q}
function REMOVE_SCS_Q(
var PTR: PB_PTR):
boolean;
begin
{ remove an entry from the SCS_SEND_Q work queue and return
its address in PTR: return true if entry removed;
false otherwise }
end;{REMOVE_SCS_Q}
procedure INSERT(
Q: Q_BUF_PTR;
PTR: Q_BUF_PTR);
begin
{ insert entry whose address is PTR in queue Q }
end;{INSERT}
SCS OPERATION Page 9-9
function REMOVE(
Q: Q_BUF_PTR;
var PTR: Q_BUF_PTR):
boolean;
begin
{ remove entry from queue Q and return address of
entry in PTR: return true if entry removed;
false otherwise }
end;{REMOVE}
{SCSDEF}
SCS OPERATION Page 9-10
9.6 CONFIGURATION SERVICE
9.6.1 System Block
The system list is a data structure built and maintained by the PPD
layer and used by the SCS layer. An entry on the system list is
termed a system block. A representative system block has the
following format:
3
1 0
+-------------------------------+
| NEXT_SB |
+---------------+---------------+
|DST_PORT_COUNT |FIRST_PB_INDEX |
+-------------------------------+
| | RESERVED |
| +---------------+
| DST_SYS |
+---------------+---------------+
| DST_MAX_MSG | DST_MAX_DG |
+---------------+---------------+
| DST_SW_TYPE |
+-------------------------------+
| DST_SW_VERSION |
+-------------------------------+
| DST_SW_INCARNATION |
| |
+-------------------------------+
| DST_HW_TYPE |
+-------------------------------+
| |
= DST_HW_VERSION =
| |
+-------------------------------+
| NODE_NAME |
| |
+-------------------------------+
where:
NEXT_SB the address of the next system block on the the
SCS_SEND_Q.
FIRST_PB_INDEX path block index of the first path block for this
system.
DST_PORT_COUNT number of paths to the destination system.
RESERVED reserved word.
DST_SYS the destination system.
SCS OPERATION Page 9-11
DST_MAX_DG the maximum datagram size (in bytes) supported by
the system.
DST_MAX_MSG the maximum message size (in bytes) supported by
the system.
DST_SW_TYPE the 4-character ASCII type of the software in the
system.
DST_SW_VERSION the 4-character ASCII version number of the
software in the system.
DST_SW_INCARNATION (8 bytes) the incarnation number of the
software in the system.
DST_HW_TYPE the type of system hardware.
|
| DST_HW_VERSION (12 bytes) the version number of the system
| hardware.
NODE_NAME (8 bytes) the ASCII node name of the system.
SCS OPERATION Page 9-12
9.6.2 Path Block
The path block is a data structure containing information about a
single system-to-system path. That is, it describes one of
potentially several ports to a destination system.
3
1 0
+-------------------------------+
| SB | NEXT_PB |
+-------------------------------+
| | DST_VC_STATE |
| +---------------|
| DST_PORT |
+-------------------------------+
| DG_Q |
+-------------------------------+
| MSG_PTR |
+-------------------------------+
| CB_Q |
+---------------+---------------+
| |
= DST_PORT_CHAR =
| |
+-------------------------------+
NEXT_PB path block index of the next path to the
destination system.
SB system block index of the system block to which
this path block is queued.
DST_VC_STATE the state of the virtual circuit to the
destination port.
DST_PORT the destination system port address.
DG_Q the datagram return queue for maintenance
operations.
MSG_PTR the address of the local message buffer associated
with the port-to-port virtual circuit.
CB_Q the queue of connection blocks of connections
requiring SCS control message service.
DST_PORT_CHAR the characteristics of the destination port.
SCS OPERATION Page 9-13
9.6.3 Configuration Services
| REQ_ID REMOVED
function CONFIG_SYS(
ENTRY: SB_INDEX;
var FIRST_PB: PB_INDEX;
var SYS: SYSTEM;
var MAX_DG: WORD;
var MAX_MSG: WORD;
var SW_TYPE: LONG;
var SW_VERSION: LONG;
var SW_INCARNATION: QUAD;
var HW_TYPE: LONG;
var HW_VERSION: SEPTA;
var NODE_NAME: QUAD;
var PORT_COUNT: WORD):
FSTATUS;
{ Return information about destination SYSTEM from the
specified System Block. }
begin
if ENTRY <= CUR_SB then with SBA[ENTRY] do
begin
FIRST_PB:=SB$FIRST_PB;
SYS:=SB$DST_SYS;
MAX_DG:=SB$DST_MAX_DG;
MAX_MSG:=SB$DST_MAX_MSG;
SW_TYPE:=SB$DST_SW_TYPE;
SW_VERSION:=SB$DST_SW_VERSION;
SW_INCARNATION:=SB$DST_SW_INCAR;
HW_TYPE:=SB$DST_HW_TYPE;
HW_VERSION:=SB$DST_HW_VERSION;
NODE_NAME:=SB$DST_NODE_NAME;
PORT_COUNT:=SB$DST_PORT_COUNT;
CONFIG_SYS:=SUCCESS
end
else CONFIG_SYS:=FAIL
end;{CONFIG_SYS}
function CONFIG_PATH(
ENTRY: PB_INDEX;
var STATE: VC_STATE;
var PRT: PORT;
var NEXT_PB: PB_INDEX;
var SB: SB_INDEX;
var CHAR: PORT_CHAR):
FSTATUS;
{ Return information about the specified INTERCONNECT
from the specified Path Block. }
SCS OPERATION Page 9-14
begin
if ENTRY <= CUR_PB then with PBA[ENTRY] do
begin
STATE:=PB$DST_VC_STATE;
PRT:=PB$DST_PORT;
NEXT_PB:=PB$NEXT_PB;
SB:=PB$SB;
CHAR:=PB$DST_PORT_CHAR;
CONFIG_PATH:=SUCCESS
end
else CONFIG_PATH:=FAIL
end;{CONFIG_PATH}
SCS OPERATION Page 9-15
9.7 CONNECTION MANAGEMENT SERVICE
9.7.1 Connection Block
A representative connection block has the following format:
SCS OPERATION Page 9-16
3
1 0
+-------------------------------+
| NEXT_CB |
+---------------+---------------+
| BLOCK_STATE | CONNECT_STATE |
+---------------+---------------+
| SRC_CONNECT_ID |
+-------------------------------+
| DST_CONNECT_ID |
+-------------------------------+
| |
= SRC_PROC_NAME =
| |
+-------------------------------+
| |
= DST_PROC_NAME =
| |
+-------------------------------+
| |
= CONNECT-DATA =
| |
+---------------+---------------+
| DST_REASON | SRC_REASON |
+---------------+---------------+
|MIN_SEND_CREDIT| SEND_CREDIT |
+---------------+---------------+
|MIN_REC_CREDIT | REC_CREDIT |
+---------------+---------------+
| REQ_CREDIT |PEND_REC_CREDIT|
+---------------+---------------+
| RET_NULL | RET_CREDIT |
+---------------+---------------+
| RESERVED | DG_REC |
+---------------+---------------+
| DST_PB | DST_SB |
+---------------+---------------+
| DG_Q |
+-------------------------------+
| MSG_Q |
+-------------------------------+
| READ_Q |
+-------------------------------+
| WRITE_Q |
+-------------------------------+
| DG_RET_Q |
+-------------------------------+
| MSG_RET_Q |
+-------------------------------+
SCS OPERATION Page 9-17
where:
NEXT_CB the address of the next connection block on the
SCS send queue.
CONNECT_STATE the connection state.
BLOCK_STATE the state of the connection block.
SRC_CONNECT_ID the connect id of the local connection block.
DST_CONNECT_ID the connect id of destination connection block.
SRC_PROC_NAME the process name of local process allocating the
connection block.
DST_PROC_NAME the process name of destination process.
CONNECT_DATA connection data.
SRC_REASON the local reject or disconnect reason.
DST_REASON the destination reject or disconnect reason.
SEND_CREDIT the number of available credits to send.
MIN_SEND_CREDIT the SYSAP protocol threshold.
REC_CREDIT the upper bound of the number of unused send
credits held by the destination SYSAP process.
MIN_REC_CREDIT the minimum number of send credits needed by the
destination SYSAP process.
PEND_REC_CREDIT if non-negative, the number of buffers queued to
receive messages, but not yet credited to the
destination process; otherwise the negative of
the number of cancels not yet sent to the
destination process.
REQ_CREDIT the number of credits sent to the destination
process in a CREDIT_REQ, but not yet responded to
by a CREDIT_RSP.
RET_CREDIT the number of credits returned by the destination
as specified in the CREDIT_RSP.
RET_NULL the number of credits requested to be returned in
a CREDIT message but not returned in the
CREDIT_RSP.
DG_REC the number datagram buffers queued to receive
datagrams.
SCS OPERATION Page 9-18
RESERVED reserved word.
DST_SB system block corresponding to the destination
system.
DST_PB path block on which this connection is
established.
DG_Q the queue of DGREC responses.
MSG_Q the queue of MSGREC responses.
READ_Q the queue of DATREC responses.
WRITE_Q the queue of CNFREC responses.
DG_RET_Q the queue of DGSNT responses.
MSG_RET_Q the queue of MSGSNT response.
SCS OPERATION Page 9-19
9.7.2 Connection States
| A connection exists in 1 of several states: CLOSED, LISTEN,
| CONNECT_SENT, CONNECT_ACK, CONNECT_REC, ACCEPT_SENT, REJECT_SENT,
| OPEN, DISCONNECT_SENT, DISCONNECT_REC, DISCONNECT_ACK, and DISCONNECT
| MATCH. Events cause transitions between states. An event is either a
| connection management function call or receipt of a connection
| management control message.
|
| The connection state table follows:
|
| Current Event Action New
| State State
|
| CLOSED LISTEN call - LISTENING
| CONNECT call send CONNECT_REQ CONNECT_SENT
| *rcv CONNECT_REQ send CONNECT_RSP CLOSED
| with NO_MATCH
| *rcv ACCEPT_REQ send ACCEPT_RSP CLOSED
| with NO_MATCH
| DISCONNECT call nop CLOSED
|
| LISTENING rcv CONNECT_REQ send CONNECT_RSP CONNECT_REC
|
| DISCONNECT call cancel listen CLOSED
|
| CONNECT_SENT rcv CONNECT_RSP
| with SUCCESS await ACCEPT or CONNECT_ACK
| REJECT
| with NO_MATCH - CLOSED
| with NO_RESOURCES - CLOSED
|
| DISCONNECT call return success on CLOSED
| DISCONNECT, abort on
| CONNECT
|
| CONNECT_ACK rcv REJECT_REQ send REJECT_RSP CLOSED
| rcv ACCEPT_REQ send ACCEPT_RSP OPEN
| DISCONNECT call - CLOSED
|
| CONNECT_REC ACCEPT call send ACCPET_REQ ACCEPT_SENT
| REJECT call send REJECT_REQ REJECT_SENT
| DISCONNECT call send REJECT_REQ REJECT_SENT
|
| ACCEPT_SENT rcv ACCEPT_RSP
| with SUCCESS - OPEN
| with DISCONNECTED - CLOSED
|
| DISCONNECT call SUCCESS on DISCONNECT CLOSED
|
| ABORT on ACCEPT
|
| REJECT_SENT rcv REJECT_RSP - CLOSED
|
| DISCONNECT call SUCCESS on DISCONNECT CLOSED
SCS OPERATION Page 9-20
| SUCCESS on REJECT
|
| OPEN DISCONNECT call send DISCONNECT_REQ DISCONNECT_SENT
| rcv DISCONNECT_REQ send DISCONNECT_RSP DISCONNECT_REC
|
| DISCONNECT_SENT rcv DISCONNECT_REQ send DISCONNECT_RSP DISCONNECT_MATCH
| rcv DISCONNECT_RSP - DISCONNECT_ACK
|
| DISCONNECT call SUCCESS on both CLOSED
| DISCONNECTs
|
| DISCONNECT_REC DISCONNECT call Send DISCONNECT_REQ DISCONNECT_MATCH
|
| DISCONNECT_ACK rcv DISCONNECT_REQ send DISCONNECT_RSP CLOSED
|
| DISCONNECT call SUCCESS on both CLOSED
| DISCONNECTs
|
|
| DISCONNECT_MATCH
| rcv DISCONNECT_RSP - CLOSED
|
| DISCONNECT call SUCCESS on both CLOSED
| DISCONNECTs
|
|
|
| any non-CLOSED close port/port VC - CLOSED
|
| any state any inappropriate close port/port VC CLOSED
| event
|
The reason that ACCEPT/REJECT are separated from CONNECT_RSP is to
allow a system to initiate a potentially time consuming operation
(e.g. process creation) in response to an incoming CONNECT_REQ.
DISCONNECT_ACK and DISCONNECT_MATCH states are used to ensure that (1)
both sides wait until the passive SYSAP issues a DISCONNECT request,
and (2) both sides have acknowledged that they know the second
DISCONNECT was issued. At that point, no further transfer requests
can be issued by either side. To ensure that all messages in transit
when the DISCONNECT was issed have completed before the connection is
closed, all disconnect messages should be sent at lowest priority on
ports that implement multiple priority messages.
SCS OPERATION Page 9-21
9.7.3 Connect
| function CONNECT(
| var CID: CONNECT_ID;
| SRC_PROC: PROC_NAME;
| DST_PROC: PROC_NAME;
| DST: SB_INDEX;
| THRSH: WORD;
| { [CREDITS: Q_BUF_PTR];... }
| DATA: C_DATA
| { [PATH: PB_INDEX] }
| ):
| FSTATUS;
|
| begin
|
| { Allocate a connection block, fill in appropriate fields, and place
| on SCS work queue for processing. }
|
| if ALLOC_CB(CID) then with CBA[CID.INDEX] do
| begin
| CB$CONNECT_STATE:=CLOSED;
| CB$BLOCK_STATE:=CONNECT_PEND;
| CB$SRC_CONNECT_ID:=CID;
| CB$SRC_PROC_NAME:=SRC_PROC;
| CB$DST_PROC_NAME:=DST_PROC;
| CB$CONNECT_DATA:=DATA;
| CB$MIN_SEND_CREDIT:=THRSH;
| { CB$PEND_REC_CREDIT:= count of CREDITS;
| queue buffers with INSERT_MFREEQ }
| CB$DST_SB:=DST;
|
| { Select a path to destination and store path block index
| in CB. Insert CB on connection queue in chosen path block.
| If queue is currently empty, then place the PB on
| the SCS work queue for processing. }
|
| CHOOSE_PATH(DST,CB$DST_PB);
| if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
| then INSERT_SCS_Q(CB$DST_PB);
| CONNECT:=SUCCESS
| end
| else CONNECT:=FAIL
| end;{CONNECT}
SCS OPERATION Page 9-22
9.7.4 Listen
| function LISTEN(
| var CID: CONNECT_ID;
| SRC_PROC: PROC_NAME;
| DST_PROC: PROC_NAME;
| DST: SB_INDEX ):
| FSTATUS;
|
| { Allocate a connection block and initialize fields to
| indicate waiting for matching connection request. }
|
| begin
| if ALLOC_CB(CID) then with CBA[CID.INDEX] do
| begin
| CB$CONNECT_STATE:=LISTENING;
| CB$SRC_CONNECT_ID:=CID;
| CB$SRC_PROC_NAME:=SRC_PROC;
| CB$DST_PROC_NAME:=DST_PROC;
| CB$DST_SB:=DST;
| LISTEN:=SUCCESS
| end
| else LISTEN:=FAIL
| end{LISTEN};
9.7.5 Accept
| procedure ACCEPT(
| CID: CONNECT_ID;
| { [CREDITS: Q_BUF_PTR];...}
| THRSH : WORD;
| DATA: C_DATA);
|
| { Accept a connection request. Set CB$BLOCK_STATE for SCS_SEND
| process and insert PB on work queue. Queue some message buffers
| so credits can be extended.}
|
| begin with CBA[CID.INDEX] do
| begin
| CB$BLOCK_STATE:=ACCEPT_PEND;
| CB$CONNECT_DATA:=DATA;
| { CB$PEND_REC_CREDIT:= count of CREDITS;
| queue buffers with INSERT_MFREEQ }
| CB$MIN_SEND_CREDIT:=THRSH;
| if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
| then INSERT_SCS_Q(CB$DST_PB);
| end
| end;{ACCEPT}
SCS OPERATION Page 9-23
9.7.6 Reject
procedure REJECT(
CID: CONNECT_ID;
REASON: WORD);
{ Reject a connection request. Set CB$BLOCK_STATE for SCS_SEND
process, note reason for rejection, and queue PB for processing. }
begin with CBA[CID.INDEX] do
begin
CB$BLOCK_STATE:=REJECT_PEND;
CB$SRC_REASON:=REASON;
if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
then INSERT_SCS_Q(CB$DST_PB);
end
end;{REJECT}
9.7.7 Disconnect
procedure DISCONNECT(
CID: CONNECT_ID;
REASON: WORD);
{ Disconnect the connection. First, check to see if
the connection is in operation. If so, transmit the
DISCONNECT_REQ message and move to DISCONNECT_SENT state.
Otherwise, disconnection has already begun due to remote
disconnect request. Move to DISCONNECT_MATCH state and send
DISCONNECT_REQ message to notify the other side that local
SYSAP has disconnected. Set connection state, set block
state for SCS_SEND, and insert PB if needed for sending. }
begin
with CBA[CID.INDEX] do
begin
case CB$CONNECT_STATE of
OPEN:
begin
CB$CONNECT_STATE := DISCONNECT_SENT;
CB$BLOCK_STATE := DISCONNECT_PEND
end;
DISCONNECT_REC:
begin
CB$CONNECT_STATE := DISCONNECT_MATCH;
CB$BLOCK_STATE := DISCONNECT_PEND
end;
CONNECT_REC:
begin
SCS OPERATION Page 9-24
CB$CONNECT_STATE := REJECT_SENT;
CB$BLOCK_STATE := REJECT_PEND
end;
OTHERWISE
begin
CB$CONNECT_STATE := CLOSED;
CB$BLOCK_STATE := FREE
end;
end;
CB$SRC_REASON:=REASON;
if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
then INSERT_SCS_Q(CB$DST_PB)
end;
end;{DISCONNECT}
9.7.8 State Poll
procedure STATE_POLL(
CID: CONNECT_ID;
var STATE: C_STATE;
var DST_CID: CONNECT_ID;
var DST_PROC: PROC_NAME;
var DST_SB: SB_INDEX;
var DST_PB: PB_INDEX;
var DATA: C_DATA;
var REASON: WORD);
{ Return the state of a process-to-process connection}
begin with CBA[CID.INDEX] do
begin
STATE:=CB$CONNECT_STATE;
DST_CID:=CB$DST_CONNECT_ID;
DST_PROC:=CB$DST_PROC_NAME;
DST_SB:=CB$DST_SB;
DST_PB:=CB$DST_PB;
DATA:=CB$CONNECT_DATA;
REASON:=CB$DST_REASON
end
end;{STATE_POLL}
SCS OPERATION Page 9-25
9.8 DATAGRAM SERVICE
9.8.1 Send Datagram
function SEND_DG(
CID: CONNECT_ID;
RET_FLAG: boolean;
DLEN: APPL_DG_LEN;
PTR: Q_BUF_PTR):
FSTATUS;
{ Check to see that connection is still open. Fill in SCS header
information and call PPD send datagram. }
begin with CBA[CID.INDEX] do
if CB_CLOSED(CID) then SEND_DG:=NOT_OPEN else
begin
if not RET_FLAG then CB$DG_REC:=CB$DG_REC+1;
PTR^.LENGTH:=DLEN+AP_DG_HDR_LEN;
PTR^.SCS_TYPE:=APPL_DG;
PTR^.CREDIT:=0;
PTR^.REC_CONNECT_ID:=CB$DST_CONNECT_ID;
PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
SNDDG(CB$DST_PB,RET_FLAG,PTR);
SEND_DG:=SUCCESS
end
end;{SEND_DG}
9.8.2 Send Datagram Poll
function SEND_DG_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
{ Check datagram return queue for datagram transmission buffer
from previous send. }
begin with CBA[CID.INDEX] do
if REMOVE(CB$DG_RET_Q,PTR) then
SEND_DG_POLL:=SUCCESS
else SEND_DG_POLL:=FAIL
end;{SEND_DG_POLL}
SCS OPERATION Page 9-26
9.8.3 Receive Datagram
function REC_DG(
CID: CONNECT_ID;
PTR: Q_BUF_PTR):
FSTATUS;
{ Queue a buffer to the datagram receive queue. }
begin with CBA[CID.INDEX] do
if CB_CLOSED(CID) then REC_DG:=NOT_OPEN else
begin
CB$DG_REC:=CB$DG_REC+1;
INSERT_DFREEQ(PTR);
REC_DG:=SUCCESS;
end
end;{REC_DG}
9.8.4 Receive Datagram Poll
function REC_DG_POLL(
CID: CONNECT_ID;
var DLEN: APPL_DG_LEN;
var PTR: Q_BUF_PTR):
FSTATUS;
{ Check CB datagram queue and return datagram if any
have been received. }
begin with CBA[CID.INDEX] do if REMOVE(CB$DG_Q,PTR) then
begin
DLEN:=PTR^.LENGTH-AP_DG_HDR_LEN;
REC_DG_POLL:=SUCCESS
end
else
REC_DG_POLL:=FAIL
end;{REC_DG_POLL}
SCS OPERATION Page 9-27
9.8.5 Cancel Receive Datagram
function CANCEL_REC_DG(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
{ Return a queued datagram receive buffer. Function FAILS if
no buffers are queued for this connection or if the global
queue is empty. }
begin with CBA[CID.INDEX] do if CB$DG_REC > 0 then
if REMOVE_DFREEQ(PTR) = SUCCESS then
begin
CB$DG_REC:=CB$DG_REC-1;
CANCEL_REC_DG:=SUCCESS
end
else CANCEL_REC_DG:=FAIL
else CANCEL_REC_DG:=FAIL
end;{CANCEL_REC_DG}
SCS OPERATION Page 9-28
9.9 SEQUENTIAL MESSAGE SERVICE
9.9.1 Send Message
function SEND_MSG(
CID: CONNECT_ID;
THRSH: WORD;
RET_FLAG: boolean;
MLEN: APPL_MSG_LEN;
PTR: Q_BUF_PTR):
FSTATUS;
{ Check that connection is operating. Send Message if credits are
available. }
begin with CBA[CID.INDEX] do
if CB_CLOSED(CID) then SEND_MSG:=NOT_OPEN
else if CB$SEND_CREDIT > THRSH then
begin
CB$SEND_CREDIT:=CB$SEND_CREDIT-1;
{ If we're keeping this buffer, note one more credit to extend. }
if not RET_FLAG then CB$PEND_REC_CREDIT:=
CB$PEND_REC_CREDIT+1;
{ If we have extra receive buffers to report, update estimated
unused credits held by destination (CB$REC_CREDIT), send
the outstanding credits by placing in message CREDIT field,
and zero PENDING_REC_CREDIT to note that we're up to date. }
if CB$PEND_REC_CREDIT > 0 then
begin
CB$REC_CREDIT:=CB$REC_CREDIT+CB$PEND_REC_CREDIT;
PTR^.CREDIT:=CB$PEND_REC_CREDIT;
CB$PEND_REC_CREDIT:=0;
end
else
{ Otherwise, we have not reported some
cancelled buffers. }
begin
PTR^.CREDIT:=0;
CB$RET_CREDIT:=CB$RET_CREDIT+1
end;
{ Fill in SCS header and transmit messge. }
PTR^.LENGTH:=AP_MSG_HDR_LEN+MLEN;
PTR^.SCS_TYPE:=APPL_MSG;
PTR^.REC_CONNECT_ID:=CB$DST_CONNECT_ID;
PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
SCS OPERATION Page 9-29
SNDMSG(CB$DST_PB,RET_FLAG,PTR);
SEND_MSG:=SUCCESS
end
else
SEND_MSG:=FAIL
end;{SEND_MSG}
9.9.2 Send Message Poll
function SEND_MSG_POLL(
CID:CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
{ Check message return queue for received message }
begin with CBA[CID.INDEX] do
if REMOVE(CB$MSG_RET_Q,PTR) then
SEND_MSG_POLL:=SUCCESS
else SEND_MSG_POLL:=FAIL
end;{SEND_MSG_POLL}
9.9.3 Receive Message
function REC_MSG(
CID: CONNECT_ID;
PTR: Q_BUF_PTR):
FSTATUS;
{ Receive message. Check connection status, queue the supplied buffer,
and note that there is one more credit for the connection. }
begin with CBA[CID.INDEX] do if CB_CLOSED(CID)
then REC_MSG:=NOT_OPEN
else
begin
REC_MSG:=SUCCESS;
INSERT_MFREEQ(PTR);
CB$PEND_REC_CREDIT:=CB$PEND_REC_CREDIT+1;
{ If we were going to ask for credits back, note that we
got one back. }
if CB$PEND_REC_CREDIT <= 0 then
CB$RET_CREDIT:=CB$RET_CREDIT+1
{ If remote side is below threshold, send credit message now. }
else if CB$REC_CREDIT <= CB$MIN_REC_CREDIT then
SCS OPERATION Page 9-30
begin
if CB$BLOCK_STATE = ALLOC then
begin
CB$BLOCK_STATE:=CREDIT_PEND;
if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB)
= WAS_EMPTY then
INSERT_SCS_Q(CB$DST_PB);
end
end
end
end;{REC_MSG}
9.9.4 Receive Message Poll
function REC_MSG_POLL(
CID: CONNECT_ID;
var MLEN: APPL_MSG_LEN;
var PTR: Q_BUF_PTR):
FSTATUS;
{ Check for reception of a message. Return buffer and data length. }
begin with CBA[CID.INDEX] do if REMOVE(CB$MSG_Q,PTR) then
begin
MLEN:=PTR^.LENGTH-AP_MSG_HDR_LEN;
REC_MSG_POLL:=SUCCESS
end
else
REC_MSG_POLL:=FAIL
end;{REC_MSG_POLL}
SCS OPERATION Page 9-31
9.9.5 Cancel Receive Message
procedure CANCEL_REC_MSG(
CID: CONNECT_ID);
{ Cancel a receive message request. Note one less credit to send (or
one more to take back). If we're going to extend more credits then
note that we got one back (increment CB$RET_CREDIT) so that user will
get buffer back. Otherwise, prepare CB so that credit message will
be sent. The buffer is returned by calling CANCEL_REC_MSG_POLL. }
begin with CBA[CID.INDEX] do
begin
CB$PEND_REC_CREDIT:=CB$PEND_REC_CREDIT-1;
if CB$PEND_REC_CREDIT >= 0 then
CB$RET_CREDIT:=CB$RET_CREDIT+1
else
begin
if CB$BLOCK_STATE = ALLOC then
begin
CB$BLOCK_STATE:=CREDIT_PEND;
if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB)
= WAS_EMPTY then
INSERT_SCS_Q(CB$DST_PB);
end
end
end
end;{CANCEL_REC_MSG}
9.9.6 Cancel Receive Message Poll
function CANCEL_REC_MSG_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR):
FSTATUS;
{ Request return of buffers cancelled by CANCEL_REC_MESSAGE.
CB$RET_CREDIT indicates number of buffers that can be returned.
CB$RET_NULL indicates number of cancels requested but credits not
returned from remote side. Status of NULL indicates that the
cancel succeeded but the buffer can not be given back to the caller. }
begin with CBA[CID.INDEX] do
begin
if CB$RET_CREDIT > 0 then
begin
CB$RET_CREDIT:=CB$RET_CREDIT-1;
CANCEL_REC_MSG_POLL:=REMOVE_MFREEQ(PTR)
end
else if CB$RET_NULL > 0 then
begin
SCS OPERATION Page 9-32
CB$RET_NULL:=CB$RET_NULL-1;
CANCEL_REC_MSG_POLL:=NULL
end
else CANCEL_REC_MSG_POLL:=FAIL
end
end;{CANCEL_REC_MSG_POLL}
SCS OPERATION Page 9-33
9.10 BLOCK DATA SERVICE
9.10.1 Buffer Descriptor Table
The buffer descriptor table is a data structure maintained by the SCS
layer and readable by the PPD layer. The buffer descriptor table is
referenced by buffer name and contains the length, address, and access
control information for named buffers.
A representative buffer descriptor table entry has the following
format:
3
1 0
+-------------------------------+
| BUF_LENGTH |
+-------------------------------+
| BUF_ADDRESS |
+-------------------------------+
| BUF_ACCESS |
+-------------------------------+
where:
BUF_LENGTH the length of buffer.
BUF_ADDR the address of the buffer and/or buffer mapping
tables.
BUF_ACCESS the buffer access control.
SCS OPERATION Page 9-34
9.10.2 Map Buffer
function MAP(
{BLOCK_BUF: BUF_DESCR;}
var NAME: LONG):
FSTATUS;
begin
{fill in Buffer Descriptor Table entry
end return buffer name}
end;{MAP}
9.10.3 Unmap Buffer
procedure UNMAP(
NAME: LONG);
begin
{invalidate name and free Buffer Descriptor
Table entry}
end;{UNMAP}
9.10.4 Read
function READ(
CID: CONNECT_ID;
THRSH: WORD;
PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
{ Request block data transfer from destination. First check for
connection condition and sufficient credits to perform operation.
Assign a new transaction number for this transaction and return
it to caller. }
begin with CBA[CID.INDEX] do if CB_CLOSED(CID)
then READ:=NOT_OPEN
else if CB$SEND_CREDIT > THRSH then
begin
CB$SEND_CREDIT:=CB$SEND_CREDIT-1;
PTR^.SEND_BLOCK_ID:=CID.INDEX;
XID:=NEXT_XID;
PTR^.SEND_XID:=XID;
REQDAT(CB$DST_PB,PTR);
READ:=SUCCESS
end
else READ:=FAIL
SCS OPERATION Page 9-35
end;{READ}
9.10.5 Read Poll
function READ_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
{ Check for completion of read block transfer. }
begin with CBA[CID.INDEX] do if REMOVE(CB$READ_Q,PTR) then
begin
XID:= PTR^.SEND_XID;
READ_POLL:=SUCCESS;
end
else READ_POLL:=FAIL;
end{READ_POLL};
9.10.6 Write
function WRITE(
CID: CONNECT_ID;
THRSH: WORD;
PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
{ Request block data transfer to destination system. Verify that
connection is open, assign a new transaction number, and call
PPD routine to perform the transfer. }
begin with CBA[CID.INDEX] do if CB_CLOSED(CID)
then WRITE:=NOT_OPEN
else if CB$SEND_CREDIT > THRSH then
begin
CB$SEND_CREDIT:=CB$SEND_CREDIT-1;
PTR^.SEND_BLOCK_ID:=CID.INDEX;
XID:=NEXT_XID;
PTR^.SEND_XID:=XID;
SNDDAT(CB$DST_PB,PTR);
WRITE:=SUCCESS
end
else WRITE:=FAIL
end;{WRITE}
SCS OPERATION Page 9-36
9.10.7 Write Poll
function WRITE_POLL(
CID: CONNECT_ID;
var PTR: Q_BUF_PTR;
var XID: WORD):
FSTATUS;
{ Check for completion of write block transfer. }
begin with CBA[CID.INDEX] do if REMOVE(CB$WRITE_Q,PTR) then
begin
XID:=PTR^.SEND_XID;
WRITE_POLL:= SUCCESS
end
else WRITE_POLL:=FAIL
end{WRITE_POLL};
SCS OPERATION Page 9-37
9.11 SCS SEND
| procedure SCS_SEND; {PROCESS}
|
| var PTR: PB_PTR;
|
| { SCS work queue process to send SCS command messages. Path blocks
| are queued to the work queue when a command is to be sent for
| a connection. The CB$BLOCK_STATE field of the first connect
| block queued to the PB specifies the work to be performed.
| A control message is constructed in the single SCS command buffer
| queued to the path block (PB), and the message is transmitted. }
|
| begin
|
| { Get next path block address in PTR. Dispatch on block state. }
|
| while REMOVE_SCS_Q(PTR) do with PTR^ do begin
| case PB$CB_Q^.CB$BLOCK_STATE of
|
| CONNECT_PEND:
|
| { Prepare Connect Request Message. Fill in number of credits
| now available (CB$PEND_REC_CREDIT) and the minimum number
| of credits needed by destination (CB$MIN_REC_CREDIT). }
|
| begin
| PB$MSG_PTR^.LENGTH:=CONNECT_REQ_LEN;
| PB$MSG_PTR^.SCS_TYPE:=CONNECT_REQ;
| PB$MSG_PTR^.CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
| { Update CB to note credits extended }
| PB$CB_Q^.CB$PEND_REC_CREDIT:=0;
| PB$MSG_PTR^.MIN_CREDIT:=PB$CB_Q^.CB$MIN_REC_CREDIT;
| PB$MSG_PTR^.STATUS:=0;
| PB$MSG_PTR^.REC_PROC:=PB$CB_Q^.CB$DST_PROC_NAME;
| PB$MSG_PTR^.SEND_PROC:=PB$CB_Q^.CB$SRC_PROC_NAME;
| PB$MSG_PTR^.SEND_DATA:=PB$CB_Q^.CB$CONNECT_DATA;
| PB$CB_Q^.CB$CONNECT_STATE:=CONNECT_SENT
| end;
|
| ACCEPT_PEND:
|
| { Prepare Accept message. Fill in number of credits
| now available (CB$PEND_REC_CREDIT) and the minimum number
| of credits needed by destination (CB$MIN_REC_CREDIT). }
|
| begin
| PB$MSG_PTR^.LENGTH:=ACCEPT_REQ_LEN;
| PB$MSG_PTR^.SCS_TYPE:=ACCEPT_REQ;
| PB$MSG_PTR^.CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
| { Update CB to note credits extended }
| PB$CB_Q^.CB$PEND_REC_CREDIT:=0;
| PB$MSG_PTR^.MIN_CREDIT:=PB$CB_Q^.CB$MIN_REC_CREDIT;
| PB$MSG_PTR^.STATUS:=0;
| PB$MSG_PTR^.REC_PROC:=PB$CB_Q^.CB$DST_PROC_NAME;
SCS OPERATION Page 9-38
| PB$MSG_PTR^.SEND_PROC:=PB$CB_Q^.CB$SRC_PROC_NAME;
| PB$MSG_PTR^.SEND_DATA:=PB$CB_Q^.CB$CONNECT_DATA;
| PB$CB_Q^.CB$CONNECT_STATE:=ACCEPT_SENT
| end;
|
| REJECT_PEND:
|
| { Prepare Reject message with reason for rejection.
| Give no credits (adding insult to injury). }
|
| begin
| PB$MSG_PTR^.LENGTH:=REJECT_REQ_LEN;
| PB$MSG_PTR^.SCS_TYPE:=REJECT_REQ;
| PB$MSG_PTR^.CREDIT:=0;
| PB$MSG_PTR^.MIN_CREDIT:=0;
| PB$MSG_PTR^.STATUS:=PB$CB_Q^.CB$SRC_REASON;
| PB$CB_Q^.CB$CONNECT_STATE:=REJECT_SENT
| end;
|
| DISCONNECT_PEND:
|
| { Prepare Disconnect Request message. Connection state has
| already been set to DISCONNECT_SENT or DISCONNECT_MATCH. }
|
| begin
| PB$MSG_PTR^.LENGTH:=DISCON_REQ_LEN;
| PB$MSG_PTR^.SCS_TYPE:=DISCON_REQ;
| PB$MSG_PTR^.CREDIT:=0;
| PB$MSG_PTR^.MIN_CREDIT:=0;
| PB$MSG_PTR^.STATUS:=PB$CB_Q^.CB$SRC_REASON
| end;
|
| CREDIT_PEND:
|
| { Prepare credit message. }
|
| begin
| PB$MSG_PTR^.LENGTH:=CREDIT_REQ_LEN;
| PB$MSG_PTR^.SCS_TYPE:=CREDIT_REQ;
| PB$MSG_PTR^.CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
| PB$CB_Q^.CB$REQ_CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
| PB$CB_Q^.CB$PEND_REC_CREDIT:=0
| end;
| end;
|
| { Now that message has been prepared, fill in source and
| destination connect ID and send the message. }
|
| PB$MSG_PTR^.REC_CONNECT_ID:=PB$CB_Q^.CB$DST_CONNECT_ID;
| PB$MSG_PTR^.SEND_CONNECT_ID:=PB$CB_Q^.CB$SRC_CONNECT_ID;
| { must convert PTR to a PB Index for SNDMSG call }
| SNDMSG( PBPTR_TO_PBINDEX(PTR) , false , PB$MSG_PTR);
| end;
| end;{SCS_SEND}
SCS OPERATION Page 9-39
9.12 SCS RECEIVE
| procedure SCS_REC; {PROCESS}
|
| var PTR: Q_BUF_PTR;
| RSP: RSP_TYPE;
| CNCT_INDEX: WORD;
| DST: PB_INDEX;
|
| { Process to handle reception of messages, datagrams, and command
| responses. There is a single SCS command buffer for each
| port-to-port virtual circuit. Therefore, only one command can be
| outstanding per path block. The buffer is consumed when an SCS
| command is transmitted. When a response is received, the buffer
| containing the response can be used to transmit another command.
| This is done immediately if an immediate response is required.
| Otherwise, the buffer is queued to the PB, and if any other CBs
| are waiting on the PB, the PB is queued to the send work queue
| for service. }
|
| begin
| while RSP_POLL(RSP,DST,PTR) = SUCCESS do case RSP of
|
| { PTR now has address of a buffer (Q_BUF_PTR)
| that has been received. Dispatch on the type
| of response received. If DGSNT or MSGSNT response,
| insert buffer on DG or MSG response queue. }
|
| DGSNT:
| INSERT(CBA[PTR^.SEND_CONNECT_ID.INDEX].CB$DG_RET_Q,PTR);
|
| MSGSNT:
| INSERT(CBA[PTR^.SEND_CONNECT_ID.INDEX].CB$MSG_RET_Q,PTR);
|
|
| DGREC:
|
| { Datagram received. If receive queue has a buffer, insert
| datagram on CB and note one less buffer available. Otherwise,
| return buffer to datagram receive queue. }
|
| with CBA[PTR^.REC_CONNECT_ID.INDEX] do if CB$DG_REC > 0
| then
| begin
| CB$DG_REC:=CB$DG_REC-1;
| INSERT(CB$DG_Q,PTR)
| end
| else INSERT_DFREEQ(PTR);
|
| MSGREC:
|
| { Message received. Locate CB for the message and dispatch
| on the SCS message type. }
|
| with CBA[PTR^.REC_CONNECT_ID.INDEX]
SCS OPERATION Page 9-40
| DO case PTR^.SCS_TYPE of
|
| { begin new case block }
|
| CONNECT_REQ:
|
| { Connect request recieved. Check if this conect
| matches a pending Listen request. If so, initialize
| credit and name fields. Return the Connect Response
| message with proper status. }
|
| begin
| if CONNECT_MATCH(PTR,CNCT_INDEX) then
| with CBA[CNCT_INDEX] do
| begin
| CB$CONNECT_STATE:=CONNECT_REC;
| CB$SEND_CREDIT:=PTR^.CREDIT;
| CB$DST_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
| CB$DST_PROC_NAME:=PTR^.SEND_PROC;
| CB$MIN_REC_CREDIT:=PTR^.MIN_CREDIT;
| CB$CONNECT_DATA:=PTR^.SEND_DATA;
| PTR^.STATUS:=CONNECTED
| end
| else PTR^.STATUS:=NO_MATCH;
| PTR^.LENGTH:=CONNECT_RSP_LEN;
| PTR^.SCS_TYPE:=CONNECT_RSP;
| PTR^.CREDIT:=0;
| PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
| PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
| PTR^.MIN_CREDIT:=0;
| SNDMSG(DST,false,PTR)
| end;
|
| CONNECT_RSP:
|
| { Connect response received. Note whether connect was
| processed or no matching listen was found. Restore the
| message buffer for this PB, remove CB from queue, and
| reinsert PB on work queue if more CB's are waiting. }
|
| begin
| if PTR^.STATUS = CONNECTED then
| CB$CONNECT_STATE:=CONNECT_ACK
| else
| begin
| CB$CONNECT_STATE:=CLOSED;
| CB$DST_REASON := PTR^.STATUS
| end;
| PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
| if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <> NOW_EMPTY
| then INSERT_SCS_Q(CB$DST_PB);
| end;
|
| ACCEPT_REQ:
|
SCS OPERATION Page 9-41
| { Accept Request received. Open connection and
| initialize credit and connect data information. Send
| The Accept Response message. }
|
| begin
| CB$SEND_CREDIT:=PTR^.CREDIT;
| CB$MIN_REC_CREDIT:=PTR^.MIN_CREDIT;
| CB$CONNECT_STATE:=OPEN;
| CB$CONNECT_DATA:=PTR^.SEND_DATA;
| PTR^.LENGTH:=ACCEPT_RSP_LEN;
| PTR^.SCS_TYPE:=ACCEPT_RSP;
| PTR^.CREDIT:=0;
| PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
| PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
| SNDMSG(DST,false,PTR)
| end;
|
| ACCEPT_RSP:
|
| { Accept Response message received. Save our message buffer,
| remove CB from queue, and requeue PB if more to do for this
| path. }
|
| begin
| CB$CONNECT_STATE:=OPEN;
| PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
| if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <> NOW_EMPTY
| then INSERT_SCS_Q(CB$DST_PB);
| end;
|
| REJECT_REQ:
|
| { Reject Request received. Close the channel, save the reject
| reason, and send the Reject Response message. }
|
| begin
| CB$CONNECT_STATE:=CLOSED;
| CB$DST_REASON:=PTR^.STATUS;
| PTR^.LENGTH:=REJECT_RSP_LEN;
| PTR^.SCS_TYPE:=REJECT_RSP;
| PTR^.CREDIT:=0;
| PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
| PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
| SNDMSG(DST,false,PTR)
| end;
|
| REJECT_RSP:
|
| { Reject Response received. Save our SCS message buffer
| and check if more work for this PB. }
|
| begin
| CB$CONNECT_STATE:=CLOSED;
| PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
| if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <> NOW_EMPTY
SCS OPERATION Page 9-42
| then INSERT_SCS_Q(CB$DST_PB);
| end;
|
| DISCON_REQ:
|
| { Disconnect request received. The connection can be in
| one of three states: OPEN, DISCONNECT_SENT, or DISCONNECT_ACK.
| For each state, set the correct new state. For OPEN or
| DISCONNECT_SENT states, a DISCONNECT_RSP message must
| be transmitted. A DISCONNECT_REQ message received while in
| DISCONNECT_SENT state means that both SYSAPS initated
| disconnection simultaneously. If the connection is in
| DISCONNECT_ACK state, the connection is closed, the message
| buffer is saved, and the queue is checked for more work. }
|
| begin
| case CB$CONNECT_STATE of
| OPEN: CB$CONNECT_STATE:=DISCONNECT_REC;
| DISCONNECT_SENT: CB$CONNECT_STATE:=DISCONNECT_MATCH;
| DISCONNECT_ACK: CB$CONNECT_STATE:=CLOSED
| end;
|
| if CB$CONNECT_STATE=CLOSED
| then
| begin
| PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
| if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <>
| NOW_EMPTY then INSERT_SCS_Q(CB$DST_PB)
| end
| else
| begin
| CB$DST_REASON:=PTR^.STATUS;
| PTR^.LENGTH:=DISCON_RSP_LEN;
| PTR^.SCS_TYPE:=DISCON_RSP;
| PTR^.CREDIT:=0;
| PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
| PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
| SNDMSG(DST,false,PTR)
| end
| end;
|
| DISCON_RSP:
|
| { Disconnect Response received. The connection can be
| in one of two states. If in DISCONNECT_SENT state, we initiated
| the disconnect, and now move to DISCONNECT_ACK to wait for
| the remote SYSAP to disconnect. If in DISCONNECT_MATCH state,
| we're waiting for confirmation that the initator knows that
| we've received the passive SYSAP disconnect. Here we close
| down the connection and look for more work to do. }
|
| begin
| if CB$CONNECT_STATE = DISCONNECT_SENT
| then
| begin
SCS OPERATION Page 9-43
| CB$CONNECT_STATE:= DISCONNECT_ACK;
| CB$DST_REASON:=PTR^.STATUS;
| PTR^.LENGTH:=DISCON_RSP_LEN;
| PTR^.SCS_TYPE:=DISCON_RSP;
| PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
| PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
| SNDMSG(DST,false,PTR)
| end
| else { CB$CONNECT_STATE = DISCONNECT_MATCH }
| begin
| CB$CONNECT_STATE:=CLOSED;
| PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
| if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <>
| NOW_EMPTY then INSERT_SCS_Q(CB$DST_PB)
| end
| end;
|
| CREDIT_REQ:
|
| { Credit Request received. Credit request can be positive
| (to indicate more credits) or negative (to take some back).
| If negative, only give back the minimum of the number
| requested and the number available without going below
| the SCS threshold for this connection. Return
| Credit Response message. }
|
| begin
| if PTR^.CREDIT < 0
| then PTR^.CREDIT:=
| -MIN( MAX(0,CB$SEND_CREDIT-CB$MIN_SEND_CREDIT),
| -PTR^.CREDIT);
|
| { make positive or negative adjustment }
|
| CB$SEND_CREDIT:=CB$SEND_CREDIT+PTR^.CREDIT;
| PTR^.LENGTH:=CREDIT_RSP_LEN;
| PTR^.SCS_TYPE:=CREDIT_RSP;
| PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
| PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
| SNDMSG(DST,false,PTR)
| end;
|
| CREDIT_RSP:
|
| { Credit Response received. Adjust credit values for
| number actually returned, if credit return was requested. }
|
| begin
| if CB$REQ_CREDIT < 0 then
| begin
| CB$RET_CREDIT:=CB$RET_CREDIT-PTR^.CREDIT;
| CB$RET_NULL:=CB$RET_NULL+PTR^.CREDIT-CB$REQ_CREDIT;
| end;
| CB$REC_CREDIT:=CB$REC_CREDIT+PTR^.CREDIT;
| PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
SCS OPERATION Page 9-44
|
| { If credits are waiting to be taken back from the destination
| due to cancels, OR if there are buffers not credited AND
| the destination is below threshold, then insert this PB
| on the work queue to send the credit message. }
|
| if (CB$PEND_REC_CREDIT < 0) or
| ((CB$PEND_REC_CREDIT > 0) and
| (CB$REC_CREDIT < CB$MIN_REC_CREDIT)) then
| INSERT_SCS_Q(CB$DST_PB)
|
| { Otherwise, just check to see if there's anything else to do. }
|
| else if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <>
| NOW_EMPTY then INSERT_SCS_Q(CB$DST_PB)
| end;
|
| APPL_MSG:
|
| { Application Message received. Insert on message queue for
| this connection. }
|
| begin
| CB$REC_CREDIT:=CB$REC_CREDIT-1;
| CB$SEND_CREDIT:=CB$SEND_CREDIT+PTR^.CREDIT;
| INSERT(CB$MSG_Q,PTR)
| end;
|
| end;{case PTR^.SCS_TYPE}
|
|
| DATREC:
| with CBA[PTR^.SEND_BLOCK_ID] do begin
| INSERT(CB$READ_Q,PTR);
| CB$SEND_CREDIT:=CB$SEND_CREDIT+1;
| end;
|
| CNFREC:
| with CBA[PTR^.SEND_BLOCK_ID] do begin
| INSERT(CB$WRITE_Q,PTR);
| CB$SEND_CREDIT:= CB$SEND_CREDIT+1;
| end;
|
| IDREC:
| {if <id indicates a maintenance state> then
| PBA[PTR^.SEND_BLOCK_ID].PB$DST_VC_STATE:=
| MAINT
| else if PBA[PTR^.SEND_BLOCK_ID].PB$DST_VC_STATE =
| CLOSED then VC_START( )}
| INSERT(PBA[PTR^.SEND_BLOCK_ID].PB$DG_Q,PTR);
|
| MDATREC,
| MCNFREC:
| INSERT(PBA[PTR^.SEND_BLOCK_ID].PB$DG_Q,PTR);
|
SCS OPERATION Page 9-45
| end;{case RSP}
| end;{SCS_REC}
CHAPTER 10
CI PPD OPERATION
The operation of the PPD layer is port specific. This section
describes the operation of the CI PPD layer.
10.1 PPD DATAGRAMS
10.1.1 Start
The START datagram is used to start virtual circuit initialization.
The format of START is:
3 1
1 5 0
+---------------+---------------+
| PPD_TYPE | LENGTH |
+---------------+---------------+
| |
= START_DATA =
| |
+-------------------------------+
where:
LENGTH START_LEN.
PPD_TYPE START.
START_DATA start data. See Appendix F.
CI PPD OPERATION Page 10-2
10.1.2 Start Acknowledge
The STACK datagram is used to acknowledge receipt of a START. The
format of STACK is:
3 1
1 5 0
+---------------+---------------+
| PPD_TYPE | LENGTH |
+---------------+---------------+
| |
= START_DATA =
| |
+-------------------------------+
where:
LENGTH STACK_LEN.
PPD_TPE STACK.
START_DATA start data. See Appendix F.
CI PPD OPERATION Page 10-3
10.1.3 Acknowledge
The ACK datagram is used to acknowledge the receipt of a STACK. The
format of ACK is:
3 1
1 5 0
+---------------+---------------+
| PPD_TYPE | LENGTH |
+---------------+---------------+
where:
LENGTH ACK_LEN.
PPD_TYPE ACK.
CI PPD OPERATION Page 10-4
10.2 START VIRTUAL CIRCUIT
A virtual circuit exists in one of four states: VC_CLOSED,
START_SENT, START_REC, and VC_OPEN. The state is stored in the
appropriate system block. Events cause transitions between states.
An event is either an initialization function call, a timer
expiration, or receipt of a virtual circuit initialization datagram.
The initialization sequence is a standard 3-way handshake (used, for
example, by DECNET/DNA DDCMP).
The initialization state table follows:
CURRENT STATE EVENT ACTION NEW STATE
VC_CLOSED START call send START START_SENT
start timer
START_SENT rec STACK open port VC VC_OPEN
send ACK
stop timer
rec START open port VC START_REC
send STACK
start timer
timer expires send START START_SENT
start timer
START_REC rec ACK stop timer VC_OPEN
rec SCS request stop timer VC_OPEN
control message
rec STACK send ACK VC_OPEN
stop timer
rec START send STACK START_REC
start timer
timer expires send STACK START_REC
start timer
VC_OPEN rec START close port VC VC_CLOSED
notify SCS
rec STACK send ACK VC_OPEN
rec ACK - VC_OPEN
VC failure notify SCS VC_CLOSED
detected
CI PPD OPERATION Page 10-5
Notes:
|
| 1. The initial value of the timer is at least one second.
2. The port VC is opened and closed using the SETCKT command.
CI PPD OPERATION Page 10-6
10.3 CONFIGURATION
| The system list is built by the PPD layer polling with REQID port
| functions directed to all possible destination ports. The IDREC
| responses are used to fill in the system blocks. This procedure is
| repeated periodically to insure that the system list is current.
| Also, any unsolicited IDREC responses received are used to fill in the
| system blocks and path blocks.
10.4 OTHER PPD INTERFACE FUNCTIONS
The other PPD interface functions and procedures are in one-to-one
correspondence with CI port commands and responses.
CHAPTER 11
NI PPD OPERATION
\TBS\
CHAPTER 12
BI PPD OPERATION
\TBS\
APPENDIX A
PROCESS NAMING
A process name is a 16 byte string. A process name starts with an
upper case letter (A-Z) or a dollar sign ($). The remaining
characters can be upper case letters, numbers (0-9), dollar signs, or
underlines (_) except that the last character cannot be an underline.
Blank () characters are added to the end of the string if necessary to
fill the string to 16 characters.
It is intended in SCA that process names be human understandable. The
preferred structure for naming is as follows:
<generic facility name>$<generic service name>
Examples of names are:
MSCP$DISK - MSCP disk service.
MSCP$TAPE - MSCP tape service.
SCS$DIRECTORY - SCS process name directory service.
APPENDIX B
DIRECTORY SERVICE
B.1 INTRODUCTION
Each system maintains a directory process with process name
SCS$DIRECTORY.
SYSAP processes can obtain a directory of processes in a destination
system by connecting to the directory process in the destination
system.
B.2 LOCAL DIRECTORY MANAGEMENT
Process names are entered in and deleted from the local directory
using SCS level function calls of the same form as the SCS or PPD
interface.
B.2.1 Enter
This function enters process name in the local directory:
function ENTER(
PROC: PROC_NAME,
INFO: PROC_INFO):
FSTATUS;
where:
PROC the process name to be entered.
INFO (16 bytes) additional process information.
FSTATUS SUCCESS if name entered; FAIL otherwise.
DIRECTORY SERVICE Page B-2
B.2.2 Delete
This function deletes a process name from the local directory:
function DELETE(
PROC: PROC_NAME):
FSTATUS;
where:
PROC process name to be deleted.
FSTATUS SUCCESS if process name in directory; FAIL
otherwise.
B.3 REMOTE DIRECTORY ACCESS
After connecting to the remote directory process, the SYSAP sends an
application message containing a lookup request. The directory
process returns a lookup response application message containing the
result of the lookup operation.
DIRECTORY SERVICE Page B-3
B.3.1 Lookup Request
The format of the message is:
3 1
1 5 0
+---------------+---------------+
| ENTRY | FORM |
+---------------+---------------+
| |
= PROC_NAME =
| |
+-------------------------------+
where:
FORM the form of directory lookup (BY_NAME, BY_ENTRY)
BY_NAME = 0, BY_ENTRY = 1.
ENTRY the entry number if BY_ENTRY; ignored otherwise:
entries start at one.
PROC_NAME the process name if BY_NAME; ignored otherwise.
|
| BY_ENTRY lookup is used to obtain a complete list of directory
| entires. This is done by specifying entry one and then succeeding
| entry numbers until a failure status is returned indicating there are
| no more entries. Entry numbers are densely assigned.
DIRECTORY SERVICE Page B-4
B.3.2 Lookup Response
The format of the message is:
3 1
1 5 0
+---------------+---------------+
| ENTRY | STATUS |
+---------------+---------------+
| |
= PROC_NAME =
| |
+-------------------------------+
| |
= PROC_INFO =
| |
+-------------------------------+
where:
STATUS SUCCESS if a directory name found; FAIL
otherwise.
ENTRY if SUCCESS, the entry number; UNPREDICTABLE
otherwise.
PROC_NAME if SUCCESS, the process name; UNPREDICTABLE
otherwise.
PROC_INFO (16 bytes) if SUCCESS, additional process information;
UNPREDICTABLE otherwise.
APPENDIX C
THIRD PARTY I/O
Third party I/O is an I/O operation involving three or more systems.
Consider the following:
CI
--------------+---------------+---------------+--------------
| | |
| | |
+-------+------+ +------+------+ +------+-------+
| system X(U) | | system Y(F) | | system Z(D) |
+--------------+ +-------------+ +--------------+
System X contains a file user process U. System Y contains a file
server process F. System Z contains a disk server process D for the
disks storing the file system. For D to directly read block data from
U or write block data to U for file operations the following steps
apply:
1. Process U connects to F requesting file services.
2. F sends to U the identity of Z and D and requests U to
connect to D.
3. U sends to F the <D connect id, U connect id> pair.
4. F requests D to perform block data operations directly to U
by passing (in a higher level protocol such as MSCP) a 96-bit
qualified buffer name of the following format:
THIRD PARTY I/O Page C-2
3
1 0
+-------------------------------+
| SRC_CONNECT_ID |
+-------------------------------+
| DST_CONNECT_ID |
+-------------------------------+
| NAME |
+-------------------------------+
where:
SRC_CONNECT_ID the connect id of the process initiating the block
data transfers (in this example D).
DST_CONNECT_ID the connect id of the target of the block data
transfers (in this example U).
NAME the buffer name of the target of the block data
transfers (in this example U).
APPENDIX D
SCS/PPD TYPE AND LENGTH CODES
| {SCSPPDDEF}
|
| { Define SCS message types codes. }
|
| CONNECT_REQ = 0; { connect message }
|
| CONNECT_RSP = 1; { connect response }
|
| ACCEPT_REQ = 2; { accept connection }
|
| ACCEPT_RSP = 3; { accept response }
|
| REJECT_REQ = 4; { reject connection }
|
| REJECT_RSP = 5; { reject response }
|
| DISCON_REQ = 6; { disconnect message }
|
| DISCON_RSP = 7; { disconnect response }
|
| CREDIT_REQ = 8; { extend/retract credits }
|
| CREDIT_RSP = 9; { credit response }
|
| APPL_MSG = 10; { application message }
|
| APPL_DG = 11; { application datagram }
|
| { Define PPD message type codes. }
|
| START = 0; { start virtual circuit }
|
| STACK = 1; { acknowledge START }
|
| ACK = 2; { acknowledge STACK }
|
| SCS_DG = 3; { SCS datagram }
|
| SCS_MSG = 4; { SCS message }
SCS/PPD TYPE AND LENGTH CODES Page D-2
|
| { PPD message types with the sign bit set are reserved for }
| { implementation use and are not part of the protocol over }
| { the interconnect. }
|
| { Define SCS/PPD message lengths }
|
| CONNECT_REQ_LEN = 66;
|
| CONNECT_RSP_LEN = 18;
|
| ACCEPT_REQ_LEN = 66;
|
| ACCEPT_RSP_LEN = 18;
|
| REJECT_REQ_LEN = 18;
|
| REJECT_RSP_LEN = 14;
|
| DISCON_REQ_LEN = 18;
|
| DISCON_RSP_LEN = 14;
|
| CREDIT_REQ_LEN = 18;
|
| CREDIT_RSP_LEN = 14;
|
| AP_MSG_HDR_LEN = 14;
|
| AP_DG_HDR_LEN = 14;
|
| START_LEN = 42;
|
| STACK_LEN = 42;
|
| ACK_LEN = 6; {SCSPPDEND}
APPENDIX E
REJECTION AND DISCONNECTION REASON CODES
| There is no guarantee that additional assigned codes are contiguously
| assigned. All unassigned values are reserved for SYSAP private use
| and their use may overlap between different SYSAP protocols. Common
| useage is encouraged, however.
| {CONREJDEF}
|
| { Connection accept/reject reason codes. }
|
| { Message codes have two fields. The lower three bits are }
| { the severity and the bits 3-15 are the code. }
|
| { Severity values }
|
| { 0 = warning }
| { 1 = success }
| { 2 = error }
| { 3 = reserved }
| { 4 = severe error }
| { 5 - 7 = reserved }
|
| CONNECTED = 1; { general success }
|
| NO_MATCH = 10; { no matching listen found }
|
| NO_RESOURCES = 18; { no resources available to process request }
|
| DISCONNECTED = 26; { connection has been broken }
|
| RESERVED = 34; { RESERVED }
|
| {CONREJEND}
APPENDIX F
CI START DATA FORMAT
|
| 3
| 1 0
| +-------------------------------+
| | PPD MTYPE | LENGTH |
| +-------------------------------+
| | SEND_SYS |
| +---------------+ |
| | MBZ | PRTVRS| |
| +---------------+---------------+
| | MAX_MSG | MAX_DG |
| +---------------+---------------+
| | SW_TYPE |
| +-------------------------------+
| | SW_VERSION |
| +-------------------------------+
| | SW_INCARNATION |
| | |
| +-------------------------------+
| | HW_TYPE |
| +-------------------------------+
| | |
| = HW_VERSION =
| | |
| +-------------------------------+
| | NODE_NAME |
| | |
| +-------------------------------+
| | CUR_TIME |
| | |
| +-------------------------------+
|
where:
SEND_SYS the system address of the system sending the start
data.
CI START DATA FORMAT Page F-2
| PRTVRS protocol version (MBZ at this time).
MAX_DG the maximum datagram size (in bytes) supported by
the system.
MAX_MSG the maximum message size (in bytes) supported by
the system.
SW_TYPE the type of the software in the system. Currently
defined are 'VMS ','T-10', and 'T-20'.
SW_VERSION the version number of the software in the system.
SW_INCARNATION (8 bytes) the incarnation number of the software
in the system.
HW_TYPE the type of system hardware.
|
| HW_VERSION (12 bytes) the version number of the system
| hardware.
NODE_NAME (8 bytes) the ASCII node name of the system
sending the message.
CUR_TIME (8 bytes) the 64-bit current system time on the
system sending the message.
APPENDIX G
EXAMPLE CI MESSAGE
The following figure shows a SYSAP message and its encapsulation
inside of SCS, PPD, and CI Port layer headers. This figure represents
the send message command as presented to the CI port command queue.
The double lines indicate layer boundaries.
3 2 1
1 3 5 7 0
+-------------------------------+
| FLINK |
+-------------------------------+
| BLINK |
+-------+-------+---------------+ CI PORT HEADER
|SWFLAG | TYPE | SIZE |
+-------+-------+-------+-------+
| FLAGS | OPC | STATUS| PORT |
+=======+=======+=======+=======+
| PPD MTYPE | LENGTH | PPD HEADER
+===============+===============+
| CREDIT | SCS MTYPE |
+---------------+---------------+
| DESTINATION CONNECT ID | SCS HEADER
+-------------------------------+
| SOURCE CONNECT ID |
+===============================+
| |
. .
. APPLICATION MESSAGE . SYSAP MESSAGE
. .
| |
+-------------------------------+
where:
FLINK command queue forward link.
BLINK command queue backward link.
EXAMPLE CI MESSAGE Page G-2
SIZE size in bytes of structure containing the entire
message (used by software only).
TYPE software data structure type (used by software
only).
SWFLAG software flags (used by software only).
PORT destination CI port number.
STATUS packet status on response.
OPC CI port opcode, e.g., SNDMSG in this case.
FLAGS CI command flags.
LENGTH number of bytes from PPD MTYPE field to end of
SYSAP message (this field is shared by the PPD and
SCS layers).
PPD MTYPE command type code for PPD layer, e.g., SCS_SEND in
this case.
SCS MTYPE message type for SCS layer, e.g., APPL_MSG in this
case.
DESTINATION CONNECT ID connect ID of the target SYSAP process.
SOURCE CONNECT ID connect ID of the sending SYSAP process.
APPLICATION MESSAGE the data to be transmitted to the target
SYSAP.
APPENDIX H
MINIMAL SUPPORT
Subsetting of the SCS features is allowed. For example, some SCS
systems may not implement block transfer operations. However, all
systems implementing SCS must be able to:
1. Process the PPD start sequence.
2. Interpret all SCS messages.
3. Process all SCS control messages and provide proper response.
APPENDIX I
CHANGE HISTORY
Rev. 2 to Rev. 3 change history. (All changes within change bars.)
1. Change data structures to allow for multiple interconnect
paths between systems. Each system block now has a chain of
path blocks, one for each intersystem path. The system block
and connection block data structures are modified, and the
path block data structure is added. The SCS message buffer
is now queued to the path block, and the path block is queued
to the SCS work queue for control message processing. In
addition, the following procedures required interface
modifications:
1. CONFIGURATION (changed to two procedures: CONFIG_SYS and
CONFIG_PATH)
2. INSERT_SCS_Q
3. REMOVE_SCS_Q
4. SNDDG
5. SNDMSG
6. SNDDAT
7. REQDAT
8. REQID
9. RSP_POLL
10. START_VC
11. STATE_POLL
12. REQ_ID
The following required minor code changes (due to calls to
changed interfaces listed above).
CHANGE HISTORY Page I-2
1. ACCEPT
2. REJECT
3. CONNECT
4. DISCONNECT
5. SEND_DG
6. SEND_MSG
7. REC_MSG
8. CANCEL_REC_MSG
9. READ
10. WRITE
11. SCS_REC
2. Two optional parameters are added to CONNECT. The PATH
parameter allows a SYSAP to request connection over a
specific path. The ERROR parameter provides a calling
address for SCS to notify the SYSAP on the receipt of an
erroneous packet.
3. A DISCONNECT request by one side now causes the connection to
be closed by both local and remote SCSs. A new state,
DISCONNECT_CNF, is added to the state diagram. A new SCS
disconnect confirmed control message and response pair,
DISCNF_REQ and DISCNF_RSP, are added. This second set of
disconnect messages ensure that all pending transfer
operations terminate before connection resources are
released. The following changes are made:
1. A new function, CB_CLOSED, is added to check for closed
state of a connection.
2. Procedures SEND_DG, REC_DG, and REC_MSG are changed to
functions.
3. Functions SEND_DG, REC_DG, SEND_MSG, REC_MSG, READ, and
WRITE now check to verify that the connection is open.
If the connection has been closed, status NOT_OPEN is
returned.
4. All PPD and SCS maintenance commands, messages, and responses
are removed.
CHANGE HISTORY Page I-3
5. The position of the reserved word in Start Data Format,
Appendix G, is changed to follow the system address.
6. The HW_VERSION field is changed to 16 bytes.
7. A new appendix is added showing the format of a sample CI
message transmission, including application message, SCS
header, PPD header, and CI port header.
8. A new appendix is added describing minimal support.
9. Former appendix D, Multi CI Port Support, is removed.
10. New connection state CLOSED_NR is added to indicate that
destination had no resources to process CONNECT, e.g., busy
processing another connect request. This is indicated by
NO_RESOURCES response.
11. Substantial style changes are made to the Pascal code and
specification.
Rev. 3 to Rev. 4 change history. (included in Rev. 3 change bars)
1. Change disconnect protocol to require both SYSAPs to issue
DISCONNECT requests before the connection is shutdown. The
new protocol uses only two messages, DISCONNECT_REQ and
DISCONNECT_RSP, but introduces states DISCONNECT_MATCH and
DISCONNECT_ACK. The following sections required changes:
1. Section 6.1, Type Definitions, was modified to add the
new states to the C_STATE definition.
2. Section 6.3, Connection Management Services, was modified
to add the new states and a description of the disconnect
protocol.
3. Section 6.3.5, Disconnect call in the SYSAP-SCS
interface, was changed to note that only the calling side
is prohibited from transmitting further messages.
4. Former Sections 8.2.9 and 8.2.10 of Version 3, describing
the Disconnect Confirmation messages, were removed.
5. Section 9.6.2, Connection States in SCS Operation, was
modified. The connection state table was changed to
reflect the new protocol, and the description following
that table was modified to note the disconnect
requirements for multi-priority ports.
6. Section 9.6.7, Disconnect procedure code, was modified
because disconnect can be called in one of two states.
CHANGE HISTORY Page I-4
7. Section 9.10, the SCS Send procedure code, was modified.
The DISCONNECT_PEND code was changed (only the comments)
to note the possible current states.
8. Section 9.11, SCS Receive procedure code, was modified.
The DISCNF_REQ and DISCNF_RSP code from Rev. 3 were
removed. The DISCON_REQ and DISCON_RSP code was modified
to show the path for various connection states.
2. The Start/Stack Data Format, Appendix F, is changed to add
two new fields. The CUR_TIME field is added to provide
system time for initializing nodes that do not have a clock.
The NODE_NAME field specifies the ASCII node name of the
sender.
3. The System Block data structure is modified to add the
NODE_NAME field.
4. The CONFIG_SYS function, Section 6.2.1, is changed to add the
NODE_NAME return parameter.
|
| Rev. 4 to Rev. 5 change history. (change bars include only Rev. 5
| changes)
|
| 1. Contrasting of architecture and functional specifications in
| Introduction.
|
| 2. Remove reference to requirements for supporting clusters with
| multiple CI's.
|
| 3. Describe SW_INCARNATION in system block.
|
| 4. Remove CLOSED_NM, _NR, _REJ and _VC states leaving only
| CLOSED. Add CONNECT_ACK, ACCEPT_SENT, and REJECT_SENT
| states. Update description in section 6.3 Connection
| management services and pascal code to reflect these state
| changes.
|
| 5. Rename PTR to CREDITS in CONNECT and ACCEPT calls.
|
| 6. Remove THRSH from LISTEN and put it in ACCEPT.
|
| 7. Remove ERROR from CONNECT call.
|
| 8. State that datagrams are queued and accounted for on a
| connection by connection basis in section 6.4 Datagram
| service.
|
| 9. State that an implementation "MUST" provide a provision for
| canceling block data transfers, but that there is a
| restriction due to design of CI port hardware. Section 6.6
| block data service.
CHANGE HISTORY Page I-5
| 10. Describe need for MPTR1 and MPTR2 and DPTR in START_VC call.
| Section 7.3.1 Start Virtual Circuit.
|
| 11. Remove REQ_ID and REQID functions from PPD interface.
|
| 12. Rewrite section 9.6.2 Connection States to reflect reality.
|
| 13. Define PPD message type codes with sign bit set as reserved
| for an implementation to use internally.
|
| 14. Change definitions of reject and disconnect reason codes to
| include more codes and severity encoding.
|
| 15. Change definition of Start Data format to include protocol
| version field and remove 4 bytes from the HW_VERSION.
|
| 16. Define the credit management variables a little better.
|
| 17. Explain START/STACK operation with protocol mismatch for
| later use.
|
| 18. Fix the pascal program to store something in REQ_CREDIT
| before using the value stored there.
|
| 19. Minor updates.
|
|
| Rev. 5 to Rev. 6 changes (included in Rev. 5 change bars)
|
| 1. Describe rules for verifying minimum message size for SYSAP
| protocol. Section 6.3.
|
| 2. Define BY_NAME and BY_ENTRY in section B.3.1.
|
| 3. Make statement about REJECT and DISCONNECT reason codes in
| appendix E. Reserve code 34.
|
Functional description of the
Systems Communications Architecture
21-Nov-83
Version 1, Revision 5
SCA Functional specification Page 2
1.0 Revision history
Revision 1:
1. Change user interface for packet sends to reflect data being copyed
rather than mapped into monitor space.
2. Add set port counters function (.SSSPC)
3. Add configuration change PSI channel to .SSAIC JSYS function.
Note: There are no change bars for this revision. Change bars
will begin with the next revision of the specification.
Revision 2:
Update path specification handling in .SSSDG and .SSSMG functions of
SCS%.
Revision 3:
Make maintainance data send and receive work correctly.
Revision 4:
Fix additional problems with maintainance data send and receive.
Revision 5:
Add user level maintainance functions for reset/start a remote system.
Also add "monotonic counter" to set/read port counter calls.
SCA Functional specification Page 3
2.0 Table of Contents
1.0 Revision history . . . . . . . . . . . . . . . . . . 2
2.0 Table of Contents . . . . . . . . . . . . . . . . . 3
3.0 Definitions . . . . . . . . . . . . . . . . . . . . 5
4.0 Introduction . . . . . . . . . . . . . . . . . . . . 6
4.1 Related documents . . . . . . . . . . . . . . . . 6
4.2 Scope . . . . . . . . . . . . . . . . . . . . . . 6
4.3 Module interactions . . . . . . . . . . . . . . . 7
4.4 SCA overview . . . . . . . . . . . . . . . . . . . 9
4.5 General differences . . . . . . . . . . . . . . . 9
4.5.1 TOPS-20 only functionality . . . . . . . . . . . 9
4.6 Service required of PHYKLP . . . . . . . . . . . 11
4.7 PHYKLP interface . . . . . . . . . . . . . . . . 12
4.8 Data structures . . . . . . . . . . . . . . . . 17
4.8.1 System block . . . . . . . . . . . . . . . . . 17
4.8.2 Connect block . . . . . . . . . . . . . . . . 20
4.8.3 Connect ID . . . . . . . . . . . . . . . . . . 23
5.0 Writing a monitor SYSAP . . . . . . . . . . . . . 24
5.1 General rules . . . . . . . . . . . . . . . . . 24
5.1.1 Buffer allocation and management . . . . . . . 24
5.1.2 Starting a connection . . . . . . . . . . . . 26
5.1.3 Global interlocks . . . . . . . . . . . . . . 28
5.2 Messages . . . . . . . . . . . . . . . . . . . . 29
5.2.1 Receiving messages . . . . . . . . . . . . . . 29
5.2.2 Sending messages . . . . . . . . . . . . . . . 29
5.3 Datagrams . . . . . . . . . . . . . . . . . . . 29
5.3.1 Receiving datagrams . . . . . . . . . . . . . 29
5.3.2 Sending datagrams . . . . . . . . . . . . . . 30
5.4 Named buffers . . . . . . . . . . . . . . . . . 30
5.5 Monitor SYSAP interface . . . . . . . . . . . . 31
5.5.1 SYSAP to SCA interface . . . . . . . . . . . . 31
5.5.1.1 Connect (SC.CON) . . . . . . . . . . . . . . 31
5.5.1.2 Listen (SC.LIS) . . . . . . . . . . . . . . 32
5.5.1.3 Accept (SC.ACC) . . . . . . . . . . . . . . 35
5.5.1.4 Reject (SC.REJ) . . . . . . . . . . . . . . 36
5.5.1.5 Disconnect (SC.DIS) . . . . . . . . . . . . 37
5.5.1.6 Abort (SC.ABT) . . . . . . . . . . . . . . . 38
5.5.1.7 Send datagram (SC.SDG) . . . . . . . . . . . 38
5.5.1.8 Queue datagram receive buffers (SC.RDG) . . 40
5.5.1.9 Send a message (SC.SMG) . . . . . . . . . . 41
5.5.1.10 Queue message receive buffers (SC.RMG) . . . 42
5.5.1.11 Cancel datagram receive buffer (SC.CRD) . . 43
5.5.1.12 Cancel message receive buffers (SC.CRM) . . 43
5.5.1.13 Map a named buffer (SC.MAP) . . . . . . . . 44
5.5.1.14 Unmap a buffer (SC.UMP) . . . . . . . . . . 46
5.5.1.15 Send named buffer data (SC.SND) . . . . . . 47
5.5.1.16 Request remote named buffer transfer (SC.REQ) 48
5.5.1.17 Connect state poll (SC.CSP) . . . . . . . . 49
5.5.1.18 Return destination connect ID (SC.DCI) . . . 50
5.5.1.19 Return system configuration data (SC.RCD) . 51
5.5.1.20 Reset a remote system (SC.RST) . . . . . . . 52
5.5.1.21 Start a node (SC.STA) . . . . . . . . . . . 53
5.5.1.22 Set port counters (SC.SPC) . . . . . . . . . 54
5.5.1.23 Read port counters (SC.RPC) . . . . . . . . 55
SCA Functional specification Page 4
5.5.1.24 Maintainance data send (SC.MDS) . . . . . . 56
5.5.1.25 Maintainance data read (SC.MDR) . . . . . . 57
5.5.1.26 Set online address (SC.SOA) . . . . . . . . 58
5.5.1.27 Swap bytes from 11 to 10 format (SC.ISW) . . 59
5.5.1.28 SC.OSW (Swap word from 10 to 11 forma . . . 60
5.5.1.29 Return node number given CID (SC.SBI) . . . 61
5.5.1.30 Return credit info (SC.RAC) . . . . . . . . 62
5.5.1.31 Return local port number (SC.PRT) . . . . . 63
5.5.1.32 Allocate a datagram buffer (SC.ALD) . . . . 64
5.5.1.33 Allocate a message buffer (SC.ABF) . . . . . 65
5.5.1.34 Return a message buffer (SC.RBF) . . . . . . 66
5.5.1.35 Return a datagram buffer (SC.RLD) . . . . . 66
5.5.2 SCA to SYSAP interface . . . . . . . . . . . . 67
6.0 Writing a JSYS SYSAP . . . . . . . . . . . . . . . 72
6.1 General rules . . . . . . . . . . . . . . . . . 72
6.1.1 Communicating with SCA . . . . . . . . . . . . 72
6.1.1.1 Using the SCS% with the PSI system . . . . . 72
6.1.2 Buffer management . . . . . . . . . . . . . . 72
6.1.2.1 Incoming buffers . . . . . . . . . . . . . . 72
6.1.2.2 Outgoing buffers . . . . . . . . . . . . . . 73
6.1.3 The race condition . . . . . . . . . . . . . . 73
6.2 JSYS SYSAP interface . . . . . . . . . . . . . . 74
6.2.1 Connect (.SSCON) . . . . . . . . . . . . . . . 75
6.2.2 Listen (.SSLIS) . . . . . . . . . . . . . . . 77
6.2.3 Accept (.SSACC) . . . . . . . . . . . . . . . 78
6.2.4 Reject (.SSREJ) . . . . . . . . . . . . . . . 79
6.2.5 Disconnect (.SSDIS) . . . . . . . . . . . . . 80
6.2.6 Send a DG (.SSSDG) . . . . . . . . . . . . . . 81
6.2.7 Queue a DG buffer (.SSQRD) . . . . . . . . . . 82
6.2.8 Send message (.SSSMG) . . . . . . . . . . . . 83
6.2.9 Queue message receive buffers (.SSQRM) . . . . 84
6.2.10 Cancel DG receive (.SSCRD) . . . . . . . . . . 85
6.2.11 Cancel receive message (.SSCRM) . . . . . . . 86
6.2.12 Connect state poll (.SSCSP) . . . . . . . . . 87
6.2.13 Return local node number (.SSGLN) . . . . . . 88
6.2.14 Return configuration data (.SSRCD) . . . . . . 89
6.2.15 Return buffer sizes (.SSRBS) . . . . . . . . . 91
6.2.16 Return status information (.SSSTS) . . . . . . 92
6.2.17 Get a queue entry . . . . . . . . . . . . . . 93
6.2.17.1 Receive a message (.SSRMG) . . . . . . . . . 93
6.2.17.2 Receive a datagram (.SSRDG) . . . . . . . . 94
6.2.17.3 Get entry from data queue (.SSGDE) . . . . . 95
6.2.17.4 Get an entry off the event queue (.SSEVT) . 96
6.2.18 Named buffer overview . . . . . . . . . . . . 98
6.2.19 Map a buffer (.SSMAP) . . . . . . . . . . . . 99
6.2.20 Unmap a buffer (.SSUMP) . . . . . . . . . . . 101
6.2.21 Send data (.SSSND) . . . . . . . . . . . . . . 102
6.2.22 Request data (.SSREQ) . . . . . . . . . . . . 103
6.2.23 Maintainance data send (.SSMDS) . . . . . . . 104
6.2.24 Maintainace data read (.SSMDR) . . . . . . . . 105
6.2.25 Start a remote system (.SSSRS) . . . . . . . . 106
6.2.26 Reset a remote system (.SSRRS) . . . . . . . . 107
6.2.27 Set port counters (.SSSPC) . . . . . . . . . . 108
6.2.28 Read port counters (.SSRPC) . . . . . . . . . 109
6.2.29 Add interrupt channels (.SSAIC) . . . . . . . 110
SCA Functional specification Page 5
3.0 Definitions
There are a number of terms and concepts vital to an understanding
of SCA. They are:
1. Credit - Credit refers to buffers queued for message (only messages,
there is no credit system for datagrams) reception or transmission.
Receive credit is the number of buffers you have queued to get
messages from a remote node. Send credit is the number of buffers
the remote has queued to receive messages from you.
2. Callback - The callback is the mechanism through which SCA interrupts
a SYSAP. For example, when a message or datagram has arrived for
your connection, SCA will PUSHJ to the address given in the CONNECT,
LISTEN, or set online notification address call, with T1-T4 setup to
point to the new packet.
3. Port queues - This refers to the set of queues used by the monitor to
communicate with the KLIPA. These queues include the message and
datagram free queues, into which all inbound packets are placed.
4. Packet - Term used to denote any CI packet, I.E. a message or a
datagram.
5. Circuit - Virtual communications path layered on top of the CI wire
(I.E. hardware path) maintained by the port driver.
6. Connection - Virtual communications path layered on top of circuits
and maintained by SCA.
SCA Functional specification Page 6
Introduction
4.0 Introduction
4.1 Related documents
The reader should at least be familiar with the following documents
before proceeding with this specification. The corporate SCA spec is
particularly important as all terminology used in this document follows
standards set in the corporate spec.
1. Systems Communications Architecture, Rev 4, 20-July-82 (Strecker)
2. LCG CI Port Architecture Specification, 11-July-83 (Dossa/Keenan)
3. TOPS-20 KLIPA Driver Functional Specification, 19-Aug-83
(Grant/Miller)
4. TOPS-20 Coding Standard, 23-Mar-83 (Murphy)
4.2 Scope
This document will describe the interfaces in and out of the Systems
Communications Architecture (SCA). This includes the user interface
through the SCS% JSYS. Some of the functions invisible to the rest of
the monitor, yet important to the overall scheme of the CI software are
also covered. Implementation details are left to the design
specification however.
SCA Functional specification Page 7
Introduction
4.3 Module interactions
The following diagram illustrates the layout of the CI software and
hardware.
-------- ---------
! SCS% ! ! DIAG% !
-------- --------- User mode
! /
- - - - ! - - - / - - -
-------- -------- ------- /
! MSCP ! !SCSJSY! ! CFS ! / Monitor mode
-------- -------- ------- /
\ ! / /
\ ! / /
\ ! / /
----------------- /
! SCA !-----
-----------------
!
---------------
! Port driver !
---------------
!
! Software
!
- - - - - - - - - -
!
! Hardware
---------------
! KLIPA !
---------------
!
CI !
==========================================
Briefly, these are the functions performed by each of the software
modules listed above.
The port driver is the hardware controller for the KLIPA. It
communicates with the device through a queued protocol using KL main
memory.
SCA is the CI gateway for the rest of the monitor. The only exception is
the DIAG JSYS which has the capability of disabling the port driver and
taking direct control of the hardware. In general however all monitor
components access the CI through SCA.
System applications (SYSAP) are the end users of the CI. The Mass
Storage Control Protocol (MSCP) is a CI disk controller. Common File
System (CFS) is the global file lock manager for implementing distributed
SCA Functional specification Page 8
Introduction
access to CI disks and dual ported massbus disks.
SCA Functional specification Page 9
Introduction
4.4 SCA overview
The overall function of SCA can best be described as software
multiplexer, demultiplexer for the CI. SCA is the module that creates
the illusion of virtual connections over the circuits established by the
port driver. A detailed description of how SCA performs this function
can be found in [1]. What needs to be detailed here is exactly what has
been done that is specific to TOPS-20 and hence could never be outlined
in the corporate specification.
4.5 General differences
In general, the corporate specification is considered to be a model
in which the seeds of the TOPS-20 implementation may be found. There are
a number of global differences that need to be outlined.
1. The corporate specification uses polling to determine the completion
of a request. The TOPS-20 implementation is interrupt driven.
2. TOPS-20 does not use the suggested format for connection and system
blocks. Additional words were required and all support locations for
path blocks were removed.
3. The most important difference is the lack of the "path" concept in
TOPS-20. The corporate specification calls for the use of multiple
paths to a single node. (Note that this is not the dual rail
concept, I.E. Path A and Path B) The entire concept of multiple
paths to a single node is dissallowed in TOPS-20. All nodes are
directly connected to all other nodes by exactly one logical path. A
logical path is a port onto a CI, even though the port may have more
than one cable on it.
TOPS-20 does not support paths because the KL-10 processor can
currently support only one KLIPA. Since there is one KLIPA there can
by definition only be one path to a node. When more than one KLIPA
is supported the issue of paths will be addressed.
4.5.1 TOPS-20 only functionality
At present, there is only one function of SCA that is seen by the
outside world and not covered by the corporate specification. This
function is the periodic polling of nodes with open connections. The
need for this service arises from the fact that the KLIPA answers REQID
packets without software intervention. Since port level pollers for most
machines use REQID packets to test the rails to the other nodes on the
net, a system could suffer a complete software failure and no one would
detect it until the port were reset during the BOOT process. There are
SYSAPs that need to see remote software failures much sooner than this.
Hence SCA will send credit requests for zero credit to nodes that have
SCA Functional specification Page 10
Introduction
not sent the local node a message for a certain time period. If the
response comes back within a certain time then the node is up and SCA
simply marks the fact the the credit request received a response. If the
response does not come back within the defined time period, the node is
declared offline, SCA requests that the port to port virtual circuit be
broken, and all SYSAP's are notified of the remote node failure.
SCA Functional specification Page 11
Introduction
4.6 Service required of PHYKLP
Since PHYKLP maintains direct control over the hardware, there are
services required of PHYKLP by SCA. These services are:
1. ULNKDG -- Remove a buffer from the datagram free queue.
2. ULNKMG -- Remove a buffer from the message free queue.
3. SNDDG -- Send a datagram
4. SNDMSG -- Send a message
5. LNKMFQ -- Link a buffer chain onto the message free queue
6. LNKDFQ -- Link a buffer chain onto the datagram free queue
7. CLOSVC -- Close a virtual circuit
8. MAPBUF -- Map a named buffer
9. UMAP -- Unmap a named buffer
10. SNDDAT -- Start a named buffer data send
11. REQDAT -- Start a named buffer data receive
12. LOCPRT -- Return the local node number
13. KLPOPN -- Open a circuit
14. PPDSRS -- Send a reset or start maintainance packet
15. PPDSMD -- Do a maintainance data send
16. PPDRMD -- Do a maintainace data read
17. PPDRPT -- Read port counters
18. PPDSPT -- Set port counters
19. STRPOL -- Start the poller
20. STPPOL -- Stop the poller
21. STRKLP -- Start the KLIPA
22. STPKLP -- Stop the KLIPA
SCA Functional specification Page 12
Introduction
4.7 PHYKLP interface
Direct control over the CI is done by the port driver (PHYKLP).
Hence SCA must interface to the port driver to perform its function. The
following is the set of SCA entry points understood by the port driver.
- SC.INT -
This routine is called when the port driver has received a packet
bound for SCA.
Call
BLCAL. (SC.INT,<SS.PKA,SS.SBA,SS.FLG,SS.LEN>)
Where:
SS.PKA - Address of message/datagram/SCA buffer
SS.SBA - Address system block
SS.FLG - Flags
F.SPM - Packet data mode 0 - Industry compatable mode
1 - High density mode
F.RSP - Local or remote packet 0 - Remote packet
1 - Localy generated packet
SS.LEN - Length of packet in bytes (for industry compatible packets)
- Length in words for high density packets
Return (+1)
T1/ Error code
Return (+2)
No data returned, all went well
SCA Functional specification Page 13
Introduction
- SC.MDC -
This routine is called by the port driver when a maintainance data
transfer has completed.
Call
BLCAL. (SC.MDC,<SS.ADR,SS.NAM>)
Where:
SS.ADR -- Address passed to PHYKLP on SC.MDS/SC.MDR call
SS.NAM -- Local name for transfer which has completed
Return (+1)
T1/ Error code
Return (+2)
No data returned
SCA Functional specification Page 14
Introduction
- SC.DMA -
This routine handles the completion of a named buffer transfer.
Call
BLCAL. (SC.DMA,<SS.CID,SS.SBA,SS.NAM>)
Where:
SS.CID -- CID of connection we did this for
SS.SBA -- Address of system block
SS.NAM -- Buffer name for transfer that completed
Return (+1)
T1/ Error code
Return (+2)
No data returned
SCA Functional specification Page 15
Introduction
- SC.ERR -
This routine is called to notify SCA of a virtual circuit closure.
This includes closures requested by SCA.
Call
BLCAL. (SC.ERR,<SS.NOD>)
Where:
SS.NOD --> Node number of the system who's VC just went away.
Return (+1)
T1/ Error code
Return (+2)
No data returned
- SC.ONL -
This routine is called when a node has come online.
Call
BLCAL. (SC.ONL,<SS.NOD>)
Where:
SS.NOD -- Node number of system that has come online
Return (+1)
T1/ Error code
Return (+2)
No data returned
- SC.OFL -
This routine is called when a system has gone offline. Note that
SCA assumes the data for this node has not been cleaned up by the port
driver.
Call
BLCAL. (SC.OFL,<SS.NOD>)
Where:
SS.NOD -- Node number of the system that has gone offline
Return (+1)
T1/ Error code
Return (+2)
No data returned
SCA Functional specification Page 16
Introduction
- SC.PRC -
This routine is called when the port detects that a
READ-PORT-COUNTERS command has completed.
Call
BLCAL. (SC.PRC,<SS.CID,SS.ADR>)
Where:
SS.CID -- CID for whom the register read was done
SS.ADR -- Address of counter data packet
Return (+1)
T1/ Error code
Return (+2)
No data returned
SCA Functional specification Page 17
Introduction
4.8 Data structures
To perform its function as multiplexer/demultiplexer SCA maintains a
set of connections over the virtual circuits maintained by the port
driver. There are two blocks basic to the maintenance of these
connections, the system block and the connect block.
4.8.1 System block
The system block is a data structure shared with the port driver.
In fact the port driver owns most of the block.
!=======================================================!
.SBANB ! Address of next system block !
!-------------------------------------------------------!
.SBAPB ! Address of associated port control block !
!-------------------------------------------------------!
.SBACD ! Address of associated channel data block !
!-------------------------------------------------------!
.SBVCS ! Path validity info ! Dest vir cir state !
!-------------------------------------------------------!
.SBDSP ! Destination port !
!-------------------------------------------------------!
.SBDRQ ! Datagram return queue header !
!-------------------------------------------------------!
.SBLMB ! Local message buffer header ! *
!-------------------------------------------------------!
.SBFCB ! Pointer to first connection block ! *
!-------------------------------------------------------!
.SBLCB ! Pointer to last connection block ! *
!-------------------------------------------------------!
.SBTWQ ! FLINK for SCA work queue ! *
!-------------------------------------------------------!
.SQBWQ ! BLINK for SCA work queue ! *
!-------------------------------------------------------!
.SBQOR ! Pointer to queue of outstanding requests !
!-------------------------------------------------------!
.SBDSS \ \
\ Destination system \
\ \
!-------------------------------------------------------!
.SBMMS ! Max mess size (bytes) ! Max DG size (Bytes) !
!-------------------------------------------------------!
.SBDST ! Destination software type !
!-------------------------------------------------------!
.SBDSV ! Destination software version !
!-------------------------------------------------------!
.SBDSE ! Destination software edit level !
!-------------------------------------------------------!
SCA Functional specification Page 18
Introduction
!-------------------------------------------------------!
.SBDHT ! Destination hardware type !
!-------------------------------------------------------!
.SBDHV ! Destination hardware version !
!-------------------------------------------------------!
.SBDPC \ \
\ Destination port characteristics \
\ \
!-------------------------------------------------------!
.SBTIM ! TODCLK at last message from this remote ! *
!-------------------------------------------------------!
.SBFLG ! Flags ! *
!-------------------------------------------------------!
.SBTBQ ! Address of first buffer on buffer defer queue ! *
!-------------------------------------------------------!
.SBBBQ ! Address of last buffer on buffer defer queue ! *
!=======================================================!
Most of the cells in this structure are maintained by the port
driver. There are a few however that are the exclusive domain of SCA.
These are described below.
.SBLMB
The local message buffer header is an interlock location for this remote.
Since all SCA messages are flow controled, some method had to be arrived
at for flow control of SCA overhead messages. This is done by always
having just one receive credit available for each remote node. Hence we
cannot send more than one overhead message at a time to a particular
node. Hence this location is used to flag the fact that a request has
been sent to the host. Note that when non-zero, this location contains
the message type that is expected in response to the request we believe
is outstanding.
.SBFCB/.SBLCB
The pointer to the first and last connect blocks are the FLINK and BLINK
for one set of threads to the connect blocks. Each connect block is a
member of two doubly linked lists. One is the list of connections to a
system, the other is the list of connects owned by a fork. Note that
unless the fork has done an SCS% JSYS, this second list is empty.
.SBTWQ/.SBBWQ
Something must be done with the requests that need to be sent to a system
which already has a request outstanding. These requests are placed on
the work queue for that system. The work queue FLINK and BLINK are
stored in the system block.
.SBTIM
A function performed by SCA is the polling of remote systems that have
connections open to them. This polling is done to detect a remote
software stoppage. .SBTIM is TODCLK the last time the node talked to us.
For further details on this process, see the section on SC.CLK.
.SBFLG
SCA Functional specification Page 19
Introduction
Currently, the only defined flags are the timed message flag, and the
circuit requires opening flag. When the timed message flag is lit in
.SBFLG, a timed message is outstanding for this node. SCA uses this flag
to help determine if a node should be declared dead. The circuit
requires opening flag indicates that the circuit has been closed and just
as soon as databases have been cleaned up, SCA should call the port
driver to open the circuit again.
.SBTBQ/.SBBBQ
These words are the head and tail pointers for the queue of buffer defer
requests. This queue is used by SCA to handle the allocation of more
buffers than it has on hand.
SCA Functional specification Page 20
Introduction
4.8.2 Connect block
The other data structure used by SCA is the connect block. As the
name implies this block is the complete set of information maintained
about an SCA connection.
!=======================================================!
.CBANB ! Address of next connection block for this SB !
!-------------------------------------------------------!
.CBAPB ! Address of previous connection block for this SB !
!-------------------------------------------------------!
.CBJNB ! Address of next connection block for this fork !
!-------------------------------------------------------!
.CBJPB ! Address of previous connection block for this fork !
!-------------------------------------------------------!
.CBSTS ! Block state ! Connect state !
!-------------------------------------------------------!
.CBFLG ! Flags !
!-------------------------------------------------------!
.CBSCI ! Source connect ID !
!-------------------------------------------------------!
.CBDCI ! Destination connect ID !
!-------------------------------------------------------!
.CBSPN \ \
\ Source process name \
\ \
!-------------------------------------------------------!
.CBDPN \ \
\ Destination process name \
\ \
!-------------------------------------------------------!
.CBDTA \ \
\ User supplied connect data \
\ \
!-------------------------------------------------------!
.CBREA ! Dest reason ! Source reason !
!-------------------------------------------------------!
.CBMCD ! Min send Credit ! Min Receive credit !
!-------------------------------------------------------!
.CBRCD ! Receive Credit !
!-------------------------------------------------------!
.CBSCD ! Send credit !
!-------------------------------------------------------!
.CBNPO ! Number of packets still on port command Q !
!-------------------------------------------------------!
.CBRQC ! Requeue credit !
!-------------------------------------------------------!
.CBPRC ! Pending rec credit !
!-------------------------------------------------------!
.CBSBA ! Pointer to system block for this connection !
!-------------------------------------------------------!
.CBADR ! Address to call SYSAP on certain conditions !
!-------------------------------------------------------!
SCA Functional specification Page 21
Introduction
!-------------------------------------------------------!
.CBCDD ! Number of dropped datagrams !
!-------------------------------------------------------!
.CBDGR ! Number of real DG buffers queued !
!-------------------------------------------------------!
.CBDGJ ! Number of JSYS DG buffers queued !
!-------------------------------------------------------!
.CBSBI ! Destination node number !
!-------------------------------------------------------!
.CBFRK ! Job number of owner job ! Fork number of owner fork !
!-------------------------------------------------------!
.CBTMQ ! Pointer to top of message available queue (for JSYS) !
!-------------------------------------------------------!
.CBBMQ ! Pointer to bot of message available queue (for JSYS) !
!-------------------------------------------------------!
.CBTDQ ! Pointer to top of datagram available queue (for JSYS)!
!-------------------------------------------------------!
.CBBDQ ! Pointer to bot of datagram available queue (for JSYS)!
!-------------------------------------------------------!
.CBTXQ ! Pointer to top of the DMA xfer complete queue !
!-------------------------------------------------------!
.CBBXQ ! Pointer to bot of the DMA xfer complete queue !
!-------------------------------------------------------!
.CBTEQ ! Pointer to top of the event queue !
!-------------------------------------------------------!
.CBBEQ ! Pointer to bot of the event queue !
!-------------------------------------------------------!
.CBTBQ ! Pointer to first buffer descriptor block !
!-------------------------------------------------------!
.CBBBQ ! Pointer to last buffer descriptor block !
!-------------------------------------------------------!
.CBPS0 ! PSI channel for messages ! PSI channel for datagrams !
!-------------------------------------------------------!
.CBPS1 ! PSI channel for DMA ! PSI channel for events !
!=======================================================!
Of the above cells, a few are returned by SCA on certain routine
calls. The following is a description of the cells that are of
importance to a SYSAP.
.CBSTS
If non-zero, the block state indicates the connection is waiting for a
response to a request. The block state also indicates what the response
will be. These are the currently defined block states:
.BSCNP --> Connect pending
.BSACP --> Accept pending
.BSCRP --> Credit pending
.BSRPN --> Reject pending
.BSDPN --> Disconnect pending
As the name may indicate, the connection state indicates the current
state of the connect. The following are the currently defined connection
SCA Functional specification Page 22
Introduction
states.
.CSDRE --> Disconnect received
.CSDSE --> Disconnect sent
.CSDAK --> Disconnect acknowledge
.CSDMC --> Disconnect match
.CSCLO --> Closed - by command
.CSCNM --> Closed - no match
.CSCRJ --> Closed - rejection
.CSCNR --> Closed - no resources
.CSCVC --> Closed - Port virtual circuit error
.CSLIS --> Listening
.CSCSE --> Connect sent
.CSCAK --> Connect acknowledge
.CSCRE --> Connect received
.CSOPN --> Connection open
.CBFLG
The flags word supports flags for both SCA and the SCS% JSYS. These are
the currently defined flags:
CBFNNC --> Credit has come available since ntofication of credit low
CBFJSY --> This is a JSYS initiated connect block
CBFABT --> CB has been aborted
CBFRAP --> CB is to be reaped
CBFDCL --> This was don't care listener
CBFKIL --> Owning fork has gone away (JSYS connect only)
.CBSCI
This is the source connect ID. This is the local name for this
connection.
.CBDCI
This is the remote connect ID. This name is what the remote calls the
connection.
.CBSPN/.CBDPN
These are the local and remote process names in 8 bit ASCII.
.CBDTA
This is the initial connection data sent during the handshake for opening
the connection. It is always the data sent to us by the remote.
.CBREA
These are the remote and local disconnect reasons. When a disconnect is
started, the local code is transmitted as the cause for the disconnect.
When the disconnected is initiated remotely, the destination reason is
stored from the disconnect request packet.
.CBRCD/.CBSCD
SCA Functional specification Page 23
Introduction
These cells contain the current credit levels for this connection. The
receive credit reflects the number of buffer queued on this system for
the reception of message from the remote. The send credit is the number
of buffers the remote has queued for receiving localy generated messages.
4.8.3 Connect ID
The connect ID is the one word unique identifier for any connection.
It is mentioned here because the SYSAP needs to understand the fprmat of
the connect ID. The ID is made up of two fields, the SYSAP field and the
SCA field. The SYSAP field contains bits defined by the SYSAP and passed
to SCA when connection blocks area being created (the connect and listen
calls). The SCA field is broken down into fields for use by SCA, but the
SYSAP only needs to know that the entire field is for the use of SCA.
The following is the format of the connect ID:
0 5 6 35
!====================================================!
!SYSAP bits ! SCA bits !
!====================================================!
When the SYSAP field is passed to SCA it is passed in bits thirty
(30) through thirty-five (35) of the BLCAL. argument. SCA will move the
bits into the correct position for placement into the connect ID.
SCA Functional specification Page 24
Writing a monitor SYSAP
5.0 Writing a monitor SYSAP
5.1 General rules
To talk to other processes on remote systems, SYSAPs request
services of SCA. There are some rules that must be followed if the
conversation is to go smoothly.
5.1.1 Buffer allocation and management
There are four buffer types that monitor SYSAPs may have to deal
with, messages and datagrams, both of which can be inbound or outbound.
Rule one, ALL inbound buffers are allocated and controlled by SCA.
When a SYSAP desires to queue buffers for message or datagram reception,
call SCA (see calling sequence for SC.RMG and SC.RDG) and indicate how
many you desire, or specify the address of a buffer already allocated by
SCA. In the normal case, start up by asking for a number of buffers, and
after they have been returned with text in them, return them to SCA as
fresh buffers for the port queues. SYSAPs MUST NOT specify a buffer not
allocated by SCA when queueing inbound buffers.
Rule two deals with outbound buffers. SYSAPs may ask SCA for a
packet buffer (see calling sequence for SC.ABF and SC.ALD), fill it with
data, and ask SCA to send it (see SC.SMG and SC.SDG). If the SYSAP uses
SCA buffers for sending packets, the SYSAP may request the buffer go on
the port free queue on packet send completion. Hence the SYSAP may do a
packet send and queue a buffer for reception all at the same time. Note
that only SCA buffers may end up on the port free queues. Hence SYSAPs
may not allocate their own space and ask for these buffers to end up on
the port free queue.
If the SYSAP desires to allocate its own send buffers, it may do so
but the space allocated must meet rigid standards. First, the buffer
must be contiguous in physical memory. Hence if a page boundry is
crossed, the two virtual pages must be physically contiguous. Second,
the start of the SYSAP text must be at least .MHUDA words into the page.
This is used by SCA for header space. Third, when the packet send is
done the SYSAP must ask for the buffer back. It MUST NOT end up on the
port free queues.
SCA Functional specification Page 25
Writing a monitor SYSAP
SYSAPs must understand the format of SCA buffers if they are to be
used correctly. The following is the general format of an SCA buffer:
!=====================================!
.MHISH \ \ \
\ Invisible SYSAP header \ \ SYSAP header area
\ \ / --------------------
\ \ /
!-------------------------------------!
0 ---> \ \ \
\ SCA header \ \
\ \ \
\ \ / SCA header area
!-------------------------------------! / --------------------
.MHPKL ! Packet length ! /
!-------------------------------------!
.MHUDA \ \ \
\ SYSAP text \ \ SYSAP text area
\ \ / --------------------
\ \ /
!=====================================!
.MHISH - This symbol defines the offset to the base of the invisible
SYSAP header. It is important to note that this is a negative offset.
This header is for the exclusive use of the SYSAP. SCA will zero it
when the SYSAP requests the buffer but otherwise will not touch it. This
means the SYSAP can write data to this area and have it survive across
port packet transmission.
0 - This is word zero of the buffer. It is the base address which is
passed between SCA and te SYSAP when talking about this buffer. All
offsets within the buffer are defined as offsets from this word.
.MHPKL - This word is used by SCA to describe the length of an incoming
packet. It is always filled in by SCA when it is called by the port
driver for an incoming packet. This word is not filled in by the SYSAP
on a message send.
This word is always the length of the SYSAP text, I.E. it never
includes the length of any overhead data. If the packet was transmitted
in high density mode, then the length is in words. If the transmission
mode was industry compatable, then the length is in bytes.
.MHUDA - This offset defines the first word of the SYSAP text area. SCA
will never touch this area except to zero it on buffer allocation.
SCA Functional specification Page 26
Writing a monitor SYSAP
5.1.2 Starting a connection
Before application packets can be exchanged between processes on two
systems, SCA must mediate the opening of a connection. The following is
a graphic description of this process.
SCA Functional specification Page 27
Writing a monitor SYSAP
System A ! System B
!
Active side ! Passive side
_____________________________________________________________________________
! _____________________
! | SYSAP does LISTEN |
! ---------------------
! \
! ___________\______
! | SCA creates CB |
! ------------------
!
______________________ !
| SYSAP does CONNECT | !
---------------------- !
\ !
_______\______________ ! ________________________________
| SCA sends CONN_REQ | ---------------->| SCA gets CONN_REQ and finds |
---------------------- ! | listener. SCA sends CONN_RSP|
! | and gives .SSCTL callback |
_____________________ <--------------- | to listening SYSAP |
| SCA gets CONN_RSP | ! --------------------------------
--------------------- ! /
! _______/___________
! |SYSAP gets .SSCTL|
! -------------------
! |
! |
! ___________________
! |SYSAP does ACCEPT|
! -------------------
! /
_________________________ ! ________________/__
|SCA gets ACCP_REQ,sends| <---------------- |SCA sends ACCP_REQ|
| ACCP_RSP, and issues | ! --------------------
| .SSCRA callback. | !
| Connect is now open, | ! ________________________________
| packets may be sent | ----------------> |SCA receives ACCP_RSP, issues |
------------------------- ! | .SSOSD callback. Connect is |
/ ! | now open, packets may be sent|
/ ! --------------------------------
------------------- ! \
|SYSAP gets .SSCRA| ! --------------------------
| callback, SYSAP | ! |SYSAP gets .SSOSD call |
| knows connect is| ! | back, SYSAP knowns |
| open | ! | connect is open |
------------------- ! --------------------------
The diagram above is a typical connection opening sequence. The
important thing to watch is the set of callbacks from SCA. They are the
direct indicator of what state the connect is in. Note that there are
other options than the set indicated by the diagram. The detailed
SCA/SYSAP interface details these options.
SCA Functional specification Page 28
Writing a monitor SYSAP
5.1.3 Global interlocks
There are times when a SYSAP desires to insure that no further CI
traffic will be processed until it has completed some piece of code.
Using PIOFF to accomplish this is undesirable since it does not allow for
nesting and it turns off more channels than are necessary. Instead of
PIOFF/PION, CIOFF/CION should be used. These macros call routines in
SCAMPI which will do nesting and interrupt level checks. At present,
there are 36 bits of nesting counter, and code executed at KLIPA
interrupt level will not turn off the channel. Since these nesting
checks are done, the SYSAP is guaranteed that the channel will stay off
until it does a CION. Note that one side effect of going CIOFF is being
NOSKED as well.
SCA Functional specification Page 29
Writing a monitor SYSAP
5.2 Messages
5.2.1 Receiving messages
To receive messages from a remote node a SYSAP must do the
following:
1. Open a connection to the desired remote.
2. Queue message buffers.
The SYSAP will now receive a .SSMGR callback for each message that
arrives for it.
5.2.2 Sending messages
To send messages the SYSAP must have the following:
1. An open connection with the desired remote.
2. Send credit.
3. A buffer which meets the requirements for placement on the port
command queues.
If the connection has no send credits the remote node has not queued
any buffers for receiving messages from you. Hence you cannot send any
and will get the fail return from SC.SMG until the remote queues some
buffers.
5.3 Datagrams
5.3.1 Receiving datagrams
Much like messages, datagrams require an open connection to the
remote and buffers queued for datagram reception. The major difference
is that when the remote does a send, if it fails because there are no
buffers available for your connection, you will get the .SSDDG callback.
This is mearly an indication that the software has detected a dropped
datagram for your connection and you should queue some buffers for it.
If the hardware drops the datagram because there are no buffers on the
entire hardware queue, you will never hear about it. Hence the SYSAP
cannot count on being told about dropped datagrams. Note that SCA never
notifies the sender that the datagram was dropped.
SCA Functional specification Page 30
Writing a monitor SYSAP
5.3.2 Sending datagrams
Sending datagrams requires an open connection to the remote and a
packet buffer that meets the requirements for placement on the port
command queues. (See the section on buffers for more details)
5.4 Named buffers
The general procedure for the transfer of data with named buffers is
as follows:
1. Both sides of an open connection do a map call to set up a buffer.
2. SYSAP A gives its name for the buffer to SYSAP B.
3. The SYSAP B does a request or send data function which starts the
data in the desired direction.
4. The SYSAP B gets a callback indicating the completion of the named
buffer transfer.
5. Lastly, and optionally, SYSAP B tells the SYSAP A that the transfer
is complete.
This method implies that each SYSAP has message buffers queued. The
data transfer functions require a buffer from the message free queue.
The exchange of names should be done with messages or datagrams.
SCA Functional specification Page 31
Writing a monitor SYSAP
5.5 Monitor SYSAP interface
5.5.1 SYSAP to SCA interface
SCA provides many services to the SYSAP though the use of these
calling sequences:
5.5.1.1 Connect (SC.CON)
- Connect (SC.CON) -
This routine requests a connect with a remote process.
Call
BLCAL. (SC.CON,<SS.SPN,SS.DPN,SS.NOD,SS.MSC,SS.MRC,SS.ADR,^_
SS.SID,SS.DTA,SS.BFR,SS.DGB>)
Where:
SS.SPN -- Byte pointer to source process name
SS.DPN -- Byte pointer to destination process name
SS.NOD -- Node number of destination system
SS.MSC -- Minimum send credit (Min for remote receive
credit)
SS.MRC -- Minimum receive credit, point at which
destination must give more
SS.ADR -- Address to call on condition changes for
this connection
SS.SID -- Value to be placed in SYSAP field in CID (right justified)
SS.DTA -- Address of SYSAP connection data or zero
SS.BFR -- Number of buffers to queue for message reception
SS.DGB -- Number of datagram buffers to queue
Return (+1)
T1/ Error code
Return (+2)
T1/ Connect ID
The returned connect ID is the unique identifier for this
connection. All further interaction with SCA will include this connect
ID (CID).
SCA Functional specification Page 32
Writing a monitor SYSAP
5.5.1.2 Listen (SC.LIS)
- Listen (SC.LIS) -
This routine enables the process to listen for connections from
remote processes.
Call
BLCAL. (SC.LIS,<SS.SPN,SS.DPN,SS.NOD,SS.ADR,SS.SID,SS.DTA,^_
SS.MSC,SS.MRC>)
Where:
SS.SPN -- Byte pointer to source process name
SS.DPN -- Byte pointer to destination process name or 0
SS.NOD -- Node number or -1
SS.ADR -- Address to call on connection condition changes
SS.SID -- Value to be placed in SYSAP field of CID (Right justified)
SS.MSC -- Minimum send credit
SS.MRC -- Minimum receive credit
Return (+1)
T1/ Error code
Return (+2)
T1/ Connect ID
When SCA receives a connect request from a remote node, the
following algorithm is used when doing name matching with local
listeners:
SCA Functional specification Page 33
Writing a monitor SYSAP
Figure 1
SCA Functional specification Page 34
Writing a monitor SYSAP
A successful return from this call means SCA has a held a connection
for you waiting for connects from remote nodes. If a remote requests a
connection with a process, that process will receive the .SSCTL callback.
SCA Functional specification Page 35
Writing a monitor SYSAP
5.5.1.3 Accept (SC.ACC)
- Accept (SC.ACC) -
This routine is used to accept a connect request from a remote node.
Call
BLCAL. (SC.ACC,<SS.CID,SS.DTA,SS.BFR,SS.DGB>)
Where:
SS.CID -- Connect ID
SS.DTA -- Address of initial connection data or zero
SS.BFR -- Number of buffers to be queued for message reception
SS.DGB -- Number of buffers to queue for datagram reception
Return (+1)
T1/ Failure code
Return (+2)
T1/ Address of initial connect data
The returned address of connect data is a pointer to the connection
data sent by the remote on the connect request. Note that the connection
is not open until the .SSOSD callback is given.
SCA Functional specification Page 36
Writing a monitor SYSAP
5.5.1.4 Reject (SC.REJ)
- Reject (SC.REJ) -
This routine rejects the connect request of a remote process.
Call
BLCAL. (SC.REJ,<SS.CID,SS.RJR>)
Where:
SS.CID -- Connect ID
SS.RJR -- Reject reason code
Return (+1)
T1/ Failure code
Return (+2)
No data is returned by this routine
The reject reason may be any value the caller desires with the
exception of those reserved to SCA (in the range /TBD/). The idea is
that the SYSAP protocol should invent and use its own reject reasons.
After the reject call has been issued, the connection goes back into the
listen state.
SCA Functional specification Page 37
Writing a monitor SYSAP
5.5.1.5 Disconnect (SC.DIS)
- Disconnect (SC.DIS) -
This routine closes an open connection. Note that it may only be
called if the connection is open. No other connection state is allowed
for a connection that is to be disconnected.
Call
BLCAL. (SC.DIS,<SS.CID,SS.DIR>)
Where:
SS.CID -- Connect ID
SS.DIR -- Disconnect reason
Return (+1)
T1/ Failure code
Return (+2)
No data is returned by this routine
The disconnect reason may be any value the caller desires with the
exception of those reserved to SCA (in the range /TBD/). The idea is
that the SYSAP protocol should invent and use its own disconnect reasons.
SCA Functional specification Page 38
Writing a monitor SYSAP
5.5.1.6 Abort (SC.ABT)
- Abort (SC.ABT) -
This routine is called to abort, or cancel, a connection. It
differs from disconnect in that it may be issued for a connection in any
state. Whereas disconnect may only be issued for an open connection.
Call
BLCAL. (SC.ABT,<SS.CID>)
Where:
SS.CID -- Connect ID of the connection to be aborted
Return (+1)
T1/ Error code
Return (+2)
No data returned, CID is no longer valid, and the connection has been
aborted.
5.5.1.7 Send datagram (SC.SDG)
- Send datagram (SC.SDG) -
This routine is called to send a datagram over an open connection.
Call
BLCAL. (SC.SDG,<SS.CID,SS.FLG,SS.LDG,SS.ADG>)
Where:
SS.CID -- Connect ID
SS.FLG -- Flag word
SS.LDG -- Len of datagram (in bytes)
SS.ADG -- Address of datagram buffer
Return (+1)
T1/ Failure code
Return (+2)
No data is returned by this routine, datagram
placed on port queue
The flags word is used to indicate the transmission mode of the
packet, and hence the units on the packet size. It also indicates what
should be done with the buffer after the message send is complete. See
the section on buffer management for more details. These are the defined
SCA Functional specification Page 39
Writing a monitor SYSAP
flags for this word:
F.RTB -- 1 - return message send buffer to SCA
0 - return message send buffer to free Q
F.SPM -- 1 - Send mess/datagram in high den mode
0 - Send mess/datagram in industry compat mode
SCA Functional specification Page 40
Writing a monitor SYSAP
5.5.1.8 Queue datagram receive buffers (SC.RDG)
- Queue datagram receive buffers (SC.RDG) -
This routine puts buffers onto the port datagram free queue for you.
Call
BLCAL. (SC.RDG,<SS.CID,SS.NUM,SS.ADR>)
Where:
SS.CID -- Connect ID
If SS.ADR is zero then:
SS.NUM -- Number of buffers to queue
If SS.ADR is non-zero, then:
SS.NUM is ignored, and
SS.ADR -- Address of the buffer to queue. Note that this
buffer must be a buffer procured from SCA. This means it has
been used as a datagram buffer before. This is handy for those
time you are done with an SCA datagram buffer and wish to
requeue it. It eliminated the need for two calls to SCA.
Return (+1)
T1/ Error code
Return (+2)
Buffer(s) have been queued to receive datagrams.
SCA Functional specification Page 41
Writing a monitor SYSAP
5.5.1.9 Send a message (SC.SMG)
- Send a message (SC.SMG) -
This routine sends a message if there are sends credits available
and the circuit is open.
Call
BLCAL. (SC.SMG,<SS.CID,SS.FLG,SS.LMG,SS.AMG,SS.PRI,SS.TSH>)
Where:
SS.CID -- Connect ID
SS.FLG -- Flag word, see SC.SDG for a definition
SS.LMG -- Length of message in bytes
SS.AMG -- Address of message buffer
SS.PRI -- Priority to give message
SS.TSH -- Allow send only if more than this many send credits exist
Return (+1)
T1/ Error code
Return (+2)
No data returned
SCA Functional specification Page 42
Writing a monitor SYSAP
5.5.1.10 Queue message receive buffers (SC.RMG)
- Queue message receive buffers (SC.RMG) -
This routine places buffers onto the port message free queue and
reflects these buffers as receive credit for the given connection.
Call
BLCAL. (SC.RMG,<SS.CID,SS.NRB,SS.AMB>)
Where:
SS.CID -- Connect ID
SS.NRB -- If SS.AMB is zero then this is the number of buffers
to be queued for message reception.
SS.AMB -- Address of message buffer
If SS.AMB is zero then a buffer is taken from the SCA
message buffer free queue. If it is non-zero, then it
is assumed that no problems will arise if the buffer
is returned to the SCA pool. Since it may end up in
the SCA pool it must be the length of all other buffers
in the pool, must have come from the general free
pool,and must be resident.
Return (+1)
T1/ Error code
Return (+2)
Buffer has been queued.
SCA Functional specification Page 43
Writing a monitor SYSAP
5.5.1.11 Cancel datagram receive buffer (SC.CRD)
- Cancel datagram receive buffer (SC.CRD) -
This routine will take buffers off the port datagram free queue. It
will not allow the caller to take more buffers than were queued for the
given connection. The buffers are returned to the SCA free pool and not
to the caller.
Call
BLCAL. (SC.CRD,<SS.CID,SS.NBF>)
Where:
SS.CID -- Connect ID
SS.NBF -- Number of buffers to dequeue
Return (+1)
T1/ Error code
Return (+2)
No data returned, buffer dequeued.
5.5.1.12 Cancel message receive buffers (SC.CRM)
- Cancel message receive buffers (SC.CRM) -
This routine will dequeue buffers from the message free queue. Note
that it will not allow the caller to dequeue more buffers than were
queued for the given connection. The buffers are returned to the SCA
free pool and not to the caller.
Call
BLCAL. (SC.CRM,<SS.CID>)
Where:
SS.CID - The connection ID of connection who's buffer we are canceling
SS.NBD - The number of buffers to dequeue
Return (+1)
T1/ Error code
Return (+2)
No data returned, buffer(s) have been returned to the free pool
SCA Functional specification Page 44
Writing a monitor SYSAP
5.5.1.13 Map a named buffer (SC.MAP)
- Map a named buffer (SC.MAP) -
This routine associates memory with a named buffer. Provided a
descriptor block (shown below) it will get the port driver to give the
buffer to the port.
Call
BLCAL. (SC.MAP,<SS.BLK>)
Where:
SS.BLK -- Address of the first entry in a chain of buffer
descriptor blocks.
Return (+1)
T1/ Error code
Return (+2)
T1/ Buffer name
Buffer descriptor blocks have the following format:
!=======================================================!
.MDNXT ! Address of next buffer descriptor (zero if none) !
!-------------------------------------------------------!
.MDFLG ! Flags !
!-------------------------------------------------------!
.MDLEN ! Length of segment #0 !
!-------------------------------------------------------!
.MDADR ! Address of the segment #0 !
!-------------------------------------------------------!
\ \
\ \
\ segment descriptor pairs \
\ \
\ \
!-------------------------------------------------------!
! Length of buffer segment #n !
!-------------------------------------------------------!
! Address of the segment #n !
!-------------------------------------------------------!
! 0 !
!=======================================================!
The flags word has the following set of flags defined:
1. MD%DMD -- Two bit field indicating buffer mode. The following
settings are defined:
MD%DIC -- Industry compatable
MD%DCD -- Core dump
MD%DHD -- High density
SCA Functional specification Page 45
Writing a monitor SYSAP
All other values are illegal.
Note that .MDNXT and .MDFLG are offsets from the start of the block
to the address of the next entry in the chain, but .MDLEN and .MDADR are
offsets within the words describing a single buffer segment.
SCA Functional specification Page 46
Writing a monitor SYSAP
5.5.1.14 Unmap a buffer (SC.UMP)
- Unmap a buffer (SC.UMP) -
This routine is called to unmap a buffer. Note that this routine
must be called before the buffer will go away. Hence if the routine is
not called after all named buffer transfers are completed the buffer will
stay around forever. This enables the SYSAP to do multiple operations
with the same buffer, without having to map the buffer every time.
Call
BLCAL. (SS.UMP,<SS.NAM>)
Where:
SS.NAM -- Name of buffer to be unmapped
Return (+1)
T1/ Error code
Return (+2)
No data, buffer name is no longer valid
SCA Functional specification Page 47
Writing a monitor SYSAP
5.5.1.15 Send named buffer data (SC.SND)
- Send named buffer data (SC.SND) -
This routine sends block data from a named buffer.
Note:
One receive credit is required to do any named buffer transfer.
Call
BLCAL. (SC.SND,<SS.CID,SS.SNM,SS.RNM,SS.SOF,SS.ROF>)
Where:
SS.CID -- Connection on which this transfer is being done
SS.SNM -- Name of the buffer to get data from
SS.RNM -- Name of buffer to put data into
SS.SOF -- Byte offset into transmission buffer
SS.ROF -- Byte offset into reception buffer
Return (+1)
T1/ Error code
Return (+2)
No data returned.
SCA Functional specification Page 48
Writing a monitor SYSAP
5.5.1.16 Request remote named buffer transfer (SC.REQ)
- Request remote named buffer transfer (SC.REQ) -
This routine requests the transfer of data from a remote data buffer
to a local one. Note that do perform this function the SYSAP must have
at least one receive credit. This is due to the ports use of a message
buffer from the message free queue on a named buffer operation.
Call
BLCAL. (SS.REQ,<SS.CID,SS.NOD,SS.SNM,SS.RNM,SS.SOF,SS.ROF>)
Where:
SS.CID -- Connection on which this transfer is being done
SS.NOD -- Node number of remote host
SS.SNM -- Name of remote buffer to get data from
SS.RNM -- Name of local buffer to put data into
SS.SOF -- Byte offset into transmission buffer
SS.ROF -- Byte offset into reception buffer
Return (+1)
T1/ Error code
Return (+2)
No data returned.
SCA Functional specification Page 49
Writing a monitor SYSAP
5.5.1.17 Connect state poll (SC.CSP)
- Connect state poll (SC.CSP) -
This routine returns information about the state of a connection.
Call
BLCAL. (SC.CSP,<SS.CID,SS.FRE>)
Where:
SS.CID -- Connect ID of target connect
SS.FRE -- Address of a free space block for returned info
Return (+1)
T1/ Failure code
Return (+2)
T1/ Address of returned data
Note that it is the SYSAP that provides the free space for the
return of data. This free space may be from an extended section or
section zero. The format of the retutned data is as follows:
!=======================================================!
.CDCST ! Connection state !
!-------------------------------------------------------!
.CDDCI ! Destination Connect ID !
!-------------------------------------------------------!
.CDDPN ! Byte pointer to destination process name !
!-------------------------------------------------------!
.CDSBI ! Node number !
!-------------------------------------------------------!
.CDACB ! Address of connection block !
!-------------------------------------------------------!
.CDREA ! Source disconnect reasons ! Dest disconnect reasons !
!=======================================================!
The byte pointer to destination process name points to a string in
an SCA database. This is important to realize since the SYSAP must not
change the indicated string.
SCA Functional specification Page 50
Writing a monitor SYSAP
5.5.1.18 Return destination connect ID (SC.DCI)
- Return destination connect ID (SC.DCI) -
This routine returns the remotes identifier for the given
connection.
Call
BLCAL. (SC.DCI,<SS.CID,SS.FRE>)
Where:
SS.CID -- Connect ID for target connection
SS.FRE -- Address of free space into which data is to be returned
Return (+1)
T1/ Error code
Return (+2)
T1/ Destination connect ID for given connection
SCA Functional specification Page 51
Writing a monitor SYSAP
5.5.1.19 Return system configuration data (SC.RCD)
- Return system configuration data (SC.RCD) -
This routine returns information about a system. To discover who is
available on the net simply call this routine for each possible node
number. Node numbers are guarenteed to start at zero and and at
Call
BLCAL. (SC.RCD,<SS.NOD>)
Where:
SS.NOD -- Target node number
Return (+1)
T1/ Failure code
Return (+2)
T1/ Address of configuration data block
The free space into which data is retuedn may be in an extended
section or section zero, and has the following format:
!=======================================================!
.RDSTS ! Virtual circuit state ! Port number !
!-------------------------------------------------------!
.RDSYS \ \
\ System address (6 8-bit bytes, word aligned) \
\ \
!-------------------------------------------------------!
.RDMDG ! Maximum destination datagram size !
!-------------------------------------------------------!
.RDMMS ! Maximum destination message size !
!-------------------------------------------------------!
.RDDST ! Destination software type !
!-------------------------------------------------------!
.RDDSV ! Destination software version !
!-------------------------------------------------------!
.RDDSI ! Destination software incarnation !
!-------------------------------------------------------!
.RDDHT ! Destination hardware type !
!-------------------------------------------------------!
.RDDHV ! Destination hardware version !
!-------------------------------------------------------!
.RDPRT \ \
\ Port characteristics (6 8-bit bytes, word aligned) \
\ \
!=======================================================!
The format of the system name and port characteristics fields are
/TBD/.
SCA Functional specification Page 52
Writing a monitor SYSAP
5.5.1.20 Reset a remote system (SC.RST)
- Reset a remote system (SC.RST) -
This routine sends a maintenance reset to a remote node. No
checking is done as to the node type. If the remote does not honor such
packets then the remote will simply ignore the packet. There is no
direct indication to the local SYSAP as to whether the packet was taken
or ignored.
Call
BLCAL. (SC.RST,<SS.NOD,SS.FRB>)
Where:
SS.NOD -- Node number of node to be reset
SS.FRB -- Force reset bit, if one, reset is forced, if zero,
reset will only be done if we are the last node to do
a reset for this remote
Return (+1)
T1/ Error code
Return (+2)
No data returned, reset packet sent
SCA Functional specification Page 53
Writing a monitor SYSAP
5.5.1.21 Start a node (SC.STA)
- Start a node (SC.STA) -
This routine sends a maintainance start a remote node. No check of
remote node type is done. If the remote node does not honor this packet
type then the remote will simply ignore the packet. No direct indication
of success or failure of the packet at the remote is provided.
Call
BLCAL. (SC.STA,<SS.NOD,SS.DSA,SS.STA>)
Where:
SS.NOD -- Node number of target remote
SS.DSA -- Flag for use of SS.STA, if zero, SS.STA is ignored and
the default start address is used. If non-zero, SS.STA
is used as the start address of the remote.
SS.STA -- Start address for the remote node. Only used if SS.DSA is
non-zero.
Return (+1)
T1/ Error code
Return (+2)
No data returned
SCA Functional specification Page 54
Writing a monitor SYSAP
5.5.1.22 Set port counters (SC.SPC)
- Set port counters (SC.SPC) -
This function sets the port counters for a desired function.
Call
BLCAL. (SC.SPC,<SS.NOD,SS.CTL>)
Where:
SS.NOD -- Node number or 377 for all nodes
SS.CTL -- Control word for port counters, bits as follows:
B0 If on, count ACKs received on Path A.
B1 If on, clear the counter.
B2 If on, count NAKs received on Path A.
B3 If on, clear the counter.
B4 If on, count NO_RSPs received on Path A.
B5 If on, clear the counter.
B6 If on, count ACKs received on Path B.
B7 If on, clear the counter.
B8 If on, count NAKs received on Path B.
B9 If on, clear the counter.
B10 If on, count NO_RSPs received on Path B.
B11 If on, clear the counter.
B12 The count of discarded datagrams because
of no DGFree Queue entries.
B13 If on, clear the counter.
B14 Count the packets transmitted to the
designated port.
B15 If on, clear the counter.
B16 Count the packets received from the
designated port.
B17 If on, clear the counter.
Return (+1)
T1/ Error code
Return (+2)
No data retutned, port counters set
SCA Functional specification Page 55
Writing a monitor SYSAP
5.5.1.23 Read port counters (SC.RPC)
- Read port counters (SC.RPC) -
This routine returns the values of the port counters. It is an
asynchronous event. The routine will return immediatly but the answer
will occur as the .SSRPC callback.
Call
BLCAL. (SC.RPC,<SS.ADR>)
Where:
SS.ADR -- Address of SCA allocated buffer into
which data is to be returned
Return (+1)
T1/ Error code
Return (+2)
No data returned, .SSRPC callback will happen
when data is ready
SCA Functional specification Page 56
Writing a monitor SYSAP
5.5.1.24 Maintainance data send (SC.MDS)
- Maintainance data send (SC.MDS) -
This routine requests a block tranfser write, in maintainance mode. No
SCA connection or port circuit are required for this function. The
buffer must have been mapped with the SC.MAP call however.
Call
BLCAL. (SC.MDS,<SS.NOD,SS.SNM,SS.RNM,SS.XOF,SS.ROF,SS.ADR>)
Where:
SS.NOD -- Node number of target system
SS.SNM -- Local buffer name for transfer
SS.RNM -- Remote buffer name for transfer
SS.XOF -- Transmit offset (in words)
SS.ROF -- Receive offset (in words)
SS.ADR -- Address to call when transfer is compelte
Return (+1)
T1/ Error code
Return (+2)
No data returned, notification by .SSMNT callback when completed
SCA Functional specification Page 57
Writing a monitor SYSAP
5.5.1.25 Maintainance data read (SC.MDR)
- Maintainance data read (SC.MDR) -
This routine requests a block tranfser read, in maintainance mode.
No SCA connection or port circuit are required for this function. The
buffer must have been mapped with the SC.MAP call however.
Call
BLCAL. (SC.MDR,<SS.NOD,SS.SNM,SS.RNM,SS.XOF,SS.ROF,SS.ADR>)
Where:
SS.NOD -- Node number of target node
SS.SNM -- Remote buffer name for transfer
SS.RNM -- Local buffer name for transfer
SS.XOF -- Transmit offset (in words)
SS.ROF -- Receiver offset (in words)
SS.ADR -- Address to call when transfer is complete
Return (+1)
T1/ Error code
Return (+2)
No data returned, .SSMNT callback when complete
SCA Functional specification Page 58
Writing a monitor SYSAP
5.5.1.26 Set online address (SC.SOA)
- Set online address (SC.SOA) -
Notification of a node coming online happens on a per SYSAP basis
rather than on a per connection basis. Hence SCA must have an address
for each SYSAP that wishes to be called when a new VC has been opened.
This routine sets the online address for the SYSAP. Note that this
routine does not know who calls it and will simply add this address to
the list of notification addresses. It does not try to delete old
entries if called twice by the same SYSAP.
Note that this call will only allow .SSNCO callbacks to occur. All
other callbacks are done through the address specified at connect or
listen time.
Call
BLCAL. (SC.SOA,<SS.ADR>)
Return (+1)
T1/ Error code
Return (+2)
No data, address saved
SCA Functional specification Page 59
Writing a monitor SYSAP
5.5.1.27 Swap bytes from 11 to 10 format (SC.ISW)
- Swap bytes from 11 to 10 format (SC.ISW) -
This support routine swaps a single PDP-11 format word into a PDP-10
format word. Since this is a popular thing to do when talking to the HSC
and friends this routine is global for access by the rest of the monitor.
Call
T1/ Word to be swapped
Return (+1) Always
T1/ Byte swapped word
Input format:
2 16 bit half words, left justified
!=======================================================!
! B (lsb) ! B (msb) ! A (lsb) ! A (msb) ! IGN !
!=======================================================!
0 7 8 15 16 23 24 31 32 35
Where A and B are the half words, and (lsb) are the least significant bits
and (msb) are the most significant bits.
The contents of bits 32 thru 35 are ignored.
Output format:
2 18 bit half words,
!=======================================================!
!X! Byte A (msb+lsb) !X! Byte B (msb +lsb) !
!=======================================================!
0 2 17 20 35
X denotes the 2 bit field within each halfword that
will always be zero.
SCA Functional specification Page 60
Writing a monitor SYSAP
5.5.1.28 SC.OSW (Swap word from 10 to 11 forma
- SC.OSW (Swap word from 10 to 11 format)
This routine swaps a single word from PDP-10 format to PDP-11
format. Rather than be yet another in the long list of byte swappers,
this routine is globally available to the rest of the monitor (in
particular SYSAPs).
Call
T1/ Word to swap
Return (+1) Always
T1/ Byte swapped word
Input format:
2 18 bit half words,
!=======================================================!
! Byte A (msb+lsb) ! Byte B (msb +lsb) !
!=======================================================!
0 17 18 35
Output format:
2 16 bit half words, left justified
!=======================================================!
! B (lsb) ! B (msb) ! A (lsb) ! A (msb) ! IGN !
!=======================================================!
0 7 8 15 16 23 24 31 32 35
Where A and B are the half words, and (lsb) are the least significant bits
and (msb) are the most significant bits.
SCA Functional specification Page 61
Writing a monitor SYSAP
5.5.1.29 Return node number given CID (SC.SBI)
- Return node number given CID (SC.SBI) -
This routine returns the node number of the remote end of the given
CID.
Call
BLCAL. (SC.SBI,<SS.CID>)
Where:
SS.CID -- Connect ID of target connection
Return (+1) Always
T1/ Local connect ID
T2/ Node number of the remote end of the connection specified
SCA Functional specification Page 62
Writing a monitor SYSAP
5.5.1.30 Return credit info (SC.RAC)
- Return credit info (SC.RAC) -
This routine returns the current credit levels for a particular
connection. This routine is not interlocked, hence the credit counts may
be incorrect by the time SCAMPI returns from the PUSHJ. The usual case
is SCAMPI is interrupted in the middle of this routine by a message
arriving for this connection. This means the receive credits will be
wrong. If the SYSAP sends a reply at interrupt level the send credits
will be wrong as well. Since most connections maintain a large number of
credits this routine will at least give a ballpark figure. If the SYSAP
knows that it will not be getting any messages or if it calls this
routine CIOFF then the counts will be correct.
Call
BLCAL. (SC.RAC,<SS.CID>)
Where:
SS.CID -- Connect ID of connection whose credits
are desired
Return (+1)
T1/ Error code
Return (+2)
T1/ Send credit
T2/ Receive credit
T3/ Number of datagram buffers queued
SCA Functional specification Page 63
Writing a monitor SYSAP
5.5.1.31 Return local port number (SC.PRT)
- Return local port number (SC.PRT) -
This routine returns the node number of the local node. The
assumption is made that this is a KL with only one KLIPA.
Call
No arguments
Return (+1)
Error code
Return (+2)
T1/ Local node number
T2/ Reserved
T3/ Reserved
T4/ Reserved
SCA Functional specification Page 64
Writing a monitor SYSAP
5.5.1.32 Allocate a datagram buffer (SC.ALD)
- Allocate a datagram buffer (SC.ALD) -
This routine will allocate datagram buffers from the SCA free pool.
It is from this pool that all buffers on the port free queues originated.
If desired the SYSAP can use buffers from this pool for outgoing
datagrams and have the buffer placed on the port free queue on
transmission completion.
When more than one buffer has been requested, the buffers are
chained together with the link in the zeroth word of each buffer. The
link word always points to word zero of the next buffer. The last buffer
has a link word of zero.
Call
T1/ Number of buffers desired
Return (+1)
T1/ Error code
Return (+2)
T1/ Address of first buffer on chain
T2/ Number of buffers returned
T3/ Address of routine to return buffers
SCA Functional specification Page 65
Writing a monitor SYSAP
5.5.1.33 Allocate a message buffer (SC.ABF)
- Allocate a message buffer (SC.ABF) -
This routine allocates message buffers from the SCA free pool. If
desired the SYSAP may use these buffers for message transmission and have
the buffer placed on the port free queue on send completion. Also note
that these buffers have the invisible area described in the section on
SCA buffers.
When more than one buffer has been requested, the buffers are
chained together with the link in the zeroth word of each buffer. The
link word always points to the zeroth word of the next buffer. The last
buffer has a link word of zero.
Call
T1/ Number of buffers desired
Return (+1)
T1/ Error code (No buffers returned)
Return (+2)
T1/ Address of first buffer on chain
T2/ Number of buffers returned
T3/ Address of routine to return buffers
SCA Functional specification Page 66
Writing a monitor SYSAP
5.5.1.34 Return a message buffer (SC.RBF)
- Return a message buffer (SC.RBF) -
This routine is used to return buffers to the SCA free pool
allocated with SC.ABF. Although buffers can be allocated in chains, they
may not be returned that way. A buffer is returned one at a time. Hence
the link word of the buffer is ignored.
Call
T1/ Address of buffer to be returned
Return (+1) Always
No data returned, buffer returned OK
5.5.1.35 Return a datagram buffer (SC.RLD)
- Return a datagram buffer (SC.RLD) -
Datagram buffer allocated with SC.ALD must be returned to the SCA
free pool with this routine. Although buffers may be allocated in
chains, they must be returned one at a time. Hence the link word in each
buffer is ignored.
Call
T1/ Address of buffer to be returned
Return (+1) Always
No data returned, buffer has been returned
to SCA free pool
SCA Functional specification Page 67
Writing a monitor SYSAP
5.5.2 SCA to SYSAP interface
The following is the complete set of callbacks that the SYSAP can
expect to see from SCA.
General format of returned information:
T1/ Function code
T2-T4/ Function code dependant additional data
Context: List of possible contexts for this callback. I.E.
the contexts the SYSAP may see during this callback
- - - - - - - - - -
.SSDGR
Datagram received. SCA is indicating that the CI has filled one of the buffers
queued for datagram reception with a datagram.
T1/ .SSDGR
T2/ Connect ID
T3/ Address of datagram buffer
T4/ <FLAGS>B5 ! <Addr of routine to return buffer>B35
(See SC.SDG for flag definitions)
.MHPKL word of datagram buffer/
Length of the packet (Bytes for industry compatable, words
for high density)
Context: Interrupt
- - - - - - - - - -
.SSMGR
Message received. SCA is indicateing that you have received a message from the
CI.
T1/ .SSMGR
T2/ Connect ID
T3/ Address of message buffer
T4/ <FLAGS>B5 ! <Addr of routine to return buffer>B35
(See SC.SDG for flag definitions)
.MHPKL word of msg buffer/
Length of the packet (Bytes for industry compatable, words
for high density)
Context: Interrupt
- - - - - - - - - -
.SSPBC
Port broke connection. The port hardware detected a fatal error for the
port virtual circuit on which you had a connection. Thus it broke your
connection.
T1/ .SSPBC
T2/ Connect ID
T3/ Unused
SCA Functional specification Page 68
Writing a monitor SYSAP
T4/ Unused
Context: Interrupt, scheduler
- - - - - - - - - -
.SSCTL
Connection to listen. The listen done for you has been matched to a remote
connect request.
T1/ .SSCTL
T2/ Connect ID
T3/ Address to connection data from remote system
T4/ Unsued
Context: Interrupt
- - - - - - - - - -
.SSCRA
Connection response available. The system to which you sent a connect message
has responded.
T1/ .SSCRA
T2/ Connect ID
T3/ -1 for accepted, 0 for rejected connection
T4/ Reject code (If rejected), pointer to connect data if accepted
Context: Interrupt
- - - - - - - - - -
.SSMSC
Message/datagram Send complete. The message/datagram which you requested be
sent, has been. The "buffer address" is the address of the buffer you gave
SCA to send.
T1/ .SSMSC
T2/ Connect ID
T3/ Address of buffer
T4/ Length of buffer in bytes for ind. compat/words for high den
This is the length of the text portion, and does not
include SCA headers.
Context :Interrupt
- - - - - - - - - -
.SSLCL
Little credit left. You have just received a message that put you under
receive credit threshold. It is suggested that you queue at least some buffers
if you expect to get more messages. Note that you will receive one of these
calls every time you receive a message after which you are under threshold.
T1/ .SSLCL
T2/ Connect ID
T3/ Number of credits needed to get you over threshold
T4/ Unused
SCA Functional specification Page 69
Writing a monitor SYSAP
Context: Interrupt
- - - - - - - - - -
.SSNCO
Node came online. You requested to be told of nodes coming online.
It happened and now you're being told.
T1/ .SSNCO
T2/ Node number of system that has come online
T3/ Unused
T4/ Unused
Context: Interrupt, scheduler
- - - - - - - - - -
.SSOSD
OK to send data. The connection has been completed to a remote system and is
now in the OPEN state. Messages and datagram may be sent.
T1/ .SSOSD
T2/ Connect ID
T3/ Unused
T4/ Unused
Context: Interrupt
- - - - - - - - - -
.SSRID
Remote initiated disconnect. The host at the other end of your connection
doesn't want to talk to you anymore and has completed an orderly shutdown of
your connection.
T1/ .SSRID
T2/ Connect ID
T3/ Unused
T4/ Unused
Context: Interrupt
- - - - - - - - - -
.SSCIA
Credit is available. Your message send failed for lack of credit. There is
now more credit available for your send.
T1/ .SSCIA
T2/ Connect ID
T3/ Current send credit
T4/ Current receive credit
Context: Interrupt
SCA Functional specification Page 70
Writing a monitor SYSAP
- - - - - - - - - -
.SSNWO
Node went offline. The remote end of your connection has just dropped
offline. After this callback, all data about the connection will be deleted.
T1/ .SSNWO
T2/ CID for connect you had on offline node
T3/ Unused
T4/ Unused
Context: Interrupt, scheduler
- - - - - - - - - -
.SSDMA
Named buffer operation complete. The named buffer operation you requested
has been completed. Note that you will NOT be told about the completion of
passive requests. I.E. you will not be notified when a request/send data
done by a remote completes.
T1/ .SSDMA
T2/ Connect ID of connection tranfers was done for
T3/ Buffer name of named buffer
T4/ Unused
Context: Interrupt
- - - - - - - - - -
.SSDDG
Dropped datagram. SCA received a datagram for this connection and dropped it
since you had no buffers left. The buffer was returned to the port free queue.
Note that this is a software detected datagram drop. If the port drops the
datagram because there are no buffers on the port queue, this call back will
not happen.
T1/ .SSDDG
T2/ Connect ID
T3/ Unused
T4/ Unused
Context: Interrupt
- - - - - - - - - -
.SSMNT
Maintainance data send/receive complete.
T1/ .SSMNT
T2/ Buffer name of completed transfer
T3/ Unused
T4/ Unused
SCA Functional specification Page 71
Writing a monitor SYSAP
Context: Interrupt
- - - - - - - - - -
.SSRPC
Read port counters response. The request for reading the port counters has
completed and here is your answer.
T1/ .SSRPC
T2/ Connect ID of requesting connect
T3/ Address of packet containing counter data
T4/ Unused
The following is the format of the counter data:
!=======================================================!
\ \
\ Port header \
\ \
!-------------------------------------------------------!
.PCMCV ! Microcode version !
!-------------------------------------------------------!
.PCAAC ! Path A ACK count !
!-------------------------------------------------------!
.PCANC ! Path A NAK count !
!-------------------------------------------------------!
.PCANR ! Path A no response count !
!-------------------------------------------------------!
.PCBAC ! Path B ACK count !
!-------------------------------------------------------!
.PCBNC ! Path B NAK count !
!-------------------------------------------------------!
.PCBNR ! Path B no response count !
!-------------------------------------------------------!
.PCDGD ! Datagrams discarded !
!-------------------------------------------------------!
.PCPTX ! Packets transmitted !
!-------------------------------------------------------!
.PCPRX ! Packets received !
!-------------------------------------------------------!
.PCDPT ! Designated port !
!-------------------------------------------------------!
\ \
\ Reserved for software \
\ \
!=======================================================!
SCA Functional specification Page 72
Writing a JSYS SYSAP
6.0 Writing a JSYS SYSAP
This section is a detailed review of the differences between writing
monitor level SYSAPs and user level SYSAPs. The concepts are identical
for the two SYSAP types, but the implementation details are very
different. In the reading of the following sections it is assumed that
the sections on monitor level SYSAPs has been read.
6.1 General rules
6.1.1 Communicating with SCA
When writing monitor level code SYSAPs communicate with SCA through
subroutine calls. The SYSAP obtains services from SCA by calling
routines in SCA, and SCA returns event information by calling routine
addresses specified by the SYSAP. When writing JSYS code, services are
obtained by executing the JSYS, and SCA communicates event information
through a series of PSIs. In all there are four PSIs that the JSYS level
SYSAP may have to handle. One each for incoming messages, datagrams,
named buffer completions and all other events. If the SYSAP does not
require some of these services then the PSI need not be enabled.
6.1.1.1 Using the SCS% with the PSI system
When using the PSI system with SCA keep in mind that the SCS% call
to add channel must be done in addition to the usual set of JSYS calls.
The SCS% call simply lets SCA know which channels are to be used for
which event types. The SIR%, AIC%, EIR% (and their extended third
cousins) etc. must still be used to specify and enable the PSI system.
6.1.2 Buffer management
Buffer management for the JSYS SYSAP is very different than that
done for monitor SYSAPs. There are still four basic buffer types,
messages and datagrams, both of which can be incoming or outgoing.
6.1.2.1 Incoming buffers
Buffers queued for reception of messages and datagrams must be large
enough to handle the largest packet possible. The correct buffer size
for messages is thirty eight (38) words, for datagrams this size is one
hundred fifty two (152) words. These buffers are queued in chains much
the way they are in the monitor. These buffers are not placed on the
port queues however. Monitor internal buffers are placed on the port
queues and data is BLTed to user space when it arrives. When data is
moved the length to be BLTed is obtained from the packet. Hence if the
SCA Functional specification Page 73
Writing a JSYS SYSAP
buffer is to short the end of the buffer will be BLTed over. This is why
the buffer must be at least as long as the longest packet possible.
6.1.2.2 Outgoing buffers
Buffers used for packets transmission need only be as long as the
packet text. There are no other restrictions on these buffers.
6.1.3 The race condition
Something which comes up when coding a monitor SYSAP is that
interlocking further CI traffic is easy. JSYS SYSAPs do not have things
quite so simple. In particular there is a race that a JSYS SYSAP
designer should be aware of. When a JSYS SYSAP does a listen, he is told
about a connection to that listen with a PSI. As soon as the connection
comes in and the match is found, the monitor changes the state of the
connect to connectreceived rather than listen. Hence if another connect
request comes in for that SYSAP before it has been told about the first
connect request, then the second one will fail at the SCA level since no
match can be found even though the SYSAP would likely want to see that
connect.
One reasonable solution to this problem is based on an understanding
of the problem by both the active and passive sides of the connect
mechanism. The listener should open more than one listen (keeping in
mind that they do use system resources), and the connector should retry
connect attempts if they fail.
SCA Functional specification Page 74
Writing a JSYS SYSAP
6.2 JSYS SYSAP interface
The following is the general format of a call to the SCS% JSYS.
Call
T1/ Function code
T2/ Address of arg block
Return (+1) Always
T1/ Function code
T2/ Address of arg block
An error generates an illegal instruction trap.
General format of the argument block:
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
\ \
\ Function dependent arguments \
\ \
!=======================================================!
Where the "words processed" is the number of words in the argument
block that the monitor actually looked at and used. Hence this field is
returned by the monitor, not supplied by the user. The "length of block"
is the total length of the supplied block including the header word.
Note that this JSYS requires one or any combination of wheel,
maintenance, or network wizard.
SCA Functional specification Page 75
Writing a JSYS SYSAP
6.2.1 Connect (.SSCON)
Connect (.SSCON)
This function requests a connection with another process on the CI.
The JSYS will return as soon as the connection request has been sent.
You are notified that your connection request was granted or failed via a
PSI interrupt.
The argument block has the following format:
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
.SQSPN ! Byte pointer to source process name !
!-------------------------------------------------------!
.SQDPN ! Byte pointer to destination process name !
!-------------------------------------------------------!
.SQSYS ! Node # of destination ! SYSAP field for CID !
!-------------------------------------------------------!
.SQCDT ! Pointer to connection data !
!-------------------------------------------------------!
.SQAMC ! Address of first buffer on message buffer chain !
!-------------------------------------------------------!
.SQADC ! Address of first buffer on datagram buffer chain !
!-------------------------------------------------------!
.SQRCI ! Returned connect ID !
!=======================================================!
The byte pointer to the source process name is a byte pointer to the
ASCII string which is the name of your process. Note that this string
must end on a null byte and may be a maximum of 16 bytes long, not
including the null byte.
The byte pointer to destination process name is the byte pointer to the
name of the process you wish to connect to. This name must also end in a
null byte and may be a maximum of 16 bytes, not including the null byte.
The node number is the unique identifier of the system you wish to
connect to.
Note that the specified strings may be any valid ASCII byte size (I.E.
any byte size equal to or larger than 7 bits). These strings may also be
generic byte pointers (-1,,STRNG). If generic byte pointers are given, 7
bit ASCII terminated by a null byte is assumed.
The "SYSAP field for CID" is the right justified value to be placed into
the SYSAP field of the connect ID created for the connection. These bits
are generally used for connection management by the user program.
SCA Functional specification Page 76
Writing a JSYS SYSAP
The pointer to connection data is the address of a block of data SQ%CDT
words long to be sent as connection data. Note that the monitor will
copy SQ%CDT words of data from the users address space. Hence a full
block SQ%CDT words long should be allocated for the data.
- Error codes -
SCSNEP,SCSBTS,SCSISB,SCSNSN,SCSENB,SCSIAB,SCSIBP,SCSNBA
SCA Functional specification Page 77
Writing a JSYS SYSAP
6.2.2 Listen (.SSLIS)
Listen (.SSLIS)
This function listens for a connection. Note that the JSYS does not
block. You will be notified of a connect to your listen via a PSI
interrupt.
There are a number of options that may be used when doing a listen
for a connection. You may listen for a particular process from any
system by making the node number -1. You may listen for any process from
a particular system by making the byte pointer to the destination process
name -1. If the node number and the byte pointer to the destination
process name are both -1, then any connect request that is not for a
particular process name will match your listen. Naturally you may
specify both a node number and a process name and then only that process
from the named system will be allowed to connect to your listen.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQSPN ! Byte pointer to source process name !
!-------------------------------------------------------!
.SQDPN ! Byte pointer to destination process name !
!-------------------------------------------------------!
.SQSYS ! Node # of destination ! SYSAP field for CID !
!-------------------------------------------------------!
.SQLCI ! Returned connect ID !
!=======================================================!
The fields defined here are identical to those used by the connect
call. The only difference is the absence of some of the fields used in
the connect call.
- Error codes -
SCSNBA,SCSNEP,SCSBTS,SCSISB,SCSNSN,SCSENB
SCA Functional specification Page 78
Writing a JSYS SYSAP
6.2.3 Accept (.SSACC)
Accept a connection (.SSACC)
This function tells a remote process that you are granting his
request for a connection.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQCDA ! Pointer to connection data !
!=======================================================!
The pointer to connection data is the address of the block of
connection data to be sent to the remote system. The monitor will copy
SQ%CDT words of data from the users address space as data. Note that
this data will be sent directly over the CI and hence the low order four
bits are not sent.
- Error codes -
SCSNEP,SCSBTS,SCSIID,SCSCWS,SCSNBA
SCA Functional specification Page 79
Writing a JSYS SYSAP
6.2.4 Reject (.SSREJ)
Reject a connection (.SSREJ)
This function code tells a remote process that you are not allowing
a connection to your process.
The argument block for this function has this format:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQREJ ! Rejection reason !
!=======================================================!
The rejection reason is a code, invented by the SYSAP, (outside the
revserved range /TBD/ codes) which indicates why the connection was
rejected.
- Error codes -
SCSBTS,SCSIID,SCSNBA,SCSCWS,SCSNEP
SCA Functional specification Page 80
Writing a JSYS SYSAP
6.2.5 Disconnect (.SSDIS)
Disconnect (.SSDIS)
This function closes a connection. Note that the connection must be
open to use disconnect. The disconnect function code requires the
following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQDIS ! Disconnect reason !
!=======================================================!
The disconnect reason is a SYSAP invented code (outside the reserved
range /TBD/) which indicates why the connection was disconnected.
- Error codes -
SCSNEP,SCSBTS,SCSIID,SCSCWS,SCSNBA
SCA Functional specification Page 81
Writing a JSYS SYSAP
6.2.6 Send a DG (.SSSDG)
Send a datagram (.SSSDG)
This function code sends a datagram.
The following arguments are required:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQAPT ! Address of datagram text !
!-------------------------------------------------------!
.SQLPT ! Len of message,high density (words), industry (bytes) !
!-------------------------------------------------------!
.SQFLG ! Flags ! OPS !
!=======================================================!
OPS is the path selection field. OPS allows the JSYS user to select
the path over which the packet is to be sent. The following setting are
allowed for OPS:
0 --> Automatic path selection
1 --> Use path A
2 --> Use path B
If automatic path selection is chosen, the port hardware selects the
path to use.
The currently defined flags are:
SC%MOD --> Packet transmission mode: 0 = industry compatable
1 = high density
*** Restrictions ***
1. If the datagram is to be sent in industry compatable mode, the text
must be packed in left justified, word aligned, eight bit bytes.
2. The datagram text may not be longer than 152 (decimal) words/608
bytes long. The byte count is for industry compatable packets and
the word count for high density packets.
- Error codes -
SCSNEP,SCSBTS,SCSIID,SCSDCB,SCSIAA,SCSNBA,SCSCWS,SCAMTL
SCA Functional specification Page 82
Writing a JSYS SYSAP
6.2.7 Queue a DG buffer (.SSQRD)
Queue a buffer for datagram reception (.SSQRD)
This function code queues buffers for datagram reception.
Note that in each buffer the first word is the address of the next
buffer. The last buffer has zero as the address of the next buffer.
This function requires these arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQAFB ! Address of first buffer on buffer chain !
!=======================================================!
*** Restrictions ***
1. Datagram buffers must be 152 words in length.
- Error codes -
SCSNEP,SCSIID,SCSNBA,SCSBTS
SCA Functional specification Page 83
Writing a JSYS SYSAP
6.2.8 Send message (.SSSMG)
Send a message (.SSSMG)
This function code sends a message to a remote node.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQAPT ! Address of message text !
!-------------------------------------------------------!
.SQLPT ! Len of message,high density (words), industry (bytes)!
!-------------------------------------------------------!
.SQFLG ! Flags ! OPS !
!=======================================================!
OPS is the path selection field. OPS allows the JSYS user to select
the path over which the packet is to be sent. The following setting are
allowed for OPS:
0 --> Automatic path selection
1 --> Use path A
2 --> Use path B
If automatic path selection is chosen, the port hardware selects the
path to use.
The flags definitions may be found in the section for .SSSDG.
*** Restrictions ***
1. If this is an industry compatable message then the text must be
packed in left justified 8 bit bytes.
2. Message text may not be longer than 38 36 bit words (152 bytes).
- Error codes -
SCSIID,SCSNEP,SCSNBA,SCSBTS,SCSNSH,SCSDCB,SCSIAA
SCA Functional specification Page 84
Writing a JSYS SYSAP
6.2.9 Queue message receive buffers (.SSQRM)
Queue message receive buffers (.SSQRM)
This function code queues buffers to receive messages. Note that
the buffer size is fixed at 38, 36 bit words. It requires the following
arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQAFB ! Address of buffer chain to queue !
!=======================================================!
- Error codes -
SCSNEP,SCSIID,SCSNBA,SCSBTS
SCA Functional specification Page 85
Writing a JSYS SYSAP
6.2.10 Cancel DG receive (.SSCRD)
Cancel datagram receive (.SSCRD)
This function code removes a buffer queued for datagram reception.
The address that you specify must be the address of a buffer that was
previously queued for receiving datagrams (with .SSQRD). If this address
is not found by the monitor when it goes to take the buffer out of its
queue, the JSYS fails with an illegal instruction trap. This function
requires these arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQADB ! Address of buffer to dequeue !
!=======================================================!
- Error codes -
SCSNSC,SCSNEP,SCSBTS,SCSNSB,SCSNEB
SCA Functional specification Page 86
Writing a JSYS SYSAP
6.2.11 Cancel receive message (.SSCRM)
Cancel receive message (.SSCRM)
The function dequeues a buffer that was queued for message
reception. The buffer address that is specified must be of a buffer that
you asked to be queued for message reception (with .SSQRM). If the
monitor does not find the address specified in the argument block amongst
the buffers you queued, the JSYS will fail. This function requires the
following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQADB ! Address of buffer to dequeue !
!=======================================================!
- Error codes -
SCSNSC,SCSNEP,SCSBTS,SCSNSB,SCSNEB
SCA Functional specification Page 87
Writing a JSYS SYSAP
6.2.12 Connect state poll (.SSCSP)
Connect state poll (.SSCSP)
This function returns information about the state of a connection.
The argument block to this function includes space for the returned data.
The following is the format or the argument block:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------! ------------
.SQCST ! Connection state ! ^
!-------------------------------------------------------! !
.SQDCI ! Destination connect ID ! !
!-------------------------------------------------------! Returned
.SQBDN ! Byte pointer to destination process name ! data
!-------------------------------------------------------! !
.SQSBI ! Node number of destination ! !
!-------------------------------------------------------! !
.SQREA ! Source disconnect reasons ! Dest disconnect reasons ! v
!=======================================================! ------------
Note that the byte pointer to destination process name must be
provided by the caller and may be either a real byte pointer or minus one
in the left half and the base address of the string in the right half.
If the generic byte pointer is used the monitor assumes the string is 7
bit ASCII terminted with a null byte, or the 16th chatacter, whichever
comes first.
- Error codes -
SCSNEP,SCSBTS,SCSIID
SCA Functional specification Page 88
Writing a JSYS SYSAP
6.2.13 Return local node number (.SSGLN)
Return local node number (.SSGLN)
This function returns the local node number. If the machine does
not have a KLIPA, then an illegal instruction is generated. The
following is the argument block format:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQLNN ! Local CI node number ! Returned data
!=======================================================!
- Error codes -
SCSBTS,SCSNKP
SCA Functional specification Page 89
Writing a JSYS SYSAP
6.2.14 Return configuration data (.SSRCD)
Return configuration data (.SSRCD)
This function returns data about another system. Given the node
number the monitor will return data about that system. The data is
returned in the block pointed to by T1 which looks like this:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Optional connect ID !
!-------------------------------------------------------!
.SQOSB ! Optional node number !
!-------------------------------------------------------! -----------
.SQVCS ! Virtual circuit state ! Port number ! ^
!-------------------------------------------------------! !
.SQSAD \ \ !
\ System address (6 8-bit bytes, word aligned) \ !
\ \ !
!-------------------------------------------------------! !
.SQMDD ! Maximum destination datagram size ! !
!-------------------------------------------------------! !
.SQMDM ! Maximum destination message size ! Returned
!-------------------------------------------------------! data
.SQDST ! Destination software type ! !
!-------------------------------------------------------! !
.SQDSV ! Destination software version ! !
!-------------------------------------------------------! !
.SQDSE ! Destination software edit level ! !
!-------------------------------------------------------! !
.SQDHT ! Destination hardware type ! !
!-------------------------------------------------------! !
.SQDHV ! Destination hardware version ! !
!-------------------------------------------------------! !
.SQPCW \ Port characteristics bytes \ !
\ 6, 8 bit bytes, word aligned in leftmost 32 bits \ !
!-------------------------------------------------------! !
.SQLPN ! Local port number ! v
!=======================================================! ------------
The connect ID and node number are optional in that one or the other
must be specified, but not both. If the connect ID field is non-zero
then the node number is ignored and the information returned is for the
system implied by the connect ID. If the connect ID field is zero then
the node number is used. Note that this allows the use of node zero.
If the local port number is not available, -1 will be returned to
the user in offset .SQLPN.
SCA Functional specification Page 90
Writing a JSYS SYSAP
- Error codes -
SCSNEP,SCSBTS,SCSIID,SCSISB
SCA Functional specification Page 91
Writing a JSYS SYSAP
6.2.15 Return buffer sizes (.SSRBS)
Return buffer sizes (.SSRBS)
This function returns the sizes of the various buffers SCA expects
to see. In particular it returns the size of message and datagram
buffers. It requires the following arguments:
!=======================================================!
.SQLEN ! Process words ! Block length !
!-------------------------------------------------------! -------------
.SQLMG ! Length in words of message buffers ! ^
!-------------------------------------------------------! !
.SQLDG ! Length in words of datagram buffers ! Returned
!-------------------------------------------------------! data
! Reserved ! !
!-------------------------------------------------------! !
! Reserved ! v
!=======================================================! -------------
SCA Functional specification Page 92
Writing a JSYS SYSAP
6.2.16 Return status information (.SSSTS)
Return status information (.SSSTS)
This function returns status information about a connection. It is
intended as a fast form of the .SSCSP function code which returns
detailed information about a connection. This function requires the
following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQFST ! Flags ! Connect state ! -------------
!-------------------------------------------------------! Returned
.SQSBR ! Reserved ! Node # of remote ! data
!=======================================================! -------------
The flags which appear in the flags field are:
1. Message available (SQ%MGA)- There is at least one message available
for this connection.
2. Datagram available (SQ%DGA) - There is at least one datagram
available for this connection.
3. Named buffer transfer complete (SQ%DMA) - At least one named buffer
transfer has completed since the last time the SCS% JSYS was
performed with this function code. The bit is cleared in the monitor
data base when this function code is performed.
- Error codes -
SCSBTS,SCSNEP,SCSIID
SCA Functional specification Page 93
Writing a JSYS SYSAP
6.2.17 Get a queue entry
There are four functions for removing things from queues. One each
for messages, datagrams, named buffer transfer competions, and "all other
events". In each case the monitor will issure a PSI for the appropriate
fork when when of these queues goes non-empty. The monitor will not
issue a PSI for each entry. It is the responsibility of the SYSAP to
empty the queue once it has seen the PSI.
6.2.17.1 Receive a message (.SSRMG)
Receive a message (.SSRMG)
This function code returns message text for either the calling fork
or the specified connection. If the connect ID field in the argument
block is minus one, then the first message found for the calling fork is
returned. If the connect ID is anything but minus one (-1), the monitor
will use this as a connect ID and return the first message found for that
connection. Note that if there is no message available an illegal
instruction is generated. The following argument block is required for
this function code.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------! -----------
.SQCID ! Connect ID or -1 ! ^
!-------------------------------------------------------! !
.SQARB ! Address of returned buffer ! !
!-------------------------------------------------------! Returned data
.SQDFL ! Flags ! Node # of remote ! !
!-------------------------------------------------------! !
.SQLRP ! Length of returned packet ! v
!=======================================================! -----------
The address of returned buffer is the address at which the monitor
has placed your data. This address is one of the addresses previously
specifed by a .SSQRM call. If no .SSQRM call was done, then this
function code will fail with an illegal instruction trap. If the address
is not writable you will also get an illegal instruction trap.
The flag definitions may be found in the section on SC.SDG.
The length of the returned packet is in bytes for an industry
compatible mode message, and words for a high density mode packet. It is
always the length of the packet text, and does not include the SCA
headers.
- Error codes -
SCSNEP,SCSBTS,SCSIID,SCSQIE,SCSNUB
SCA Functional specification Page 94
Writing a JSYS SYSAP
6.2.17.2 Receive a datagram (.SSRDG)
Receive a datagram (.SSRDG)
This function code returns datagram text for either the calling fork or
the specified connection. If the connect ID field in the argument block
is minus one, then the first datagram found for the calling fork is
returned. If the connect ID is anything but minus one (-1), the monitor
will use this as a connect ID and return the first datagram found for
that connection. This is the argument block for this function code:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------! -----------
.SQCID ! Connect ID or -1 ! ^
!-------------------------------------------------------! !
.SQARB ! Address of returned buffer ! !
!-------------------------------------------------------! Returned data
.SQDFL ! Flags ! Node # of remote ! !
!-------------------------------------------------------! !
.SQLRP ! Length of returned packet ! v
!=======================================================! -----------
The address of returned data is one of the addresses provided to the
monitor on a .SSQRD call. If no .SSQRD was done or if the address is not
writable, the JSYS will fail with an illegal instruction trap. If there
are no datagrams available, an illegal instruction is generated.
The flags are returned by the monitor and currently only indicate
the data packing mode.
The length of the returned packet is in words if this is a high
density datagram, and bytes if an industry compatible datagram.
- Error codes -
SCSNEP,SCSBTS,SCSIID,SCSQIE,SCSNDQ,SCSNBA
SCA Functional specification Page 95
Writing a JSYS SYSAP
6.2.17.3 Get entry from data queue (.SSGDE)
Get entry from data queue (.SSGDE)
This function code returns the first entry from the data request
complete queue. The argument block follows:
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID or -1 !
!-------------------------------------------------------!
.SQBID ! Name of buffer whos transfer completed !
!=======================================================!
The buffer name indicates which transfer has completed.
- Error codes -
SCSNEP,SCSIID,SCSBTS,SCSIAB
SCA Functional specification Page 96
Writing a JSYS SYSAP
6.2.17.4 Get an entry off the event queue (.SSEVT)
Get an entry off the event queue (.SSEVT)
This function code retrieves the first entry off the event queue.
This queue is a record of events that the JSYS user is to be notified
about. The user receives an interrupt on the first event. After this
events will be added to the end of the queue with no further interrupts
generated. It is the responsibility of the user to empty this queue upon
receiving an event interrupt.
If a connect ID is specified, then the next event for that
connection will be returned. If however the connect ID field is minus
one, then the next event for the fork is returned.
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------! -----------
.SQCID ! Connect ID or -1 ! ^
!-------------------------------------------------------! !
.SQESB ! Reserved ! Node # of remote ! !
!-------------------------------------------------------! Returned
.SQEVT ! Returned event code ! data
!-------------------------------------------------------! !
.SQDTA \ \ !
\ Returned event data \ !
\ \ v
!=======================================================! -----------
The event code describes what event has occured. It is a small
integer ranging from zero to a maximum value. Hence it can easily be
used as an index into an event dispatch table. The connect ID tells you
what connection this event is relevant to. The event data is a block of
data returned for each event type.
The general format of the event code descriptions is as follows:
.SExxx -- Text
The .SExxx is the event code and text desribes the code
.SQDTA -- Text
This second line describes the format of the data provided for this event
code, starting at word .SQDTA of the argument block.
.SEVCC -- Virtual circuit closure
.SQDTA -- Contains the pertinant node number
.SECTL -- Connect to listen
.SQDTA -- Four words of initial connection data from the remote.
.SECRA -- Connection was accepted
SCA Functional specification Page 97
Writing a JSYS SYSAP
.SQDTA -- Four words of initial connection data from the remote.
.SECRR -- Connection was rejected
.SQDTA -- The reason code
.SEMSC -- Message/datagram send complete
.SQDTA -- address of sent buffer
.SELCL -- Little credit left
.SQDTA -- number of credits required to get you back over threshold
.SENWO -- Node went offline
.SQDTA -- Node number of system which went offline
.SENCO -- Node came online
.SQDTA -- Node number of system which came online
.SEOSD -- OK to send data
.SQDTA -- not used here
.SERID -- Remote initiated disconnect
.SQDTA -- not used here
.SEPBC -- Port broke connection
.SQDTA -- not used here
.SECIA -- Credit is available
.SQDTA -- unsed here
.SEMAX is defined to be equal to the largest event code possible.
- Error codes -
SCSNEP,SCSIID,SCSBTS,SCSIAB
SCA Functional specification Page 98
Writing a JSYS SYSAP
6.2.18 Named buffer overview
Named buffer overview
To send data to a remote system, the SYSAP must first declare memory
to be part of a buffer. A buffer is made of segments. Each segment is a
contiguous set of 36 bit words that DO NOT CROSS A PAGE BOUNDARY and are
not more than one page long. Once the buffer has been established, the
SYSAP must give the remote system the buffer name obtained. N.B. SCA
does not give the remote the buffer name, it is the responsibility of the
SYSAP to transmit this information.
SCA Functional specification Page 99
Writing a JSYS SYSAP
6.2.19 Map a buffer (.SSMAP)
Map a buffer (.SSMAP)
This function code associates a portion of memory with an SCA buffer
name to be used in named buffer transfers. This function takes the
following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQXFL ! Flags !
!-------------------------------------------------------!
.SQBNA ! Returned buffer name ! (Returned)
!-------------------------------------------------------!
/ /
/ Buffer length and address pairs /
/ /
!=======================================================!
The current set of flags are as follows:
1. SQ%DMD -- Named buffer mode. This two bit field indicates the
desired setting of the mode bits for the buffer. The following
settings are defined:
SQ%DIC -- Industry compatable mode
SQ%DCD -- Core dump
SQ%DHD -- High density
Any other value is illegal.
Buffer length and address pairs have the following format:
!=======================================================!
.SQBLN ! Length of memory block !
!-------------------------------------------------------!
.SQBAD ! Address of memory for data transfer !
!=======================================================!
The length word in this block has one of two possible values based
on the setting of the mode bits. If the buffer mode is core dump or
industry compatable the length is in 8 bit bytes. If the mode is high
density, the length is in 36 bit words.
The address for data transfer is the address where you expect data
from a data transfer to be placed by the CI port microcode.
The buffer name is the descriptor by which all other references to
this memory is made.
SCA Functional specification Page 100
Writing a JSYS SYSAP
*** Restrictions ***
1. No buffer segment may cross a page boundary. Hence the longest
possible buffer segment is one page.
- Error codes -
SCSNEP,SCSBTS,SCSNBA,SCSIAB
SCA Functional specification Page 101
Writing a JSYS SYSAP
6.2.20 Unmap a buffer (.SSUMP)
Unmap a buffer (.SSUMP)
This function will remove from the monitor data base (unmap) a
memory block assigned for named buffer transfers. It requires these
arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQNAM ! Buffer name !
!=======================================================!
- Error codes -
SCSNEP,SCSBTS
SCA Functional specification Page 102
Writing a JSYS SYSAP
6.2.21 Send data (.SSSND)
Send data (.SSSND)
This function transfers data to a remote host. It is the
responsibility of a higher level protocol to arrange the setup of buffer
names. The call requires the following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID for which transfer is to be done !
!-------------------------------------------------------!
.SQSNM ! Buffer name of send buffer !
!-------------------------------------------------------!
.SQRNM ! Buffer name of receive buffer !
!-------------------------------------------------------!
.SQOFS ! Xmit offset ! Receive offset !
!=======================================================!
- Error codes -
SCSNEP,SCSBTS,SCSIID
SCA Functional specification Page 103
Writing a JSYS SYSAP
6.2.22 Request data (.SSREQ)
Request data (.SSREQ)
This function tells SCA and the port to get data for the given
buffer name. The following arguments are required:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID for which transfer is to be done !
!-------------------------------------------------------!
.SQSNM ! Buffer name of send buffer !
!-------------------------------------------------------!
.SQRNM ! Buffer name of receive buffer !
!-------------------------------------------------------!
.SQOFS ! Xmit offset ! Receive offset !
!=======================================================!
The "xmit offset" is the number of bytes/words the sending port
should skip before sending data. This count is in bytes for industry
compatable/core dump mode sends and words for high density sends
The "receive offset" is the number of bytes/words that the receiver
should skip before writing data from the wire. The count is in bytes for
industry comapatable/core dump and words for high density mode.
- Error codes -
SCSNEP,SCSIID,SCSBTS
SCA Functional specification Page 104
Writing a JSYS SYSAP
6.2.23 Maintainance data send (.SSMDS)
Maintainance data read (.SSMDS)
This function requests a maintainance data send. It works much the
way named buffer transfers do in that the .SSMAP call must be done first
to set up a buffer. The buffer name returned by .SSMAP is used in this
call. Note that the remote must provide the buffer name it has allocated
for sending the data as well.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQMSS ! Buffer name of send buffer !
!-------------------------------------------------------!
.SQMSR ! Buffer name of receive buffer !
!-------------------------------------------------------!
.SQMOF ! Xmit offset ! Receive offset !
!-------------------------------------------------------!
.SQMDT ! Unused ! Target node number !
!=======================================================!
The xmit offset and receive offset are identical to those used for
named buffer transfers.
SCA Functional specification Page 105
Writing a JSYS SYSAP
6.2.24 Maintainace data read (.SSMDR)
Maintainance data read (.SSMDR)
This function requests a maintainance data read. It works much the
way named buffer transfers do in that the .SSMAP call must be done first
to set up a buffer. The buffer name returned by .SSMAP is used in this
call. Note that the remote must provide the buffer name it has allocated
for sending the data as well.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQMSS ! Buffer name of send buffer !
!-------------------------------------------------------!
.SQMSR ! Buffer name of receive buffer !
!-------------------------------------------------------!
.SQMOF ! Xmit offset ! Receive offset !
!-------------------------------------------------------!
.SQMDT ! Unused ! Target node number !
!=======================================================!
The xmit offset and receive offset are identical to those used for
named buffer transfers.
SCA Functional specification Page 106
Writing a JSYS SYSAP
| 6.2.25 Start a remote system (.SSSRS)
|
| Start a remote system (.SSSRS)
|
|
|
| This function will start a remote node. A start address may be
| specified or the default can be used.
|
| !=======================================================!
| .SQLEN ! Words processed ! Length of block !
| !-------------------------------------------------------!
| .SQSTN ! Node number of target node !
| !-------------------------------------------------------!
| .SQSFL ! Flags !
| !-------------------------------------------------------!
| .SQAST ! Address for starting remote system !
| !=======================================================!
|
| The currently defined flags are:
|
| 1. SQ%DSA -- Use the default start address. If this bit is lit, the
| default address is used to start the target node. If the bit is off,
| the the address specified in word .SQAST of the argument block.
|
SCA Functional specification Page 107
Writing a JSYS SYSAP
| 6.2.26 Reset a remote system (.SSRRS)
|
| Reset a remote system (.SSRRS)
|
|
|
| This function resets a remote node.
| !=======================================================!
| .SQLEN ! Words processed ! Length of block !
| !-------------------------------------------------------!
| .SQNTN ! Node number of target node !
| !-------------------------------------------------------!
| .SQRFL ! Flags !
| !=======================================================!
|
| The currently defined flags are:
| SQ%FRB -- Force reset. If this bit is not set, the reset is only
| done if the local host was the last host to send a reset to the
| target node. If the bit is on, the reset is done no matter who last
| reset the target node.
|
SCA Functional specification Page 108
Writing a JSYS SYSAP
6.2.27 Set port counters (.SSSPC)
Set port counters (.SSSPC)
This function sets the port's performance counters. The following
arguments are required:
| !=======================================================!
| .SQLEN ! Number of words processed ! Length of block !
| !-------------------------------------------------------!
| .SQNOD ! Node number !
| !-------------------------------------------------------!
| .SQPCW ! Port counter control word !
| !-------------------------------------------------------!
| .SQCPC ! Number of times the counters have been set/cleared ! (Returned)
| !=======================================================!
|
| Node number: Node number or 377 for all nodes
|
| Port counter control word, bits as follows:
|
| B0 If on, count ACKs received on Path A.
| B1 If on, clear the counter.
| B2 If on, count NAKs received on Path A.
| B3 If on, clear the counter.
| B4 If on, count NO_RSPs received on Path A.
| B5 If on, clear the counter.
| B6 If on, count ACKs received on Path B.
| B7 If on, clear the counter.
| B8 If on, count NAKs received on Path B.
| B9 If on, clear the counter.
| B10 If on, count NO_RSPs received on Path B.
| B11 If on, clear the counter.
| B12 The count of discarded datagrams because
| of no DGFree Queue entries.
| B13 If on, clear the counter.
| B14 Count the packets transmitted to the
| designated port.
| B15 If on, clear the counter.
| B16 Count the packets received from the
| designated port.
| B17 If on, clear the counter.
|
| The count of times the counters have been set/cleared reflects the
| number of SCS% JSYS that have been done to set/clear the port counters,
| not including the current one. I.E. the call just executed is not
| included in the returned count.
SCA Functional specification Page 109
Writing a JSYS SYSAP
| 6.2.28 Read port counters (.SSRPC)
|
| Read port counter (.SSRPC)
|
|
|
| This function reads the maintenance counters out of the port
| hardware. The following argument block is used:
|
|
| !=======================================================!
| .SQLEN ! Processed words ! Length of block !
| !-------------------------------------------------------! -----------
| .SQMCV ! Microcode version ! ^
| !-------------------------------------------------------! !
| .SQPAA ! Path A ACK count ! !
| !-------------------------------------------------------! !
| .SQPAN ! Path A NAK count ! !
| !-------------------------------------------------------! !
| .SQPAR ! Path A no response count ! !
| !-------------------------------------------------------! !
| .SQPBA ! Path B ACK count ! !
| !-------------------------------------------------------! Returned
| .SQPBN ! Path B NAK count ! data
| !-------------------------------------------------------! !
| .SQPBR ! Path B no response count ! !
| !-------------------------------------------------------! !
| .SQNDD ! Number of dropped datagrams ! !
| !-------------------------------------------------------! !
| .SQNPT ! Number of packets transmitted ! !
| !-------------------------------------------------------! !
| .SQNPR ! Number of packets received ! !
| !-------------------------------------------------------! !
| .SQPOR ! Designated port ! !
| !-------------------------------------------------------! !
| .SQNCC ! Number of times counters have been set/cleared ! v
| !=======================================================! -----------
Only the function code is passed to the monitor. The rest of this
block is information returned by the monitor.
- Error codes -
SCSNEP,SCSBTS,SCSNBA
SCA Functional specification Page 110
Writing a JSYS SYSAP
6.2.29 Add interrupt channels (.SSAIC)
Add interrupt channels (.SSAIC)
All notifications from SCA happen on five PSI channels. These
channels are set for: datagram available, message available, named
buffer transfer complete, events, and configuration change. The events
are detailed in the section on the .SSEVT funtion code. The only
function performed by the .SSAIC code, is to inform SCA of which channels
you wish to use for the variuos interrupts. It does not activate any of
the channels, enable the PSI system, or set LEVTAB and CHNTAB for you.
The argument block used to associate events with PSI channels has
this format:
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
\ \
\ Up to four channel descriptor words \
\ \
!=======================================================!
Where channel descriptor words have the following format:
!=======================================================!
! Interrupt type code ! Channel for this code !
!=======================================================!
The interrupt type code is a small integer that indicates an event type.
The channel number field allows you to enable and disable interrupts for
the given event type. If the channel number is -1 then interrupts are
disabled. If it is an integer between zero and thirty five, then that
channel will interrupt on the given event type. The next box is an
example of what the maximum size block would look like.
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
! .SIDGA ! Channel number !
!-------------------------------------------------------!
! .SIMSA ! Channel number !
!-------------------------------------------------------!
! .SIDMA ! -1 !
!-------------------------------------------------------!
! .SIPAN ! Channel number !
!-------------------------------------------------------!
! .SICFG ! Channel number !
!=======================================================!
In this example interrupts for message available, datagram available, and
all other events are being enabled. Interrupts on DMA transfer complete
are being disabled. Note that only the first word of this block need
SCA Functional specification Page 111
Writing a JSYS SYSAP
appear in this position. The channel descriptor words may appear in any
order. There must be at least one but not more than four descriptor
words in a block.
To set up the PSI system for use with SCA, the following JSYS's must be
done:
1. SIR%/XSIR%
2. AIC%
3. EIR%
4. SCS% with the .SSAIC function code
- Error codes -
SCSBTS,SCSNEP,SCSNSP
Design specification for the
Systems Communications Architecture
21-Sep-83
SCA Design specification Page 1
Introduction
1.0 Introduction
1.1 Scope
This document is intended as a guide to SCAMPI and SCSJSY, the TOPS-20
implementation of the Systems Communications Architecture protocol. Any
non-obvious code or algorithm used in either the monitor SYSAP support code
or JSYS support code is described here. It is a non-goal to describe each
routine in detail. The intent is to provide a map of major highways, not a
street map.
The document is broken into two parts, one for SCAMPI and one for
SCSJSY. Each could easily be a stand alone document but are included
together here for consistency with other SCA documents and convenience.
1.2 Related documents
The reader should at least be familiar with the following documents before
proceeding with this specification. The corporate SCA spec is particularly
important as all terminology used in this document follows standards set in
the corporate spec.
1. SCA Functional Specification, 19-September-83 (CDunn)
2. Systems Communications Architecture, 20-July-82 (Strecker)
3. LCG CI Port Architecture Specification, 11-July-83 (Dossa/Keenan)
4. TOPS-20 Coding Standard, 23-Mar-83 (Murphy)
SCA Design specification Page 2
SCAMPI (Monitor SYSAP support)
2.0 SCAMPI (Monitor SYSAP support)
2.1 Major data structures
2.1.1 System block
The system block is the set of per system data for each remote known
to the monitor. The set of system blocks for the local host can be
accessed through the system block list (SBLIST). This is the sparse list
of all system block addresses. Each entry is accessed by indexing into the
list by node number. This will yield the address of the system block for
that node number. In addition to SBLIST each system block has a forward
link to the next block.
There is a special index into SBLIST. When -1 is given as a node
number on a listen call, the SYSAP is indicating that any remote node is
acceptable. Hence -1 is only meaningful when doing a listen call.
System block data includes the work queue, the connect block queue,
and the work queue for this remote. The system block is mainly maintained
by the port driver but there are cells maintained by SCA. These cells are
described in [1].
2.1.2 Connect Block
The connect block is the per connection database and is entirely
maintained by SCA. All connect blocks are linked onto two doubly linked
queues. One of these lists is the set of connections for a particular
system block. The other list is the set of connections owned by a
particular fork. This list and its uses are described in the second half
of this document in the section on SCSJSY. Further description of the
cells in this block may be found in [1].
2.1.3 Remote system work queue
These queues (one per known remote) are used for the stacking of SCA
overhead messages to remotes. Since the protocol allows only one
outstanding overhead message at any time for each remote, the overhead
messages which SCA desires to send while there is one already outstanding
are placed on this queue. When the response to the outstanding message
comes in, the next message on this queue is sent. Note that the head and
tail pointers for these queues are stored in the system block for each
node.
2.2 Overview
SCAMPI can be broken down into a number of major areas, routines that
process requests from SYSAPs, interrupt handlers, periodic function
handlers, buffer management routines, and general support routines.
SCA Design specification Page 3
SCAMPI (Monitor SYSAP support)
2.2.1 SYSAP request handlers
The request handlers are the most simple and straight forward part of
SCAMPI. These routines are most easily understood by reading the code,
rather than a verbal description here. There are however some rules which
are followed in this set of routines.
The more important rule is that interrupt level may come along and
change connection data out from under the nose of a request handler. Hence
an interlock scheme must be arranged for places that cannot tolerate such a
change. For all data except the connect state, the CION/CIOFF macros may
be used to interlock connection data for periods of a few instructions.
Since the connection state needs to be interlocked for very long periods
(perhaps up to a millisecond) another interlock scheme is used. The
SCON/SCOFF macros are used to interlock the connect state. These macros
call the routines SC.SOF and SC.SON in SCAMPI which will do nesting and
interlock checking much like that done by CION/CIOFF. See the sections on
SC.SON and SC.SOF for more details on these routines.
There is one other interlock scheme used for single instructions that
wish to increment fields in the connect block. In particular when SCA
wishes to update the credit fields in the connect block, an ADDM AC,CBLOC
is done where AC contains the number of additional credits (or negative for
returning credit) and CBLOC is the address of the full word credit field in
the connect block. Since we can be guaranteed that the instruction will
complete once started we can be sure that the instruction need not be
interlocked with CION/CIOFF.
The second rule is that the SYSAP is trustworthy. Hence minimal
checks are done for SYSAP argument validity. Only data items over which
the SYSAP has no direct access (E.G. connection state) are checked.
2.2.2 Interrupt handlers
There are a number of entry points in SCA for the port driver to call
at interrupt level. Each of these entry points makes a few assumptions
about what has happened and what it can do.
A common assumption made by all interrupt handling routines is that
they may change certain data items in the connect block. In particular the
the receive credit level may be changed at interrupt level. The connection
state on the other hand is a special case. The problem is that we may very
well be interrupting a piece of code that checked the state of the
connection, saw that it was open, and is about to send messages or
datagrams based on this check. The connection must not be closed until
after this packet send is complete. Hence there is an interlock mechanism
for the connection state. The SCOFF/SCON macros turn off/on the ability to
change the connect state. When the SCON is done by the sensitive routine,
a support routine is called to check a connection specific queue for change
of state request blocks. A part of this block is the address of a chain of
packets that needs to be sent along with the change of state.
A specific case is the sending of a disconnect request. When a remote
sends the local host a disconnect request, the interrupt handler for this
message type checks the interlock for the connect block state. If it is
unlocked it proceeds to send the rest of the handshake. If it is locked
however, it puts an entry onto the connection's block state queue along
SCA Design specification Page 4
SCAMPI (Monitor SYSAP support)
with the address of the chain of messages to send, (in this case the
disconnect response followed by the disconnect request) and returns. When
the routine which locked the connection state releases the lock, the queue
is checked for change of state entries. From the remotes point of view, an
application packet will be received for a connection which has sent the
first part of the disconnect handshake. Hence it must drop this packet
without closing the VC.
2.2.2.1 SC.ONL
At this entry point SCA assumes that a new VC has just been
established. It may be a reopening of an old VC or the first circuit to a
new node. In either case we have the node number of the system newly
arrived and we may go ahead and perform SYSAP notifications. These
notifications are different from all others in that it happens on a per
SYSAP basis rather than a per connection basis. There was no reason to
notify the same SYSAPs once for each connection it owns about a new node.
Hence the SYSAP notifies SCA of an address to call when this event occurs.
Typically this address is the same address given for all other
notifications, but that is a decision for the SYSAP designer. Each SYSAP
notified requires the event code for new circuit and the node number of the
newly aquired node.
2.2.2.2 SC.ERR
This is the entry point for circuit closure. If a circuit is closed
for any reason, SCA expects the port driver to call this entry point. This
includes the case of SCA requesting a circuit closure. It should be noted
here that SCA must request the opening of a circuit after it has been
closed. This is accomplished through the use of the SCOFF/SCON macros.
Upon receiving notification of circuit closure, SCA must close all open
connections on that circuit. It cannot change the state of a connection
which has the connect state interlocked however. A circuit wide count of
interlocked circuit states is maintained. When a SCON macro is performed,
the count has reached zero and the flag for "VC requires open call" is set
in the system block, then we may call the port driver to open the circuit
again. While SCA is here, we must notify all SYSAPs that the circuit has
gone away. This implies that the SYSAP must be able to deal with a circuit
going away during an SCA call.
2.2.2.3 SC.OFL
This entry point is identical to SC.ERR except the code used on SYSAP
notification is for node offline rather than circuit closed on error.
SCA Design specification Page 5
SCAMPI (Monitor SYSAP support)
2.2.2.4 SC.DMA
This entry point is called when a named buffer transfer has completed.
All that needs to be done here is notify the connection that requested the
transfer.
2.2.2.5 SC.INT
This is the major interrupt level entry point for SCA. It is from
this point that SCA handles all incoming application and SCA packets. A
dispatch to the correct routine is done based on the SCA message type.
Other than the general interrupt level cautions outlined above, nothing
very special is done here.
SCA Design specification Page 6
SCAMPI (Monitor SYSAP support)
2.3 Periodic function handlers
Within SCA there are a few functions that are handled on a per time
basis. At present these functions are idle chatter, the management of
buffer allocation levels, and the deletion of connection data. All SCA
time driven activity happens during the one hundred millisecond clock cycle
of the scheduler. Hence there is a clock counter and instruction to
execute in STG for the SCA clock. The instruction is a PUSHJ into SC.CLK.
This routine then does simple checks to see if it is time for any SCA
events to happen, and dispatches to the correct handling routines when the
events are due.
2.3.1 Idle chatter
Idle chatter is defined as the polling of remote nodes with
connections open to them. This is done since most port hardware
implementations can answer a request ID without software intervention.
Hence the port driver poller will not declare a node offline until it stops
answering request IDs on both paths. Since the port can stay up for
extremely long periods afer the software has crashed, detection of remote
software failure could potentially take a very long time. Hence SCA will
send a credit request for zero credit to any remote which has a connection
open to it. These credit requests are only sent if the node has not sent
us a packet for over five seconds. If a credit request is sent, the
response turn around is timed. If the response arrives within five
seconds, the node is online and SCA does nothing except turn off the timed
message flag in the system block. If the response has not arrived after
five seconds, the node is declared down and circuit closure is requested.
2.3.2 Buffer allocation level management
Buffer levels are handled with a twofold process. First, a threshold
level is maintained, below which SYSAPs may request buffers without
waiting. If a SYSAP directly calls a buffer allocation routine
(SC.ABF/SC.ALD) with a request for more than what is on hand, the failure
return is taken and no further action is taken by SCA. In general it is
assumed that for cases other than connection startup and packet reception
buffers SYSAPs will only make small buffer requests (between 1 and 3
buffers). These requests will generally present no problem, as the
threshold level should be well above this.
Second, if a connect request, listen request, accept request, or
receive buffer request is made with a large numbers of buffers specified,
SCA will try to fill the request immediately. If this request would put us
under threshold, then the request is defered until job 0 can allocate the
buffers. All of this is transparent to the SYSAP however. The returned
information (if any) is the same whether the buffers were available or not.
If the buffers were not available, then whatever the SYSAP requested will
take longer to finish. Since no SYSAP should time these requests, this
does not present a problem.
Internally, SCA notices that the request for buffers will put us under
SCA Design specification Page 7
SCAMPI (Monitor SYSAP support)
threshold and hence this request must be defered. Hence the connect
request message is placed on a queue, hung off the system block. Note that
at this point the connect request has been completely assembled and is
ready for transmission. In addition to the normal connect request data, a
short block of data used for creating the required buffers has been
appended to the connect request. After the entry has been made to the
queue, job zero is poked to run and check for this type of request. Once
job zero has created the required buffers, it will either call SC.SCA to
send a request, or will simply return the buffer to the SCA free pool if
this is a buffer queue request.
The following is the format of the data block used to describe the
allocation of additional buffers:
!=======================================================!
\ \
\ Space for largest SCA overhead message \
\ \
!-------------------------------------------------------!
.BZNUM ! # of message buffers ! # of datagram buffers !
!=======================================================!
.BZNUM
This word defines the number of buffers to be allocated.
Note that if there are message buffers being created, the message
being sent here is a credit request. Hence the count of message buffers
plus the current pending receive credit must be placed in the credit field
of the packet. If there are datagram buffers being added here then the
count of datagram buffers in the connect block must be updated to include
these new buffers.
2.3.3 Connection data deletion (SC.RAP)
This periodic function is responsible for the return of resources
associated with aborted or disconnected connections. Once the abort bit
has been set by some other part of SCA, the next pass of this function will
light the reap bit. On the following cycle, SC.RAP will check the count of
packets outstanding on the KLIPA command queue and delete the connect block
if the count is zero. It should be noted that this count of packets on the
queue only accounts for packets that the software gets back. I.E. only
those packets which do not end up on a free queue are counted. Packets
which end up on a free queue are not seen by the software after the send
has completed and hence cannot be counted. There is a substantial delay
however (minimum of 15 seconds) between the abort of the connection and the
deletion of the data. This should allow enough time for those packets not
counted to make it off the KLIPA command queue.
SCA Design specification Page 8
SCAMPI (Monitor SYSAP support)
2.4 Buffer management routines
These routines handle the allocation and return of SCA free pool
buffers. The SCA free pool is a singly linked list of the buffers
available. There are two such pools, one for datagrams and one for
messages. The return of buffers to these pools is a simple operation where
the buffer is placed at the end of the list and the buffer pool count
incremented as necessary. The allocation of these buffer is a bit more
complex however.
When SCA is called upon to allocate a number of buffers (N) from one
of the free pools, there are a number of checks that need to be done.
First, if there are not enough buffers to fill the request (as determined
from the buffer count) the request is rejected outright. If there are
enough buffers but the number of buffers remaining in the pool is less than
a threshold value, then the request is granted and flags are lit for job 0
to add more buffers to the free pool. The number of buffers added is based
on the number of nodes seen the in network plus a few additional buffers.
If during the process of allocating the buffers, it is determined that the
buffer count is wrong and there are in fact not enough buffers to fill the
request, the partial allocation is returned to the free pool and the
request is rejected. After this process the free pool count is correct
since the allocation kept track of how many buffers were in the partial
allocation.
2.5 General support routines
These routine perform the common functions required to support SCA.
In general these are very simple routines that need no explanation. Only
those which make assumptions that are not obvious, or those that use
non-obvious algorithms shall be called out.
2.5.1 Connection data deletion
When an open connection has been disconnected or any connection has
been aborted, the database for that connect must be deleted. This is done
by a number of routines whos' function may not be completely obvious. In
general the idea is to wait for all outbound traffic to complete before
deleting connection data. This can be done since the handling of inbound
packets is identical whether the data is around or not. Outgoing traffic
is easily handled since there is a count of outstanding messages on the
port queues in the connect block. When this count goes to zero all
outgoing traffic has completed. We are guaranteed that there will be no
further traffic since SCA will not try to send packets on a connection in
any state but open. Once this count has gone to zero, the data may be
deleted.
To insure that the KLIPA has had time to complete transmission of any
packets outstanding for this connect, SCA waits a while before checking the
counts. The periodic function to check reap and abort bits will then clean
up the connect data and all resources associated with the connect. For
more detail on this process, see the section on periodic functions.
SCA Design specification Page 9
SCAMPI (Monitor SYSAP support)
2.5.2 SC.SON/SC.SOF
These routines interlock the connect state of each connection. There
is an interlock word in the connection block that when positive is an
indication that the lock is locked and someone wishes to lock it. When
zero the lock is locked but there are no other requests to lock it. When
-1 the lock is available. When interrupt level discovers that it would
like to change the state of the connection but the lock is not available,
an entry is made to a system wide queue, indicating the new state and a
chain of packets that need to be sent as a result of this new state. When
the unlock is done this queue is checked for entries for this connection.
If entries are found they are processed immediately.
2.5.3 SC.PON/SC.POF
These two routines are responsible for the turning off and on of CI
interrupts. This is accomplished through the turning off/on of the PI
channel for the KLIPA. The following algorithm is used to determine
whether the channel state should be changed.
SCA Design specification Page 10
SCAMPI (Monitor SYSAP support)
- SC.POF -
Fig. 1
SCA Design specification Page 11
SCAMPI (Monitor SYSAP support)
- SC.PON -
Fig. 2
SCA Design specification Page 12
SCSJSY (User mode SYSAP support)
3.0 SCSJSY (User mode SYSAP support)
3.1 Overview
SCSJSY provides a user interface to the CI through SCA. To do this it
does nothing more than translate user requests into SCA SYSAP request
handler calls and turns SCA callbacks into a PSI for a fork. A major part
of this job is the careful checking of user arguments. Since SCA assumes
that SYSAPs are trustworthy, a bad argument to an SCA call can cause a
system crash or CI failure fatal to a circuit. Hence SCSJSY must take care
to insure the integrity of user arguments.
In general, SCSJSY handles two types of traffic, inbound, and
outbound. Inbound traffic is placed on fork and connection lists and the
owning fork gets a PSI if the list was empty before this packet arrived.
Outbound traffic is placed on KLIPA command queues through the use of SCA
calls and blocks until the confirmation of send complete comes up from SCA.
This blocking is necessitated by the way packet transmission is done.
Details of this process can be found in the section on JSYS level packet
transmission.
The structure of SCSJSY can be broken up into two parts, a part that
handles service requests from the user, and a part to handle user
notification of interrupt events.
3.2 Major data structures
3.2.1 Connect blocks
In addition to the data for monitor SYSAP support, the connect block
contains a number of cells for JSYS SYSAP support. These include user
buffer counts and list head/tail pointers for various per connection lists.
In general these lists are all doublely linked, and each piece of data is
on two of the lists. In particular each piece of data is on a fork list
and on a connection list. This enables JSYS SYSAPs to request data on a
fork wide basis or a per connect basis. This is greatly simplifies
management of multiple connections. It also means that when data items are
added or removed from its lists, they will very likely be pulled from the
front of one list and the middle of the other. All support code must be
prepared to deal with this case.
A side effect of having data available on a fork wide basis is that
the head/tail pointers for the lists appear in the PSB. As a result,
various places in the code will want to modify the PSB of another fork, or
in the case of interrupt level, modify non-resident memory. To solve this
problem a system wide list was created to store data items until process
level could be summoned to modify non-resident memory. The details of this
process can be found in the section on interrupt level processing.
Connect blocks do not present this kind of problem since they are
always resident. They do however appear on a chain of connect blocks
available to the fork. Hence when the first or last connect block on the
list is deleted, the PSB of the owning fork will be modified. Hence this
process also happens in process context. The details of the connection
block deletion process can be found in the section on monitor SYSAP
support.
SCA Design specification Page 13
SCSJSY (User mode SYSAP support)
3.2.2 SCA data section
To ease the allocation of memory, SCA has a virtual section all to
itself. This section has two uses, a place to allocate buffer space, and a
place to map user packets for transmission. Buffer space is allocated
starting at the end of the section and grows down into memory a page at a
time. User packets being made ready for transmission are mapped into the
begining of the section. This scheme allows the section to be used for
both purposes and still have a dense set of pages for each.
3.3 Service request handlers
Unless otherwise noted, service request handlers check arguments,
translate required arguments into format for passing to SCA, call SCA, and
return. If any data needs to be passed back to the user program that is
not returned by the call to SCA, an event is generated and placed on the
fork/connection event queue.
3.3.1 Send a packet (SCSSMG/SCSSDG)
A major consideration in sending packet data was the performance loss
caused by copying data from user space to monitor space. Hence
SCSSMG/SCSSDG maps the packet into the low end of the SCA section. This is
the why the set of restrictions (detailed in [1]) is placed on packet
sends. Since the SCA header must be contiguous with the packet text, there
must be room for the header between the page boundry and the start of the
SYSAP text. This is why the SYSAP specifies the base address of the SCA
header and not the base of the SYSAP text when talking about buffers. It
insures the SYSAP understands that room for the header must be available.
3.3.2 Read port counters
To read the port counters the port driver must place a command on a
KLIPA command queue and notify SCA when the response comes back on the
KLIPA response queue. Hence the SCA call will not return directly with the
requested information. In this case however the JSYS call will block until
the information has been returned. This alleviates the need for yet
another event type, and since this is not really an event but a request for
information, it returns the data immediately just as the other information
calls do. It just has to wait a while to return the information. Care
must be taken however to not be NOINT wile doing this. This will allow the
user to get out of a hung call to SCS%. This implies that the routine
which returns this information must be able to handle the connection going
away when the data actually comes back. It also means no resources can be
owned when the dismiss is done.
SCA Design specification Page 14
SCSJSY (User mode SYSAP support)
3.4 Interrupt event handlers
The operation of the interrupt handlers is actually rather simple.
Each mearly records a small amount of data into a block and places the
block onto a system wide list. It is the handling of this list which is
rather circuitous:
1. Interrupt level places entry on system wide queue and zeros
location SCSTIM. This location is the clock counter for a 100ms
scheduler clock. SCHED will notice that the count is zero and XCT
a CALL SCSCLK on the next 100ms cycle.
2. Upon arrival at SCSCLK the entire system wide list is scanned.
The target fork number is retrieved from each entry and a bit is
lit in FKSTAT for this fork.
3. The main scheduler loop notices that FKPS1 is on in FKSTAT and
will end up at PIRQ. PIRQ checks the SCS% bit in FKSTAT and will
call SCSPSI if the bit is on. Once we arrived at PIRQ we are in
process context for the target fork. Hence we have the PSB we
will modify locked in core.
4. SCSPSI will now scan the system wide queue for entries bound for
the current fork. The entries it finds are placed on the fork and
connection queues of the target fork. If the list in question was
empty before the new entries were added, then a PSI is generated
on the appropriate channel for the target fork.
When a user receives a PSI, SCS% functions to retrieve data are done
to return information about events or to retrieve data from packets
received.
SCA-DESIGN-NOTES.TXT
SCAMPI will be changed to conform to the corporate spec as much as
possible. This includes updating the states and following the model of
the spec for sending SCS control messages. The current spec is version
6, and is available on R60SPC:.
See comments in the edit history of SCAMPI for specifics of edits already
made. See also SCA-TABLES.TXT for the tables that represent the state machine.
No attempt will be made in the near future to update the SCA design spec.
Any necessary changes to the functional spec will be reviewed with sysap
writers. No change will be visible to ordinary users.
The following areas must be investigated before the design can be done:
1. Interlocks
2. Buffer management
3. Disconnection
4. Deletion of connection blocks
5. When can we safely open a v.c.?
6. Inconsistencies in the corporate spec regarding states
SCA Design Notes
Judy Hall
Dave Lomartire
This is a collection of notes about the changes that have been made to
SCAMPI. It is not intended to be a complete description of the changes,
nor is it in any way a tutorial description of the design. But it does
document the reasons behind some decisions, and may provide some insight
into the assumptions implicit in the code.
Interactions in SCAMPI
Judy Hall
6/14/84
1. System block's list of connection blocks (pointed to by .SBFCB)
NOTE: We assume that the c.b. lock has prevented setting the "reap"
bit until no other code wants to use the c.b. The concern here is only
with keeping the list intact.
Adding - SC.LCB -- CIOFF
Removing -- SC.RCB -- CIOFF
Traversing -- SC.RAP knows it's the only deleter, and uses no
protection when traversing
-- SC.SCM knows it's at interrupt level, uses no protection when
traversing
-- SC.IDL goes NOSKED when traversing to prevent SC.RAP from
running
Nothing totally eliminates the queue. It may become empty when the
last entry is removed.
2. Don't-care listeners (pointed to by TOPDC)
Adding -- SC.LCB -- CIOFF
Removing -- SC.RCB -- CIOFF
-- SC.SCM -- interrupt level
Traversing -- SC.RAP uses CIOFF. WHen it finds an entry to be reaped, it
goes CION. When it continues, it returns to the top of
the list.
3. System block's work queue (pointed to by .SBTWQ)
Adding -- SC.AWQ (from SC.SCA, SC.SNM, SC.DEF) -- CIOFF, checks v.c. before
returning entry. If closed, doesn't queue the entry
since SC.ERR has destroyed the queue
Deleting -- SC.RWQ (from SC.SNM, SC.DEF) -- CIOFF
Traversing -- SC.SNM, SC.DEF -- always remove entry while CIOFF, return
it while CIOFF
Destroying queue -- SC.ERR -- CIOFF when resetting the head and tail
At any time, SC.ERR may destroy the list. Others can't traverse it
CION, or add an entry without verifying that node is still online.
4. System block's address of outbound buffer (pointed to by .SBOBB)
Taking the buffer -- SC.SNM -- uses EXCH with zero; if result is non-zero,
owns the buffer
Returning buffer to s.b. -- SC.SNM -- while CIOFF, makes sure v.c. is open.
If open, stores address in s.b.; if closed, returns buffer
to port queue
-- SC.SAR -- knows it's at interrupt level, stores
address in s.b.
Returning buffer to port or SCA --
SC.ERR -- uses EXCH with zero; if result is non-zero, returns
buffer to SCA's pool
-- if zero, gets a buffer from the port's queue.
SC.RIB -- knows that v.c. is already closed,
returns buffer to port
SC.SNM -- if PHYKLP refuses to send, returns buffer to port
At any time, SC.ERR may return the buffer to SCA's pool. All code must
test and zero the address in one operation.
5. Connection block
Connection block lock protects against
A. Reaping
Makes c.b. address invalid
Manages buffers according to counts in c.b.
(Assume reaping can happen as soon as unlock and OKSKED)
B. Protocol violation
Disc_req / application message
Disc_req / disc_req
Disc_req / credit_req
(Even if last is not a violation of protocol, we will have
reaped the block by the time the response arrives. And there
is no reason to change credit if we are disconnecting.)
C. Change in connection state or block state
Protocol is generally synchronous, but
1. SC.DIS at odd times can be interrupted by incoming
protocol message. Both change state.
2. Sysap can do connection management request, interrupt out
of it, and do SC.DIS.
3. Any connection management request can be interrupted by
node offline.
Events that can't tolerate these changes --anything that believes the
c.b.a. is valid, sets the connection state, sets the block state, or sends
a packet, including
Calls from the sysap, including
Connection management requests
Sending messages and datagrams
Queueing or canceling buffers for reception
Sending DMA
Idle chatter
Sending connection management requests
These all lock the connection block lock. In the case of sending a packet,
they unlock it only after the packet has been given to PHYKLP.
It is NOT necessary to leave a c.b. locked while it is waiting to send a
connection management request (that is, the buffer is in use). However,
it must be locked while its request is being sent and its state is being
changed.
Some code needs to honor the lock if it's at interrupt level, and lock the
lock if it's not. So there are three kinds of routines:
A. Lock
If at interrupt level, do nothing
If not, AOS the count.
B. Honor
Called by code that runs only at interrupt level
If lock is unlocked, proceed.
If lock is locked, set a bit to indicate what is deferred,
and don't proceed.
C. Lock and honor
If not at interrupt level, do "lock"
If at interrupt level, do "honor"
When locking, code goes NOSKED. Therefore, there can be only one locker
at a time.
Events that defer:
SC.ERR - node offline
SC.DIS - sysap requests disconnect
SC.DRQ - remote side initiates disconnect
SC.SNM - sending a connection management request
Unlock routine processes according to the bits it finds set.
6. Existence of connection block
Only SC.RAP deletes a connection block. Code that sets the "reap"
bit must lock the connection block, which makes it NOSKED. The reaper
won't run until the block has been unlocked.
7. Virtual circuit's state (indicated by SBVCST)
SC.ERR -- if no c.b. is locked, calls OPENVC
-- if a c.b. is locked, increments s.b.'s count of locked c.b.'s
SC.ULK -- if node offline had been deferred, decrements s.b.'s count
of locked c.b.'s. If result is zero, calls OPENVC
8. Send credit (indicated by .CBSCD)
Single-instruction AOS or SOS avoids races
Decrement and test -- SC.SMG, SC.SND, SC.REQ -- SOS and load AC
Increase -- SC.DMA increases by 1 -- AOS -- interrupt level
-- SC.CRQ and SC.AMG -- ADDM from packet -- interrupt level
Use -- SC.CRQ compares with minimum send credit -- interrupt level
Store initial value -- SC.ORQ and SC.ARQ -- interrupt level
9. Receive credit
CIOFF protects all changes; multiple kinds of credit must be adjusted
without interruption.
Use of return_credit prevents interaction between cancel receive message
and other events. Avoids cases in which the number of buffers queued
differs from receive credit.
Interlock word, .CBPND, prevents conflicts between two contexts that
want to send a credit_request. Prevents an attempt at queueing the c.b.
a second time, and avoids sending a null credit_request. When the
credit_response arrives, we send another credit_request if the need has
arisen since the last one was sent.
SC.CDT (from SC.RMG, SC.CRM, SC.IDL, SC.CRS) -- EXCH of .CBPND with -1.
If result is 0, send credit_request. If not, return.
SC.CRS -- clear .CBPND and call SC.CDT to send again if necessary.
10. Count of buffers queued for receiving datagrams
Decrement -- SC.CRD -- SOSL once per buffer; AOS if negative
Change -- SC.RDG -- ADDM
-- SC.ADG -- SOSGE; AOS and drop datagram if negative
Use -- SC.RCB dequeues based on this value; block isn't being used by then
Why SC.DIS is Special
6/21/84
SC.DIS uses CIOFF to lock out SC.DRQ, SC.ORQ, SC.ARQ, SC.ARS. If these
were allowed to run, they would have to honor the lock. SC.DRQ already does
honor it, but the other three do not.
The alternative to CIOFF is to make each of these honor the lock. The race
arises only when the sysap has done a disconnect at an unusual time, as
follows:
SC.ORQ - sysap disconnects a listener, and connect_request arrives. SC.DIS
sets new state to closed, but SC.ORQ has already set it to connect_received,
and sent a connect_rsp Match. Its deferred code would have to manufacture
a reject_request if the state had changed to closed. Today it sends
connect_rsp NM if the state is closed.
SC.ARQ - sysap disconnects after initiating a connection, and an accept_request
arrives. SC.DIS sets new state to closed, but SC.ARQ has already set it to
open, and sent an accept_response Match. Its deferred code would have to
manufacture a disconnect_request if the state had changed to closed. Today it
sends an accept_response NM if the state is closed.
SC.ARS - sysap disconnects after accepting a connection for a listener, and
an accept_response Match arrives. SC.DIS sets new state to closed, but SC.ARS
has already set it to open. Its deferred code would have to send a
disconnect_req, which it does today if the state is closed.
It seems more practical to let SC.DIS be CIOFF until it is ready to send
a message (if that's necessary), and avoid a lot of special-purpose code.
It already needs to be CIOFF for a large fraction of the execution time
anyway. Also, the speed of disconnect doesn't seem terribly critical to the
overall performance of the system.
Since SC.DIS is CIOFF for this purpose, it need not lock the lock. SC.DRQ
and SC.ERR will be held off by CIOFF, so the lock is unnecessary.
Why Reap in Process Context
Judy Hall
6/14/84
1. Allows the return of buffers that the sysap (CFS) has queued for output.
These will be returned at SC.INT, which assumes that the CID is still valid.
That is the only way to identify the sysap to which the buffer is to be
returned.
2. Code that sets the "reap" bit must still unlock the connection block before
the reaper can run. Locking goes NOSKED, which prevents reaping. If we were to
reap immediately, each pass through unlock would have to check for this case.
3. Reaping isn't very urgent, and shouldn't be done at interrupt level.
Why Stock the Message Free Queue
Judy Hall
6/20/84
1. When a node goes offline, the outgoing connection management buffer may be in
use. If so, we try to get a buffer from the port's queue to give back
to SCAMPI. When PHYKLP queues the buffer to the port, the port will return
it with error. PHYKLP will return the buffer to the free queue. Thus there
is a window where the port will be short one buffer.
2. When a node goes offline, the incoming connection management buffer
may be on the response queue. SCAMPI will try to remove a buffer from the
port's queue at SC.ERR. Eventually the connection management buffer will
be given to SCAMPI, which will return it to the free queue. Meanwhile, there
is a window where the port will be short one buffer.
3. When a node goes offline, a sysap may have queued a buffer to go out,
without asking that the buffer be returned. In this case, the sysap's
receive credit includes this buffer. If the reaper runs before the port sees
the buffer, SC.RCB will try to remove a buffer from the port when it hasn't
been queued there yet. As soon as the port rejects the command, PHYKLP will
give the buffer back to the port.
Incoming Packets on Closed V.C.
Judy Hall
6/22/84
An incoming packet may be on the response queue behind a packet that will
cause the v.c. to be closed. SCAMPI will receive a callback at SC.ERR
for the bad packet, followed by a callback at SC.INT for the good one.
SCAMPI used to process this second packet normally, even though the
v.c. was closed. This led to the following problem:
Suppose the second packet is a connect_request. SCAMPI matched the
request with a waiting listener and set the connection state to "connect
received". However, the attempt at sending a connect_response failed
because the v.c. was closed. The sysap was never notified of the change of
state. It believed it had an outstanding listener.
SCAMPI now checks the state of the v.c. for every incoming packet.
Because connect_request isn't associated with a particular connection,
it's not sufficient to check the connection state. Also, handling of
the buffer is different if we know that SC.ERR has already run.
This could be via a separate dispatch table at SC.INT, indexed by op
code and handling only the case of incoming packet on a closed v.c.
Presently, the check on the v.c. is made after the op code is known.
The buffer is handled as follows:
1. Connection management request
This is the buffer that SCAMPI queued to the port when the node came
online. Normally, the response goes out in this buffer. If the node
is offline, SCAMPI queues the buffer to the port. SC.ERR has already
taken a buffer from the port and returned it to its pool. THus this
buffer belongs to the port.
2. Connection management response
This is the buffer that is queued to the system block for outgoing
requests. When SC.ERR ran, the pointer was 0, and SCAMPI took a buffer
from the port's queue. Thus SCAMPI now returns this buffer to the port.
3. Application message
SCAMPI gives the buffer to the port. It was included in the sysap's
receive credit, so if the reaper has run, it has already removed an
extra buffer from the port's queue.
4. Application datagram
SCAMPI gives the buffer to the port. It was included in the sysap's
count of queued datagram buffers, so if the reaper has run, it has
already removed an extra buffer from the port's queue.
The List of Connection Blocks
Judy Hall
6/20/84
It's not clear that linking the connection blocks to the system block
is essential. The list is useful for idle chatter, for the reaper,
and for finding the connections when a node goes offline.
Presently, a c.b. remains on the list until the reaper deletes it. This
means that searches through the list will stumble over this block. This
is most likely to be visible after a node goes offline. All its connection
blocks are marked to be reaped, and a whole new set of them is created,
but they are behind the obsolete ones.
One possibility seems to be to remove a c.b. from this list at SC.ERR,
or at SC.PTC, which is reached also when a disconnect sequence completes.
These blocks could be on a special "reap" linked list, which the reaper
would search instead of searching the list for each system block. Since
the reaper runs periodically, and typically searches these lists without
accomplishing anything, this would seem to offer a performance gain.
Other possibilities:
Set a bit in CIDTAB to indicate that the connection block needs
reaping, and have the reaper scan CIDTAB.
Set a global flag when the reap bit is set in any c.b., and don't
call the reaper unless this flag is set.
Opening a V.C.
Judy Hall
6/20/84
SC.SNM may try to queue a packet after SC.ERR has run. Between getting the
buffer (.SBOBB) and sending, it doesn't check the v.c. We need to be sure
that 1) PHYKLP won't accept the packet if the v.c. is closed, and 2) the
v.c. doesn't get reopened before we queue the packet.
Sequence in PHYKLP should always be:
1. Mark the state as closed
2. Tell the port to close the v.c.
3. Tell SCAMPI the v.c. is closed
SCAMPI should never allow the v.c. to be opened as long as any connection
block is locked. The locker may try to send a packet (SC.SNM, SC.SMG, etc.),
and we want that to fail.
Closing and Opening V.C.'s (SCAMPI and PHYKLP)
Judy Hall
6/10/84
1. SCA makes the decision to close
SCA calls PHYKLP, which
a. marks the state as "closed"
b. tells the port to close the v.c.
c. calls SC.ERR
2. PHYKLP makes the decision to close
It follows the same sequence as in #1 above.
3. The port informs PHYKLP of an error
PHYKLP either does all of #1 above, or leaves out telling the
port to close the v.c.
If PHYKLP is unable to get a buffer for the SETCKT, it sets a bit in
RIDSTS (or elsewhere) indicating that the v.c. still needs to be closed.
At this point, the system block has the state as closed, and SENDVC is
refusing to queue packets to the node.
The poller checks this bit, and sends the SETCKT whenever it can.
- - - - -
SCA decides it can open a v.c. (PHYKLP never decides that if the v.c. has
ever been open before).
SCA calls PHYKLP, which sends a start unless the "need to close" bit is
still on. In that case, or if no buffer is available, it sets a bit in
RIDSTS called "need to open".
The poller always checks "need to close" before it checks "need to open".
When it wants to open, it sends a start.
- - - - -
Neither routine returns failure. The purpose of SCA's "open" call is to
say "you can open whenever you want to". PHYKLP will notify SCA when the
v.c. has been opened, and SCA is not concerned with the events that prevent
this.
Similarly, when SCA says "close the v.c.", it means "don't queue any more
of my packets". So PHYKLP should mark its data base and act as if the v.c.
is closed, even if it hasn't found a way to tell the port yet.
Multiple attempts at closing, either by SCA or because of the arrival of
bad packets, should be filtered. SCAMPI checks for multiple calls to SC.ERR
for the same system block, but there seems to be no reason to perform
the close function more than once.
- - - - -
When queueing a START for "open v.c.", PHYKLP should use the lowest possible
priority. THus, if any message has been queued to the port, the port will reject
it before sending the START. Otherwise, stale data might go out on the newly-
opened v.c.
Handling of Buffers on Error
Judy Hall
6/17/84
I believe that PHYKLP should return both message buffers and datagram
buffers to the port's queues when these buffers are locally-generated,
the "response" bit is not on, and an error has occurred. Here is my
reasoning:
1. Message buffers
A. Those sent by a sysap.
If the sysap doesn't want the buffer back, SCAMPI increments
its receive credit on the assumption that the buffer will be put on
the free queue when the port has finished with it.
Indeed, if there is no error, the port puts the buffer on the
free queue, where it is available for an incoming message. If there is
an error, the count has still been incremented, so the buffer should
ultimately wind up on the free queue.
If the node goes offline after the sysap has sent a message,
in theory the reaper could run before the port decides to refuse to send
the message. In this case, SCAMPI would remove "n" buffers from the port's
queue, where "n" includes the 1 that was added to it when the message was
sent. The buffer, then, belongs to the port.
B. Those sent by SCAMPI
SCAMPI sends its requests in a buffer that has been allocated
especially for the purpose (one buffer per remote node). It assumes that
the remote system will send a response, for which the port will acquire
a buffer from the free queue. Thus it does not set the "response" bit
when it sends a request.
If the node goes offline, and a request is outstanding, the port
will return the packet with error. Meanwhile, SCAMPI will have been called
at SC.ERR, where it will determine that the buffer is in use, and move
a buffer from the free queue to SCA's pool. When the original buffer is
finally available, it should replenish the free queue.
2. Datagrams
As with messages, the sysap may queue a datagram buffer without asking
for a response. In that case, SCAMPI counts it as being queued to the port
for an incoming datagram. (This accounting is similar to receive credit for
messages, but it is not communicated to the other host.)
If no error occurs, the port returns this datagram buffer to the port's
free queue. Therefore, if there is an error, PHYKLP should return
such a buffer to the port's queue.
SCA Buffer Management
David Lomartire
14-Sep-84
o SC.ALC - Allocate message and datagram buffers for SCA pool
Called by: SC.ALM via job 0 when DDCFSF is non-zero
Calls: SC.CMG to create message buffers
SC.CDG to create datagram buffers
This routine is responsible for keeping the SCA pool of datagrams and
messages up to the minimum thresholds. Whenever a buffer request is made which
causes the buffer count (FQCNT or DFQCNT) to fall below the minimum, DDCFSF is
set. This will make job 0 call SC.ALM which will call SC.ALC.
For messages -
The number of buffers in FQCNT is checked against the minimum
threshold (MINMSG). If it is below, a call to SC.CMG is made to create more
message buffers to bring us up to the minimum threshold. Upon successful return
from SC.CMG, the buffers are linked to BOTFQ, FQCNT is updated, and TOTMGB
(total number of buffers created so far) is updated.
For datagrams -
The number of buffers in DFQCNT is checked against the minimum
threshold (MINDG). If it is below, a call to SC.CDG is made to create more
datagram buffers to bring us up to the minimum threshold. Upon successful
return from SC.CDG, the buffers are linked to BOTDFQ, DFQCNT is updated, and
TOTDGB (total number of buffers created so far) is updated.
o SC.DEF - Handle buffer deferral
Called by: SC.ALM via job 0 when DDCFSF is non-zero
Calls: SC.BF2 to get (and create if necessary) buffers
This routine handles buffer deferral. When a connect block is stuck on
buffers, the bit corresponding to the node number of its system block is set in
SBSTUK and DDCFSF is set. The connect block is queued to the system block work
queue. When job 0 runs, SC.DEF will run and call SC.BF2 in an attempt to get
the buffers it needs to send the connect_request or accept_request.
When run, SC.DEF "scans" SBSTUK to find the first system block with any
connect blocks which are stuck on buffers. The stuck bit for this system block
is cleared in SBSTUK and all the connect blocks which are stuck are processed.
Any connect block that became unstuck are placed on the end of the work queue.
Once all connect blocks are done, a call is made to SC.SNM in an attempt to
send out the queued connection management requests for that system block.
All system blocks which are stuck are processed until SBSTUK is zero
(indicating that there are no longer any stuck connect blocks).
o SC.BUF (SC.BF1 - Allocate buffers from pool; cannot create buffers)
(SC.BF2 - Allocate buffers from pool; can create buffers)
SC.BF1 called: SC.SNM to get initial buffers for c.b.
SC.BF2 called: SC.DEF when processing stuck connect blocks
Calls: SC.ABF to allocate message buffers
SC.ALD to allocate datagram buffers
SC.CMG to create message buffers
SC.CDG to create datagram buffers
LNKMFQ to link message buffers to port
LNKDFQ to link datagram buffers to port
SC.RBF to return extra message buffers from SC.CMG
SC.RLD to return extra datagram buffers from SC.CDG
These routines are called by SC.SNM (SC.BF1) and SC.DEF (SC.BF2) to allocate
buffers for a connect_request or accept_request from the SCA pool.
For messages -
The number of buffers needed in CBIMB is checked to see if any are
required. If so, a call to SC.ABF is made to obtain them.
If this fails, (and if buffers cannot be created) DMRCNT is
incremented to indicate this and a failure return results. If buffers can be
created a call is made to SC.CMG to create the needed buffers. A failure here
results in a failure return from SC.BUF. On success, the total number of
buffers created is added to TOTMGB. A check is made to see if more were created
than were required and, if so, the extras are returned to the SCA pool via
a call to SCM.RM (which calls SC.RBF once for each extra buffer).
Once the buffers have been obtained, a call is made to SCL.MC to
link each message buffer onto the port message free queue (via call to LNKMFQ).
Pending receive credit (.CBPRC) is updated to reflect these buffers. Finally,
the number of buffers to queue (CBIMB) is set to zero.
For datagrams -
The number of buffers needed in CBIDB is checked to see if any are
required. If so, a call to SC.ALD is made to obtain them.
If this fails, (and if buffers cannot be created) DDRCNT is
incremented to indicate this and a failure return results. If buffers can be
created a call is made to SC.CDG to create the needed buffers. A failure here
results in a failure return from SC.BUF. On success, the total number of
buffers created is added to TOTDGB. A check is made to see if more were created
than were required and, if so, the extras are returned to the SCA pool via
a call to SCM.RD (which calls SC.RLD once for each extra buffer).
Once the buffers have been obtained, a call is made to SCL.DC to
link each datagram buffer onto the port datagram free queue (via call to
LNKDFQ). The count of datagram buffers queued (.CBDGR) is changed to reflect
these buffers. Finally, the number of buffers to queue (CBIDB) is set to zero.
o SC.SBT - Set buffer thresholds
Called by: SCA upon initialization to establish starting levels
SC.ONL to update levels when node comes online
SC.ERR to update levels when node goes offline
This routine is used to set the value for the minimum level of message
(MINMSG) and datagram buffers (MINDG) to be maintained by SCA. This count is
based on the number of systems currently online (SBCNT). Whenever a request for
a buffer forces the count of buffers to fall below the minimum, DDCFSF is set
to signal job 0 to run SC.ALC and allocate more buffers for the SCA pool.
MINMSG = (SBCNT*MBPS)+MGTRSH, where MBPS is the number of message buffers to
maintain per online system and MGTRSH is the base value of buffers which must
be available.
MINDG = (SBCNT*DBPS)+DGTRSH, where DBPS is the number of datagram buffers to
maintain per online system and DGTRSH is the base value of buffers which must
be available.
o SC.ABF - Allocate message buffers from SCA pool
Called by: SCA to acquire a buffer for NOTTAB
SC.SMG to give the port a buffer on send failure
SC.RMG to get the number of buffers to queue
SC.ONL to get 2 buffers; 1 for .SBOBB and 1 for port
SC.ACB to get a buffer to use as the connect block
SC.BF2 to get buffers requested upon connect or accept
This routine is used to obtain message buffers from SCA's pool. First, the
number of buffers desired is checked against FQCNT and if greater, the routine
will return an SCSNBA error. Next, the number of buffers left after the request
is satisfied (FQCNT-NUMBUF) is checked to see if it falls below the minimum
threshold (MGTRSH). [MGTRSH is used because it is the constant lower threshold
below which no requests for buffers will be granted unless they are small (less
than LRGREQ). MINMSG is not used because it is a fluctuating value which depends
upon the number of nodes up at the moment.] If there are enough buffers
remaining (or if not and the request is small), the request is honored. If the
request is honored because it is a small request, MBUST is incremented to
record this. To honor the request, the message free queue (top is TOPFQ and
bottom is BOTFQ) is traversed to insure that there actually are the required
number of buffers.
If there is an inconsistency, a SCAMCR BUGCHK will result and FQCNT will be
recalculated by tracing the free queue again. NMBCNT (the number of times we
ran out of message buffers) and RMRCNT (the number of times allocation was
refused) are incremented. DDCFSF is incremented to force SC.ALC to run. Also,
ASRMR is updated to reflect the average size of refused requests. A SCSNBA
error will be returned.
If the scan of the free queue is successful, TOPFQ, BOTFQ, and FQCNT are
updated. If it is found that FQCNT has fallen below MINMSG, DDCFSF is set to
allow SC.ALC to run.
If the request is refused, RMRCNT is incremented and ASRMR is updated to
reflect the average size of refused requests. A SCSNBA error will be returned.
This will occur when there are not enough buffers present to grant the request
or when a large request forces the count below the buffer threshold.
o SC.ALD - Allocate datagram buffers from SCA pool
Called by: SC.SDG to give the port a buffer on send failure
SC.RDG to acquire the buffers to queue
SC.BF2 to get buffers requested upon connect or accept
This routine is used to obtain datagram buffers from SCA's pool. First, the
number of buffers desired is checked against DFQCNT and if greater, the routine
will return an SCSNBA error. Next, the number of buffers left after the request
is satisfied (DFQCNT-NUMBUF) is checked to see if it falls below the minimum
threshold (DGTRSH). [DGTRSH is used because it is the constant lower threshold
below which no requests for buffers will be granted unless they are small (less
than LRGREQ). MINDG is not used because it is a fluctuating value which depends
upon the number of nodes up at the moment.] If there are enough buffers
remaining (or if not and the request is small), the request is honored. If the
request is honored because it is a small request, DBUST is incremented to
record this. To honor the request, the datagram free queue (top is TOPDFQ and
bottom is BOTDFQ) is traversed to insure that there actually are the required
number of buffers.
If there is an inconsistency, DFQCNT will be recalculated by tracing the free
queue again. NDBCNT (the number of times we ran out of datagram buffers) and
RDRCNT (the number of times allocation was refused) are incremented. DDCFSF is
incremented to force SC.ALC to run. Also, ASRDR is updated to reflect the
average size of refused requests. A SCSNBA error will be returned.
If the scan of the free queue is successful, TOPDFQ, BOTDFQ, and DFQCNT are
updated. If it is found that DFQCNT has fallen below MINDG, DDCFSF is set to
allow SC.ALC to run.
If the request is refused, RDRCNT is incremented and ASRDR is updated to
reflect the average size of refused requests. A SCSNBA error will be returned.
This will occur when there are not enough buffers present to grant the request
or when a large request forces the count below the buffer threshold.
o SC.CMG/SC.CDG - Create message/datagram buffers
Called by: SC.ALC to create buffers needed to boost above minimum
SC.BF2 to create buffers needed by connect or accept
Calls: SC.BBF to break memory pages into buffer chain
These routines are used to create message and datagram buffers. It is called
when the SCA buffer pool is exhausted (or below minimum values) and needs to be
restocked. The number of buffers returned is rounded up to fill an integral
number of pages so extra buffers may be provided.
First the number of pages required to fill the buffer request is calculated.
For each page required, EPGMAP is searched to locate an empty page. If no empty
pages are found, the routine returns with a SCSNEB error. The search starts at
offset LSTEPG (which is initialized to 777) and decrements towards the top of
the map. When a free page is found, the next lower offset is placed in LSTEPG
and a call is made to MLKMA to lock down the page. Finally, a call is made to
SC.BBF to break the page into buffers of the appropriate size (C%MGSZ for
messages and C%DGSZ for datagrams).
o SC.BBF - Break memory page into buffers
Called by: SCA to create the initial chain of buffers
SC.CMG to create chain of message buffers
SC.CDG to create chain of datagram buffers
This routine will take a page of memory and break it into a chain of message
or datagram buffers. The page is broken up into buffers of C%BINV+C%MGSZ size
for messages and C%BINV+C%DGSZ for datagrams. C%BINV is the size of the
invisible area which is prepended to the top of each buffer for local use (it
is never sent across the CI). The FLINKs of each buffer point to the next
buffer in the chain.
o SC.RBF - Return a message buffer
Called by: SC.ERR to return the two buffers obtained at SC.ONL
SC.INT to return buffer sent by SCA
SC.RCB to return buffers queued by connection
SC.JSY to return buffers queued by JSYS
SC.GCB to return buffers in RET_CREDIT field (.CBRTC)
SCM.RM to return one of a chain of message buffers
SC.ABF to return extra buffers from SC.CMG
This routine will return message buffers to the SCA message free queue.
First, the entire buffer (C%BINV+C%MGSZ) is zeroed. Then the buffer is linked
to BOTFQ and FQCNT is incremented to reflect the additional buffer. Note that
this routine is passed back to the caller by SC.ABF as the routine to call to
return the buffer.
o SC.RLD - Return a datagram buffer
Called by: SC.CRD to return buffer which was canceled
SC.RCB to return buffers queued by connection
SC.JSY to return buffers queued by JSYS
SCM.RD to return one of a chain of datagram buffers
SC.ALD to return extra buffers from SC.CDG
This routine will return datagram buffers to the SCA datagram free queue.
First, the entire buffer (C%BINV+C%DGSZ) is zeroed. Then the buffer is linked
to BOTDFQ and DFQCNT is incremented to reflect the additional buffer. Note that
this routine is passed back to the caller by SC.ALD as the routine to call to
return the buffer.
The SCS% JSYS
31-Jan-83
SCS% JSYS Page 1
General format of JSYS call
The following is the general format of a call to the SCS% JSYS.
Call
T1/ Function code
T2/ Address of arg block
Return (+1) Always
T1/ Function code
T2/ Address of arg block
An error generates an illegal instruction trap.
General format of the argument block:
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
\ \
\ Function dependent arguments \
\ \
!=======================================================!
Where the "words processed" is the number of words in the argument
block that the monitor actually looked at and used. Hence this field is
returned by the monitor, not supplied by the user. The "length of block"
is the total length of the supplied block including the header word.
Note that this JSYS requires one or any combination of wheel,
maintainance, or network wizard.
SCS% JSYS Page 2
Connect (.SSCON)
Connect (.SSCON)
This function requests a connection with another node on the CI.
The JSYS will return as soon as the connection request has been sent.
You are notified that your connection request was granted or failed via a
PSI interrupt.
The argument block has the following format:
|
| !=======================================================!
| .SQLEN ! Words processed ! Length of block !
| !-------------------------------------------------------!
| .SQSPN ! Byte pointer to source process name !
| !-------------------------------------------------------!
| .SQDPN ! Byte pointer to destination process name !
| !-------------------------------------------------------!
| .SQSYS ! SBI of destination ! 6 bits of connect ID !
| !-------------------------------------------------------!
| .SQCDT ! Pointer to connection data !
| !-------------------------------------------------------!
| .SQAMC ! Address of first buffer on message buffer chain !
| !-------------------------------------------------------!
| .SQADC ! Address of first buffer on datagram buffer chain !
| !-------------------------------------------------------!
| .SQRCI ! Returned connect ID !
| !=======================================================!
|
The byte pointer to the source process name is a byte pointer to the
ASCII string which is the name of your process. Note that this string
must end on a null byte and may be a maximum of 16 bytes long, not
including the null byte.
The byte pointer to destination process name is the byte pointer to the
name of the process you wish to connect to. This name must also end in a
null byte and may be a maximum of 16 bytes, not including the null byte.
The SBI (system block index) is the unique identifier of the system you
wish to connect to.
Note that the specified strings may be any vaild ASCII byte size (I.E.
any byte size equal to or larger than 7 bits). These strings may also be
generic byte pointers (-1,,STRNG). If generic byte pointers are given, 7
bit ASCII terminated by a null byte is assumed.
The 6 bits of connect ID is 6 right justified bits which will be placed
in the most significant bits of the connect ID. These bits are generally
used for connection managment by the user program. If initial data is
not desired then this word is zero.
|
| The pointer to connection data is the address of a block of data SQ%CDT
SCS% JSYS Page 3
Connect (.SSCON)
| words long to be sent as connection data. Note that the monitor will
| copy SQ%CDT words of data from the users address space. Hence a full
| block SQ%CDT words long should be allocated for the data.
SCS% JSYS Page 4
Listen (.SSLIS)
Listen (.SSLIS)
This function listens for a connection. Note that the JSYS does not
block. You will be notified of a connect to your listen via a PSI
interrupt.
There are a number of options that may be used when doing a listen
for a connection. You may listen for a particular process from any
system by making the system block index -1. You may listen for any
process from a particular system by making the byte pointer to the
destination process name -1. If the system block index and the byte
pointer to the destination process name are both -1, then any connect
request that is not for a particular process name will match your listen.
Naturally you may specify both a system block index and a process name
and then only that process from the named system will be allowed to
connect to your listen.
|
|
|
| !=======================================================!
| .SQLEN ! Processed words ! Length of block !
| !-------------------------------------------------------!
| .SQSPN ! Byte pointer to source process name !
| !-------------------------------------------------------!
| .SQDPN ! Byte pointer to destination process name !
| !-------------------------------------------------------!
| .SQSYS ! SBI of destination ! 6 bits of connect ID !
| !-------------------------------------------------------!
| .SQMGA ! Address of first buffer on message buffer chain !
| !-------------------------------------------------------!
| .SQDGA ! Address of first buffer on datagram buffer chain !
| !-------------------------------------------------------!
| .SQLCI ! Returned connect ID !
| !=======================================================!
|
See the description of .SSCON for an explanation of each field in
this block.
SCS% JSYS Page 5
Accept (.SSACC)
Accept a connection (.SSACC)
This function tells a remote node that you are granting his request
for a connection.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQCDA ! Pointer to connection data !
!=======================================================!
The pointer to connection data is the address of the block of
connection data to be sent to the remote system. The monitor will copy
SQ%CDT words of data from the users address space as data. Note that
this data will be sent directly over the CI and hence the low order four
bits are not sent.
SCS% JSYS Page 6
Reject (.SSREJ)
Reject a connection (.SSREJ)
This function code tells a remote node that you are not allowing a
connection to your process.
The argument block for this function has this format:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQREJ ! Rejection reason !
!=======================================================!
The rejection reason is a relativly small integer that indicates to
the remote host why you are not allowing the connection. MONSYM contains
a list of these codes.
SCS% JSYS Page 7
Disconnect (.SSDIS)
Disconnect (.SSDIS)
This function closes a connection. The disconnect function code
requires the following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQDIS ! Disconnect reason !
!=======================================================!
The disconnect reason is a relativly small positive integer that
indicates to the remote system, why you are closing the connection.
MONSYM contains the list of definitions of these codes.
SCS% JSYS Page 8
Send a DG (.SSSDG)
Send a datagram (.SSSDG)
This function code sends a datagram. The following arguments are
required:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQADG ! Address of datagram text !
!-------------------------------------------------------!
.SQDGL ! Length in 8 bit bytes of datagram data !
!-------------------------------------------------------!
.SQFLG ! Flags ! OPS !
!=======================================================!
OPS is an optional path specification. If specified, the OPS
indicates that you wish to send this datagram over a particular hardware
cable (path). A complete description of this field may be found in
MONSYM along with the flag definitions for the rest of the word.
*** Restrictions ***
1. The datagram text may not cross a page boundry.
2. A monitor overhead area of .SQTXT words must appear before the
message text.
3. Swapping of the page will be prevented while it is in the process of
being sent. Hence forcing the page to be swapped before notification
of message send complete will cause the hardware much grief.
4. The datagram text must be packed in left justified, word aligned,
eight bit bytes.
SCS% JSYS Page 9
Queue a DG buffer (.SSQRD)
Queue a buffer for datagram reception (.SSQRD)
This function code queues buffers for datagram reception.
Note that in each buffer the first word is the address of the next
buffer. The last buffer has zero as the address of the next buffer.
This function requires these arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQAFB ! Address of first buffer on buffer chain !
!=======================================================!
*** Restrictions ***
| 1. Datagram buffers must be 152 words in length.
SCS% JSYS Page 10
Send message (.SSSMG)
Send a message (.SSSMG)
This function code sends a message to a remote node.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQAMT ! Address of message text !
!-------------------------------------------------------!
.SQLMT ! Length of message in 8 bit bytes !
!-------------------------------------------------------!
.SQFLG ! Flags ! OPS !
!=======================================================!
OPS is an abbreviation for "optional path spec". If specified, the
OPS indicates that you wish to send this message over a particular
hardware cable (path). There are three possible settings of these bits.
A zero or one indicate the path to use, either zero or one. If all bits
are 1, then the monitor will select the path over which to send the
message. The complete set of flag definitions may be found in MONSYM.
Note that the length of the message is the number of eight bit bytes in
the message.
*** Restrictions ***
1. The message text may not cross a page boundry.
2. A monitor overhead area of .SQTXT words must appear before the
message text.
3. Swapping of the page will be prevented while it is in the process of
being sent. Hence forcing the page to be swapped before notification
of message send complete will cause the hardware much grief.
|
| 4. Message text may not be longer than 38 36 bit words (152 bytes).
SCS% JSYS Page 11
Queue message recieve buffers (.SSQRM)
Queue message receieve buffers (.SSQRM)
| This function code queues buffer to receieve messages. Note that
| the buffer size is fixed at 38, 36 bit words. It requires the following
| arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQAFB ! Address of buffer chain to queue !
!=======================================================!
SCS% JSYS Page 12
Cancel DG receive (.SSCRD)
Cancel datagram receive (.SSCRD)
This function code removes a buffer queued for datagram reception.
The address that you specify must be the address of a buffer that was
previously queued for receiving datagrams (with .SSQRD). If this address
is not found by the monitor when it goes to take the buffer out of its
queue, the JSYS fails with an illegal instruction trap. This function
requires these arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQADB ! Address of buffer to dequeue !
!=======================================================!
SCS% JSYS Page 13
Cancel receieve message (.SSCRM)
Cancel receieve message (.SSCRM)
The function dequeues a buffer that was queued for message
reception. The buffer address that is specified must be of a buffer that
you asked to be queued for message reception (with .SSQRM). If the
monitor does not find the address specified in the argumnet block amongst
the buffers you queued, the JSYS will fail. This function requires the
following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQADB ! Address of buffer to dequeue !
!=======================================================!
SCS% JSYS Page 14
Connect state poll (.SSCSP)
Connect state poll (.SSCSP)
This function returns information about that state of a connection.
The argument block to this function includes space for the returned data.
The argument block for this function looks like this:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------! ------------
.SQCST ! Connection state ! ^
!-------------------------------------------------------! !
.SQDCI ! Destination connect ID ! !
!-------------------------------------------------------! Returned
.SQBDN ! Byte pointer to destination process name ! data
!-------------------------------------------------------! !
.SQSBI ! System block index of destination ! !
!-------------------------------------------------------! !
.SQREA ! Source disconnect reasons ! Dest disconnect reasons ! v
!=======================================================! ------------
Note that the byte pointer to destination process name must be
provided by the caller and may be either a real byte pointer or minus one
in the left half and the base address of the string in the right half.
If the generic byte pointer is used the monitor will write the string as
16 word aligned eight bit bytes, not the usual 7 bit bytes!
SCS% JSYS Page 15
Return configuration data (.SSRCD)
Return configuration data (.SSRCD)
This function returns data about another system. Given the system
block index the monitor will return data about that system. The data is
returned in the block pointed to by T1 which looks like this:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Optional connect ID !
!-------------------------------------------------------!
.SQOSB ! Optional system block index !
!-------------------------------------------------------! -----------
.SQVCS ! Virtual circuit state ! Port number ! ^
!-------------------------------------------------------! !
.SQSAD \ \ !
\ System address (6 8-bit bytes, word aligned) \ !
\ \ !
!-------------------------------------------------------! !
.SQMDD ! Maximum destination datagram size ! !
!-------------------------------------------------------! !
.SQMDM ! Maximum destination message size ! Returned
!-------------------------------------------------------! data
.SQDST ! Destination software type ! !
!-------------------------------------------------------! !
.SQDSV ! Destination software version ! !
!-------------------------------------------------------! !
.SQDSE ! Destination software edit level ! !
!-------------------------------------------------------! !
.SQDHT ! Destination hardware type ! !
!-------------------------------------------------------! !
.SQDHV ! Destination hardware version ! !
!-------------------------------------------------------! !
.SQPCW \ Port characteristics bytes \ !
\ 6, 8 bit bytes, word aligned in leftmost 32 bits \ !
!-------------------------------------------------------! !
.SQLPN ! Local port number ! v
!=======================================================! ------------
The symbols which define the various hardware and software types may
be found in MONSYM.
The connect ID and system block index are optional in that one or
the other must be specified, but not both. If the connect ID field is
non-zero then the SBI field is ignored and the information returned is
for the system implied by the connect ID. If the connect ID field is
zero then the SBI field is used. Note that this allows the use of the
zero'th system block index.
If the local port number is not available, -1 will be returned to
SCS% JSYS Page 16
Return configuration data (.SSRCD)
the user in offset .SQLPN.
SCS% JSYS Page 17
Return status information (.SSSTS)
Return status information (.SSSTS)
This function returns status information about a connection. It is
intended as a fast form of the .SSCSP function code which returns
detailed information about a connection. This function requires the
following arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQCID ! Connect ID !
!-------------------------------------------------------!
.SQFST ! Flags ! Connect state ! -------------
!-------------------------------------------------------! Returned
.SQSBR ! Reserved ! SBI of remote ! data
!=======================================================! -------------
The flags which appear in the flags field are:
1. Message available - There is at least one message avilable for this
connection.
2. Datagram available - There is at least one datagram available for
this connection.
3. DMA transfer complete - At least one DMA transfer has completed since
the last time the SCS% JSYS was performed with this function code.
The bit is cleared in the monitor data base when this function code
is performed.
The complete set of flag symbol definitions may be found in MONSYM. The
connect state is provided such that a reasonable interpretation of the
flags may be made.
SCS% JSYS Page 18
Receive a message (.SSRMG)
Receive a message (.SSRMG)
This function code returns message text for either the calling fork
or the specified connection. If the connect ID field in the argument
block is minus one, then the first message found for the calling fork is
returned. If the connect ID is anything but minus one (-1), the monitor
will use this as a connect ID and return the first message found for that
connection. Note that if there is no message available an illegal
instruction is generated. The following argument block is required for
this function code.
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------! -----------
.SQCID ! Connect ID or -1 ! ^
!-------------------------------------------------------! !
.SQARB ! Address of returned buffer ! !
!-------------------------------------------------------! Returned data
.SQDFL ! Flags ! SBI of remote ! !
!-------------------------------------------------------! !
.SQLRP ! Length of returned packet ! v
!=======================================================! -----------
The address of returned buffer is the address in your working set
that the monitor has placed your data. This address is one of the
addresses previously specifed by a .SSQRM call. If no .SSQRM call was
done, then this function code will fail with an illegal instruction trap.
If the address is not writable you will also get an illegal instruction
trap.
The flags are returned by the monitor and currently only indicate
the data packing mode.
The length of the returned packet is in bytes for an industry
compatible mode message, and words for a high density mode packet.
SCS% JSYS Page 19
Receive a datagram (.SSRDG)
Receive a datagram (.SSRDG)
This function code returns datagram text for either the calling fork or
the specified connection. If the connect ID field in the argument block
is minus one, then the first datagram found for the calling fork is
returned. If the connect ID is anything but minus one (-1), the monitor
will use this as a connect ID and return the first datagram found for
that connection. This is the argument block for this function code:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------! -----------
.SQCID ! Connect ID or -1 ! ^
!-------------------------------------------------------! !
.SQARB ! Address of returned buffer ! !
!-------------------------------------------------------! Returned data
.SQDFL ! Flags ! SBI of remote ! !
!-------------------------------------------------------! !
.SQLRP ! Length of returned packet ! v
!=======================================================! -----------
The address of returned data is one of the addresses provided to the
monitor on a .SSQRD call. If no .SSQRD was done or if the address is not
writable, the JSYS will fail with an illegal instruction trap. Also note
that if there was no datagram available this address is zero.
The flags are returned by the monitor and currently only indicate
the data packing mode.
The length of the returned packet is in words if this is a high
density datagram, and bytes if an industry compatible datagram.
SCS% JSYS Page 20
.SSGDE (Get entry from data queue)
.SSGDE (Get entry from data queue)
This function code returns the first entry from the data request
complete queue. The argument block follows:
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
.SQBID ! Buffer ID whos transfer completed !
!=======================================================!
The buffer ID indicates which DMA transfer has completed.
SCS% JSYS Page 21
.SSEVT (Get an entry off the event queue)
.SSEVT (Get an entry off the event queue)
This function code retrieves the first entry off the event queue.
This queue is a record of events that the JSYS user is to be notified
about. The user receives an interrupt on the first event. After this
events will be added to the end of the queue with no further interrupts
generated. It is the responsibility of the user to empty this queue upon
receiving an event interrupt.
If a connect ID is specified, then the next event for that
connection will be returned. If however the connect ID field is minus
one, then the next event for the fork is returned.
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------! -----------
.SQCID ! Connect ID or -1 ! ^
!-------------------------------------------------------! !
.SQESB ! Reserved ! SBI of remote ! !
!-------------------------------------------------------! Returned
.SQEVT ! Returned event code ! data
!-------------------------------------------------------! !
.SQDTA \ \ !
\ Returned event data \ !
\ \ v
!=======================================================! -----------
The event code describes what event has occured. It is a small
integer ranging from zero to a maximum value. Hence it can easily be
used as an index into an event dispatch table. The connect ID tells you
what connection this event is relevant to. The event data is a block of
data returned for each event type.
SCS% JSYS Page 22
DMA overview
DMA overview
| To send data to a remote system, you must first declare memory in
| your working set to be part of a buffer. A buffer is made of segments.
| Each segment is a contiguous set of 36 bit words that DO NOT CROSS A PAGE
| BOUNDARY and are not more than one page long. Once the buffer has been
| established, you must tell the remote system the name of the buffer that
| you have declared.
SCS% JSYS Page 23
Map a buffer (.SSMAP)
Map a buffer (.SSMAP)
|
|
|
| This function code associates a portion of memory with an SCA buffer
| name to be used in DMA transfers. This function takes the following
| arguments:
|
| !=======================================================!
| .SQLEN ! Processed words ! Length of block !
| !-------------------------------------------------------!
| .SQBNA ! Returned 32 bit buffer name ! (Returned)
| !-------------------------------------------------------!
| / /
| / Buffer length and address pairs /
| / /
| !=======================================================!
|
| Buffer length and address paris have the following format:
|
|
| !=======================================================!
| .SQBLN ! Length in 36 bit words of memory block !
| !-------------------------------------------------------!
| .SQBAD ! Address of memory for DMA transfer !
| !=======================================================!
|
| The address for DMA transfer is the address in your working set
| where you expect data from a DMA transfer to be placed by the CI port
| microcode. All pages in your working set that are contained in this
| request will be locked into resident memory. They will remain this way
| until you unmap the buffer.
|
| The buffer name is the descriptor by which all other references to
| this memory is made.
*** Restrictions ***
1. No buffer segment may cross a page boundary. Hence the longest
possible buffer segment is one page.
Note:
All pages containing a buffer segment will be locked into physical
memory. Unlocking these pages behind SCA's back will cause severe system
problems!!!
SCS% JSYS Page 24
Unmap a buffer (.SSUMP)
Unmap a buffer (.SSUMP)
This function will remove from the monitor data base (unmap) a
memory block assigned for DMA transfers. It requires these arguments:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------!
.SQNAM ! 32 bit buffer name !
!=======================================================!
Upon completion of this call the pages in the memory block are no
longer locked into physical memory.
SCS% JSYS Page 25
Send data (.SSSND)
Send data (.SSSND)
| This function transfers data to a remote host. It is the
| responsibility of a higher level protocol to arrange the setup of buffer
| names. The call requires the following arguments:
|
| !=======================================================!
| .SQLEN ! Processed words ! Length of block !
| !-------------------------------------------------------!
| .SQCID ! Connect ID for which transfer is to be done !
| !-------------------------------------------------------!
| .SQSNM ! 32 bit buffer name of send buffer !
| !-------------------------------------------------------!
| .SQRNM ! 32 bit buffer name of receive buffer !
| !-------------------------------------------------------!
| .SQOFS ! Xmit offset ! Receive offset !
| !=======================================================!
SCS% JSYS Page 26
| Request data (.SSREQ)
| Request data (.SSREQ)
|
|
|
| This function tells SCA and the port to get data for the given
| buffer name. The following arguments are required:
|
| !=======================================================!
| .SQLEN ! Processed words ! Length of block !
| !-------------------------------------------------------!
| .SQCID ! Connect ID for which transfer is to be done !
| !-------------------------------------------------------!
| .SQSNM ! 32 bit buffer name of send buffer !
| !-------------------------------------------------------!
| .SQRNM ! 32 bit buffer name of receive buffer !
| !-------------------------------------------------------!
| .SQOFS ! Xmit offset ! Receive offset !
| !=======================================================!
SCS% JSYS Page 27
Read port counters (.SSRPC)
Read port counter (.SSRPC)
This function reads the maintainance counters out of the port
hardware. The following argument block is used:
!=======================================================!
.SQLEN ! Processed words ! Length of block !
!-------------------------------------------------------! -----------
.SQP0A ! Path zero ACK count ! ^
!-------------------------------------------------------! !
.SQP0N ! Path zero NAK count ! !
!-------------------------------------------------------! !
.SQP0R ! Path zero no response count ! !
!-------------------------------------------------------! !
.SQP1A ! Path one ACK count ! !
!-------------------------------------------------------! Returned
.SQP1N ! Path one NAK count ! data
!-------------------------------------------------------! !
.SQP1R ! Path one no response count ! !
!-------------------------------------------------------! !
.SQNPT ! Number of packets transmitted ! !
!-------------------------------------------------------! !
.SQNPR ! Number of packets received ! !
!-------------------------------------------------------! !
.SQPOR ! Designated port ! v
!=======================================================! -----------
Only the function code is passed to the monitor. The rest of this
block is information returned by the monitor.
SCS% JSYS Page 28
.SSAIC (Add interrupt channels)
.SSAIC (Add interrupt channels)
| All notifications from SCA happen on four PSI channels. These
| channels are: datagram available, message available, DMA transfer
| complete, and all other events. These other events include vitual
| circuit closure, connection managment events, and all port and SCA
| related errors. Interrupts will work just as they do now, add the SCA
| bits to the interrupt mask, add a cooresponding entry to LEVTAB and
| CHNTAB, and an interrupt service routine.
| Note that this call only tells SCA what channels to use when
| interrupts are to be given. It is not a replacement for the AIC JSYS!
| The argument block used to associate events with PSI channels has this
| format:
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
\ \
\ Up to four channel descriptor words \
\ \
!=======================================================!
Where channel desrciptor words have the following format:
!=======================================================!
! Interrupt type code ! Channel for this code !
!=======================================================!
The interrupt type code is a small integer that indicates an event type.
The channel number field allows you to enable and disable interrupts for
the given event type. If the channel number is -1 then interrupts are
disabled. If it is an integer between zero and thirty five, then that
channel will interrupt on the given event type. The next box is an
example of what the maximum size block would look like.
!=======================================================!
.SQLEN ! Words processed ! Length of block !
!-------------------------------------------------------!
! .SIDGA ! Channel number !
!-------------------------------------------------------!
! .SIMSA ! Channel number !
!-------------------------------------------------------!
! .SIDMA ! -1 !
!-------------------------------------------------------!
! .SIPAN ! Channel number !
!=======================================================!
In this example interrupts for message available, datagram available, and
all other events are being enabled. Interrupts on DMA transfer complete
are being disabled. Note that only the first word of this block need
appear in this position. The channel descriptor words may appear in any
order. There must be at least one but not more than four descriptor
SCS% JSYS Page 29
.SSAIC (Add interrupt channels)
words in a block.
SCA-TABLES.TXT
;States of a connection. Names in all caps are from corporate spec.
.CSCLO==1 ;Closed (CLOSED)
.CSLIS==2 ;Listening (LISTENING)
.CSCSE==3 ;Connect request was sent (CONNECT_SENT)
.CSCRE==4 ;Connect request was received (CONNECT_REC)
.CSCAK==5 ;Connect response was received (CONNECT_ACK)
.CSACS==6 ;Accept request was sent (ACCEPT_SENT)
.CSRJS==7 ;Reject request was sent (REJECT_SENT)
.CSOPN==10 ;Connection is open (OPEN)
.CSDSE==11 ;Disconnect request was sent (DISCONNECT_SENT)
.CSDRE==12 ;Disconnect request received (DISCONNECT_REC)
.CSDAK==13 ;Disconnect response received (DISCONNECT_ACK)
.CSDMC==14 ;Waiting for disconnect response (DISCONNECT_MATCH)
;States of a connection block
.BSFRE==:1 ;Free
.BSALL==:2 ;Allocate
.BSCNP==:3 ;Connect pending
.BSACP==:4 ;Accept pending
.BSRPN==:5 ;Reject pending
.BSCRP==:6 ;Credit pending
.BSDPN==:7 ;Disconnect pending
;Messages
.STORQ==0 ;Connect request
.LNORQ==^D64
.STORS==1 ;Connect response
.LNORS==^D16
.STARQ==2 ;Accept request
.LNARQ==^D64
.STARS==3 ;Accept response
.LNARS==^D16
.STRRQ==4 ;Reject request
.LNRRQ==^D16
.STRRS==5 ;Reject response
.LNRRS==^D12
.STDRQ==6 ;Disconnect request
.LNDRQ==^D16
.STDRS==7 ;Disconnect response
.LNDRS==^D12
.STCRQ==10 ;Credit request
.LNCRQ==^D12
.STCRS==11 ;Credit response
.LNCRS==^D12
.STAMG==12 ;Application message
.STADG==13 ;Application datagram
;Table X - calls from sysap to SCA.
;Note: if new connection state is in <>, it isn't set until the pending
;message has been sent
Routine State Legal? New block New connection
State State
SC.CON Closed Y CONN_PEND <connect_sent>
Listening
Connect_sent
Connect_rec
Connect_ACK
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
Routine State Legal? New block New connection
State State
SC.LIS Closed Y - Listen
Listening
Connect_sent
Connect_rec
Connect_ACK
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
Routine State Legal? New block New connection
State State
SC.ACC Closed
Listening
Connect_sent
Connect_rec Y ACC_PEND <Accept-sent>
Connect_ACK
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
* * Old code didn't change state
Routine State Legal? New block New connection
State State
SC.REJ Closed
Listening
Connect_sent
Connect_rec Y REJ_PEND <reject_sent>
Connect_ACK
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
* * * Old code left state as "listen"
Routine State Legal? New block New connection
State State
SC.DIS Closed Y FREE closed
Listening Y FREE closed
Connect_sent Y FREE closed
Connect_rec Y REJ_PEND reject_sent
Connect_ACK Y FREE closed
Open Y DIS_PEND disconnect_sent
Accept_sent Y FREE closed
Reject_sent Y FREE closed
Disconnect_sent Y FREE closed
Disconnect_rec Y DIS_PEND disconnect_match
Disconnect_ACK Y FREE closed
Disconnect_match Y FREE closed
;Table Y -- processing SCS work queue
Block Op code New connection
State to send State
CONN_PEND CONNECT_REQ connect_sent
ACC_PEND ACCEPT_REQ accept_sent
REJ_PEND REJECT_REQ reject_sent
DIS_PEND DISCON_REQ -- (already done)
CREDIT_PEND CREDIT_REQ --
;Table Z - sending an SCS message
Name Code Length priority Response
CONNECT_REQ .STORQ==0 .LNORQ==^D64 .MPCMM CONNECT_RSP
CONNECT_RSP .STORS==1 .LNORS==^D16 .MPCMM
ACCEPT_REQ .STARQ==2 .LNARQ==^D64 .MPCMM ACCEPT_RSP
ACCEPT_RSP .STARS==3 .LNARS==^D16 .MPCMM
REJECT_REQ .STRRQ==4 .LNRRQ==^D16 .MPCMM REJECT_RSP
REJECT_RSP .STRRS==5 .LNRRS==^D12 .MPCMM
DISCONNECT_REQ .STDRQ==6 .LNDRQ==^D16 .MPLOW DISCONNECT_RSP
DISCONNECT_RSP .STDRS==7 .LNDRS==^D12 .MPCMM
CREDIT_REQ .STCRQ==10 .LNCRQ==^D12 .MPFLO CREDIT_RSP
CREDIT_RSP .STCRS==11 .LNCRS==^D12 .MPCMM
;Table K - receiving a message
Name Code Current Legal? Response New connection
State State
CONNECT_REQ 0 Closed Y CONNECT_RSP NM
Listening Y CONNECT_RSP connect_received
Connect_sent
Connect_rec
Connect_ACK
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
Name Code Current Legal? Response New connection
State State
CONNECT_RSP 1 Closed
Listening
Connect_sent
success Y - Connect_ACK
failure Y - Closed
Connect_rec
Connect_ACK
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
* * * Old code set state to "closed no match" if failure
Name Code Current Legal? Response New connection
State State
ACCEPT_REQ 2 Closed Y ACCEPT_RSP NM closed
Listening
Connect_sent
Connect_rec
Connect_ACK Y ACCEPT_RSP Open
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
* * * * Old code closed v.c. if state was closed; required block state
of connect_pend, too
Name Code Current Legal? Response New connection
State State
ACCEPT_RSP Closed
Listening
Connect_sent
Connect_rec
Connect_ACK
Open
Accept_sent
Match Y - Open
No match Y - closed
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
* * * * Old code expected state to be connect_received; set new state
to closed; required block state of accept_pend
Name Code Current Legal? Response New connection
State State
REJECT_REQ Closed
Listening
Connect_sent
Connect_rec
Connect_ACK Y REJECT_RSP Closed
Open
Accept_sent
Reject_sent
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
* * * Old code set new state to closed-rejected
* * * Why not treat "closed" as legal as in accept_request
Name Code Current Legal? Response New connection
State State
REJECT_RSP Closed
Listening
Connect_sent
Connect_rec
Connect_ACK
Open
Accept_sent
Reject_sent Y - closed
Disconnect_sent
Disconnect_rec
Disconnect_ACK
Disconnect_match
* * * Old code expected state to be "listen"; left it as "listen"
Name Code Current Legal? Response New connection
DISCONNECT_REQ Closed
Listening
Connect_sent
Connect_rec
Connect_ACK
Open Y DISCONNECT_RSP disconnect_received
Accept_sent
Reject_sent
Disconnect_sent Y DISCONNECT_RSP disconnect_match
Disconnect_rec
Disconnect_ACK Y DISCONNECT_RSP closed
Disconnect_match
Name Code Current Legal? Response New connection
State State
DISCONNECT_RSP Closed
Listening
Connect_sent
Connect_rec
Connect_ACK
Open
Accept_sent
Reject_sent
Disconnect_sent Y - Disconnect_ACK
Disconnect_rec
Disconnect_ACK
Disconnect_match Y - closed
+---------------+
! d i g i t a l ! I N T E R O F F I C E M E M O R A N D U M
+---------------+
TO: Distribution
DATE: 10 May 83
FROM: Clair Grant
DEPT: LCG Software
Engineering
LOC: MRO1-2/L10
EXT: 6877
SUBJ: TOPS-20 Systems Communications Service Tester
This is a description of the SCSTST project, the test vehicle for
TOPS-20's implementation of the corporate Systems Communications
Acrhitecture being used on the CI. It is believed that such a tester
is a necessity for the ultimate success of the project, not just
initial debug and release, but for future development, maintenance,
and performance measurement.
Both DECnet and ARPANET have testers, DTR/DTS and TRAFIC,
respectively; they have been invaluable in recent TOPS-20 development
efforts and the same need exists for SCS.
Page 2
1.0 PROJECT GOALS
The project goals for the TOPS-20 System Communication Service (SCS)
test package are to provide:
1. a comprehensive tester for the SCS% JSYS, the SCA protocol,
and the CI device driver
2. a quick and reliable means of determining that SCS is in
working order
3. a tool for performance comparison between different versions
of TOPS-20
4. a command file which, when TAKEn by SCSTST, will tell the
user that SCS is functioning properly
2.0 RESTRICTIONS/DEFICIENCIES
The SCS tester will have the following restrictions:
1. it will not test every invalid way in which the SCS% JSYS can
be called but will do some fault insertion
2. it will be used between TOPS-20 systems only
3.0 FUTURE CONSIDERATIONS
Any developer working on the TOPS-20 SCS implementation should view
the tester as an integral part of the product. An SCS development
project should not be considered complete until the tester has been
modified, if necessary, and run to verify that SCS is working
properly. For example, SCSTST will look for specific error returns in
certain situations; if someone changes the way the monitor handles an
error condition it must be verified that SCSTST is not effected, or
SCSTST must be modified to handle the new situation.
Also, the design of the SCS tester could be used by other operating
systems to provide a model by which inter-system testing could be
done, e.g., DECnet's DTR/DTS.
4.0 GENERAL DESIGN
There will be 1 source file SCSTST.MAC. It will use the CMD package
to implement the command interface; all functions of the SCS% JSYS
will be used. SCSTST can be run in either "server" or "initiator"
mode. Server mode responds to incoming test requests, and initiator
Page 3
mode generates test requests.
SCSTST creates a multi-forking environment. The top fork is the
command processor; it creates test streams (sub-forks) as
necessitated by the user's command selection. Also, a sub-fork is
created which performs the logging function. As tests run, they log
information into a buffer which is periodically emptied to a file by
the logging fork.
In server mode, it starts a sub-fork and opens an SCS listener;
whenever an incoming connection arrives, that fork processes the
connection attempt (and subsequent test messages) and another sub-fork
is established as the listener. When a test finishes, the sub-fork is
killed. Thus, multiple tests can be directed at a single node's
server as long as the maximum number of sub-forks has not been
exceeded. Likewise, in initiator mode, SCSTST creates a sub-fork for
each test called for by the user. When a test finishes, the sub-fork
is killed. The user can create multiple tests, possibly to different
nodes, simultaneously, as long as the maximum number of sub-forks has
not been exceeded.
5.0 RECORDING OF RESULTS
An entry will be made in a log file for each incoming test request and
its results. Counters will be maintained by the program and their
values will be entered, as appropriate, in the log.
There will also be a trace mode. It will provide a blow-by-blow
account of each SCS% function performed and the results. Logging must
be enabled for tracing to occur.
6.0 SCS% FUNCTION TESTING
SCSTST will use the SCS% options in the following tests:
.SSCON all tests
.SSLIS declaring SCSTST as the server
.SSACC all tests except REJECT
.SSREJ REJECT test
.SSDIS all tests except REJECT
.SSSDG DATAGRAM test
.SSQRD DATAGRAM test
.SSSMG MESSAGE test
Page 4
.SSQRM MESSAGE test
.SSCRD DATAGRAM test
.SSCRM MESSAGE test
.SSCSP IDLE test
.SSRCD SCSTST initialization, all tests
.SSSTS IDLE, DATAGRAM, MESSAGE, and DMA tests
.SSRMG MESSAGE test
.SSRDG DATAGRAM test
.SSGDE DMA test
.SSEVT all tests
.SSMAP DMA test
.SSUMP DMA test
.SSSND DMA test
.SSREQ DMA test
.SSRPC all tests
.SSAIC SCSTST initialization, all tests
7.0 USER INTERFACE
This section defines the command language of SCSTST.
7.1 DECLARE
The DECLARE command has 2 options - initiator and server; this
establishes SCSTST as either the initiator or the server. You can
only run the program in 1 of the 2 modes; also, you can't switch from
one mode to the other. If you are running as an initiator and want to
be a server, you must restart the program. Example:
SCSTST>DECLARE (SCSTST TO BE THE) INITIATOR
Page 5
7.2 DISABLE
The DISABLE command directs SCSTST to stop performing some function;
there are 2 options - logging and tracing.
SCSTST>DISABLE (TEST FEATURE) TRACING
7.3 ENABLE
The ENABLE command directs SCSTST to start performing some function;
there are 2 options - logging tracing. When SCSTST is started,
tracing is off and logging goes to the TTY. Example:
SCSTST>ENABLE (TEST FEATURE) LOGGING (OUTPUT TO) FOO.LOG
7.4 EXIT
The EXIT command returns the user to TOPS-20 command level. The
program is continuable, with no change to test parameters. Example:
SCSTST>EXIT (TO TOPS-20 COMMAND LEVEL)
7.5 HELP
The HELP command prints out text which describes the general use of
the program. It does not provide specific information about
individual commands. Example:
SCSTST>HELP (WITH SCSTST)
7.6 SHOW
The SHOW command displays the current status of SCSTST. The current
status of logging, tracing, and all test streams (including test
parameters) are shown. The output from SHOW always for to TTY:.
Example:
SCSTST>SHOW (CURRENT TEST PARAMETERS)
7.7 STOP
The STOP command is use to ternminate a running test stream. Example:
SCSTST>STOP (TEST #) 2
Page 6
7.8 TAKE
The TAKE command is used to execute SCSTST commands from a file. The
default file is SCSTST.CMD. Example;
SCSTST>TAKE (COMMANDS FROM) FOO.CMD
7.9 TEST
The TEST command defines the remote node and the test to be run. The
test options are:
1. IDLE - the idle test causes the initiator to send a connect
with optional data. The server reads the first byte of
optional data, finds the idle code, verifies that the rest of
the optional data bytes are null, and accepts the connection
supplying the same optional data it received in the connect.
When the server is notified that it is ok to send, it simply
goes to sleep, periodically waking to check that the
connection is still there. Meanwhile, the initiator was
notified that its connection was accepted and checked for the
optional data it sent in the connect. It then goes to sleep,
waking periodically to check that connection is still there.
The initiator sends a disconnect when the time period is up.
SCSTST>TEST (TO NODE) 3 (FEATURE) IDLE-CONNECTION (FOR TIME
PERIOD) 00:02:00
2. CONNECT - the connect test has 2 options, with and without
optinal data. The "no optional data" test causes the
initiator to send a connect request with no optional data.
The server reads the first byte of optional data, finds
nothing and verifies that the rest of the optional data block
is empty; it then does an accept with no optional data. When
the server is notified that it is OK to send on this
connection, it does a disconnect with reason code
connect-with-no-optional-data-ok. Meanwhile, the initiator
was notified that its connection had been accepted, and
checked for no optional data. When the initiator receives the
disconnect, it verifies the reason code.
The "optional data" test causes the initiator to send a
connect request with optional data. The server reads the
first byte of optional data, finds the
connect-no-optional-data code and verifies that the rest of
the optional data block has a program-specified set of
characters; it then does an accept with the identical
optional data it received in the connect. When the server is
notified that it is OK to send, it does a disconnect with
reason code connect-with-no-optional-data-ok. Meanwhile, the
initiator was notified that its connection had been accepted,
and checked for optional data matching what it sent in the
connect. When the initiator receives the disconnect, it
Page 7
verifies the reason code.
Example:
SCSTST>TEST (TO NODE) 3 (FEATURE) CONNECT (WITH) NO-OPTIONAL-DATA
3. REJECT - the reject test has 2 options, with and without
reason code. The "reason code" test causes the initiator to
send a connect request with optional data. The server reads
the first byte of optional data, finds the code for
reject-reason code, verifies that the rest of the optional
data is null, and does a reject with reason code
reject-reason-ok. When the initiator is notified that the
connection attempt was rejected, it verifies the reason code.
The "no reason code" test causes the initiator to send a
connect request with optional data. The server reads the
first byte of optional data, finds the code for
reject-no-reason, verifies that the rest of the optional data
is null, and does a reject with no reason code. When the
initiator is notified that the connection attempt was
rejected, it verifies that no reason code was returned.
Example:
SCSTST>TEST (TO NODE) 3 (FEATURE) REJECT (WITH) REASON-CODE
4. DISCONNECT - the disconnect test has 2 options, with and
without reason code. The "reason code" test causes the
initiator to send a connect with optional data. The server
reads the first byte of optional data, finds the
disconnect-reason code and verifies that the rest of the
optional data block is empty; it then does an accept with the
identical optional data it received in the connect. When the
server is notified that it is OK to send, it does a disconnect
with reason code disconnect-reason-ok. Meanwhile, the
initiator was notified that its connection had been accepted,
and checked for optional data matching what was sent in the
connect. When the initiator receives the disconnect, it
verifies the reason code.
The "no reason code" test sends a connect with optional data.
The server reads the first byte of optional data, finds the
reject-no-reason code and verifies that the rest of the
optinal data is null; it then does and accept with the
optional data it received on the connect. When the server is
notified that it ok to send, it does a disconnect with no
reason code. Meanwhile, the initiator has been notified that
the connect was accepted, and verifies the optional data.
When the initiator receives the disconnect, it checks for no
reason code.
Example:
SCSTST>TEST (TO NODE) 3 (FEATURE) DISCONNECT (WITH) NO-REASON-CODE
Page 8
5. DATAGRAM - the datagram test has 3 options: a) number of
bytes per datagram, b) duration of the test, and c) transfer
mode. The initiator sends a connect with optional data. The
server reads the optional data and finds the datagram-mode
code and the byte count, verifies that the rest of the
optional data is null, and does and accept with optional data
matching what it received in the connect. When it is notified
that it is OK to send, it simply waits for the datagrams to
arrive. Meanwhile, the initiator has been notified that its
connect has been accepted, verifies the optional data, and
begins sending datagrams. The server verifies each datagram
(the byte pattern is predefined in the program) and returns it
to the initiator who also verifies the byte pattern. When the
time period runs out the initiator sends a disconnect.
Example:
SCSTST>TEST (TO NODE) 3 (FEATURE) DATAGRAMS (OF BYTE COUNT) 200 (FOR
TIME PERIOD) 00:02:00 (IN MODE) HIGH-DENSITY
6. MESSAGE - analogous to DATAGRAM
Example:
SCSTST>TEST (TO NODE) 3 (FEATURE) MESSAGES (OF BYTE COUNT) 200 (FOR
TIME PERIOD) 00:02:00 (IN MODE) INDUSTRY-COMPATIBLE
7. DMA-TRANSFERS - analogous to DATAGRAM
Example:
SCSTST>TEST (TO NODE) 3 (FEATURE) DMA-TRANSFERS (OF BUFFER SIZE) 50
(WITH BUFFER POOL OF) 10 (FOR TIME PERIOD) 00:02:00
7.10 WAIT
The WAIT command directs SCSTST to wait for all current test streams
to stop before executing the next SCSTST command.
SCSTST>WAIT (FOR ALL TESTS TO STOP)
Page 9
8.0 VERIFICATION COMMAND SET
The following command set should be used to verify that TOPS-20's SCS
is in basic working order. It assumes a 2 node configuration; if
more nodes are available, a similar command set would be appropriate
for each node. The test should take about 20 minutes to run to
completion.
DECLARE INITIATOR
!Part 1 - individual connection management tests
!
TEST 1 CONNECT NO-OPTIONAL-DATA
WAIT
TEST 1 CONNECT OPTIONAL DATA
WAIT
TEST 1 DISCONNECT NO-REASON
WAIT
TEST 1 DISCONNECT REASON
WAIT
TEST 1 REJECT NO-REASON
WAIT
TEST 1 REJECT REASON
WAIT
!
!Part 2 - simultaneous connection management tests
!
TEST 1 CONNECT NO-OPTIONAL-DATA
TEST 1 CONNECT OPTIONAL DATA
TEST 1 DISCONNECT NO-REASON
TEST 1 DISCONNECT REASON
TEST 1 REJECT NO-REASON
TEST 1 REJECT REASON
TEST 1 CONNECT NO-OPTIONAL-DATA
TEST 1 CONNECT OPTIONAL DATA
TEST 1 DISCONNECT NO-REASON
TEST 1 DISCONNECT REASON
TEST 1 REJECT NO-REASON
TEST 1 REJECT REASON
!
!Part 3 - individual data tests, 2 minutes each
!
TEST DATAGRAM 10 2 INDUSTRY-COMPATIBLE
WAIT
TEST 1 DAAGRAM 10 2 HIGH-DENSITY
WAIT
TEST 1 MESSAGE 10 2 INDUSTRY-COMPATIBLE
WAIT
TEST 1 MESSAGE 10 2 HIGH-DENSITY
WAIT
TEST 1 DMA-TRANSFERS 10 5 2
WAIT
!
!Part 4 - multiple datagram test, 1 minute each
!
Page 10
TEST 1 DATAGRAM 0 1 INDUSTRY-COMPATIBLE ;an empty datagram
TEST 1 DATAGRAM 1 1 HIGH-DENSITY ;a small datagram
TEST 1 DATAGRAM 200 1 INDUSTRY-COMPATIBLE ;a medium datagram
TEST 1 DATAGRAM 604 1 HIGH-DENSITY ;the biggest datagram
!
!Part 5 - multiple message test, 1 minute each
!
TEST 1 MESSAGE 0 1 INDUSTRY-COMPATIBLE ;an empty message
TEST 1 MESSAGE 1 1 HIGH-DENSITY ;a small message
TEST 1 MESSAGE 50 1 INDUSTRY-COMPATIBLE ;a medium message
TEST 1 MESSAGE 148 1 HIGH-DENSITY ;the biggest message
!
!Part 6 - multiple DMA test, 1 minute each
!
TEST 1 DMA-TRANSFERS 0 3 1 ;an empty transfers
TEST 1 DMA-TRANSFERS 1 3 1 ;a small transfer
TEST 1 DMA-TRANSFERS 100 3 1 ;a medium transfer
TEST 1 DMA-TRANSFERS 512 3 1 ;the biggest transfer
!
!Part 7 - mixed data test, 5 minutes each
!
TEST 1 IDLE-CONNECTION
TEST 1 DATAGRAM 10 5 INDUSTRY-COMPATIBLE
TEST 1 DATAGRAM 10 5 HIGH-DENSITY
TEST 1 MESSAGE 10 5 INDUSTRY-COMPATIBLE
TEST 1 MESSAGE 10 5 HIGH-DENSITY
TEST 1 DMA-TRANSFERS 10 5 5
[END OF SCA-INFO.MEMOS]