THIS FILE CONTAINS: o The LCG 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) ------------------- 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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,) 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/ B5 ! 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/ B5 ! 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 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 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 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]