DECnet DIGITAL Network Architecture Maintenance Operations Functional Specification Version 3.0.0 September 1983 .-------. `=======' .------. .---. .-------. | | .-------. `======' `===' `=======' | | `=======' \\ ..| |\ \\ \ | | / / \...| .-----. .-------------. ......| | \ \ \ .-------. .-------. o\.--------------. o `--/ /--' `---|\--' o `-----\\ \-----' o / / | \ o \\ \ o / / | \ O \\ \ O ------------. .----------------. .-----------------. /| | \ \ \ / | \ \ \ \ /.-----| \------.\ \ / `-----| \-----' \ \ --------. / .---------------------. \ .----------------------. / | | | \| \ \ | / /----' `---------------------' `--------\ \ \-------' / / \ \ \ / / \ \ \ / .------------------------ / |\ \ \ \ \ \ \ \ \ \ \ \ \ .---------------- \ | \ \| \ \ `---------\ \ Maintenance Operations Functional Specification Page 2 ________ This document describes the structure, functions, interfaces, and protocols needed for the low level maintenance of a DECnet network. _______ _________ ___________ MAYNARD, MASSACHUSETTS 01754 Copyright (c) 1980, 1983 by Digital Equipment Corporation Table of Contents Page 3 CONTENTS 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . 6 1.1 Functional Description . . . . . . . . . . . . . . 7 1.2 Design Scope . . . . . . . . . . . . . . . . . . . 8 1.2.1 Requirements . . . . . . . . . . . . . . . . . . 8 1.2.2 Goals . . . . . . . . . . . . . . . . . . . . . 8 1.2.3 Non-goals . . . . . . . . . . . . . . . . . . . 9 2 MODELS . . . . . . . . . . . . . . . . . . . . . . . 9 2.1 Relationship to DIGITAL Network Architecture . . . 9 2.2 Simplified Network Model . . . . . . . . . . . . 12 2.2.1 Low Level Maintenance Operation Model . . . . 12 3 INTERFACES . . . . . . . . . . . . . . . . . . . . 13 3.1 Data Link Interface . . . . . . . . . . . . . . 13 3.1.1 Maintenance-check . . . . . . . . . . . . . . 15 3.1.2 Open . . . . . . . . . . . . . . . . . . . . . 15 3.1.3 Close . . . . . . . . . . . . . . . . . . . . 16 3.1.4 Transmit . . . . . . . . . . . . . . . . . . . 16 3.1.5 Transmit-poll . . . . . . . . . . . . . . . . 17 3.1.6 Receive . . . . . . . . . . . . . . . . . . . 18 3.1.7 Receive-poll . . . . . . . . . . . . . . . . . 19 3.1.8 Receive-abort . . . . . . . . . . . . . . . . 19 3.2 User Level Maintenance Operation Interface . . . 20 3.2.1 Dump/Load Functions . . . . . . . . . . . . . 21 3.2.2 Loop Test Functions . . . . . . . . . . . . . 29 3.2.3 Remote Console Functions . . . . . . . . . . . 33 3.3 Network Management Interface . . . . . . . . . . 45 3.3.1 Set-state . . . . . . . . . . . . . . . . . . 45 3.3.2 Read-state . . . . . . . . . . . . . . . . . . 46 3.3.3 Add-dump/load-entry . . . . . . . . . . . . . 47 3.3.4 Remove-dump/load-entry . . . . . . . . . . . . 48 3.3.5 Set-dump/load-parameter . . . . . . . . . . . 48 3.3.6 Read-dump/load-list . . . . . . . . . . . . . 49 3.3.7 Read-dump/load-parameters . . . . . . . . . . 49 3.3.8 Set-console-parameter . . . . . . . . . . . . 50 3.3.9 Read-console-parameters . . . . . . . . . . . 51 3.4 Interface Usage Examples . . . . . . . . . . . . 51 3.4.1 A System Boot Monitor . . . . . . . . . . . . 52 3.4.2 A Minimal ASCII Console Carrier . . . . . . . 52 4 OPERATION . . . . . . . . . . . . . . . . . . . . 54 4.1 Common Algorithms . . . . . . . . . . . . . . . 54 4.2 Dump/Load . . . . . . . . . . . . . . . . . . . 55 4.2.1 Dump/Load Server . . . . . . . . . . . . . . . 56 4.2.2 Dump/Load Requester . . . . . . . . . . . . . 60 4.3 Loop Test . . . . . . . . . . . . . . . . . . . 62 4.3.1 Loop Server . . . . . . . . . . . . . . . . . 62 4.3.2 Loop Requester . . . . . . . . . . . . . . . . 63 4.4 Remote Console . . . . . . . . . . . . . . . . . 63 4.4.1 Console Server . . . . . . . . . . . . . . . . 63 4.4.2 Console Requester . . . . . . . . . . . . . . 66 Table of Contents Page 4 5 PROTOCOL MESSAGES . . . . . . . . . . . . . . . . 69 5.1 Dump/Load . . . . . . . . . . . . . . . . . . . 70 5.1.1 Memory Load with Transfer Address . . . . . . 70 5.1.2 Memory Load . . . . . . . . . . . . . . . . . 71 5.1.3 Request Memory Dump . . . . . . . . . . . . . 72 5.1.4 Request Program . . . . . . . . . . . . . . . 72 5.1.5 Request Memory Load . . . . . . . . . . . . . 73 5.1.6 Request Dump Service . . . . . . . . . . . . . 74 5.1.7 Memory Dump Data . . . . . . . . . . . . . . . 75 5.1.8 Parameter Load with Transfer Address . . . . . 75 5.1.9 Dump Complete . . . . . . . . . . . . . . . . 78 5.1.10 Assistance Volunteer . . . . . . . . . . . . . 78 5.2 Loop Test . . . . . . . . . . . . . . . . . . . 78 5.2.1 Loop Data Message . . . . . . . . . . . . . . 78 5.2.2 Looped Data Message . . . . . . . . . . . . . 79 5.3 Remote Console . . . . . . . . . . . . . . . . . 79 5.3.1 Boot . . . . . . . . . . . . . . . . . . . . . 79 5.3.2 Request ID . . . . . . . . . . . . . . . . . . 81 5.3.3 System ID . . . . . . . . . . . . . . . . . . 81 5.3.4 Request Counters . . . . . . . . . . . . . . . 84 5.3.5 Counters . . . . . . . . . . . . . . . . . . . 85 5.3.6 Reserve Console . . . . . . . . . . . . . . . 85 5.3.7 Release Console . . . . . . . . . . . . . . . 85 5.3.8 Console Command and Poll . . . . . . . . . . . 86 5.3.9 Console Response and Acknowledge . . . . . . . 86 APPENDIX A PREDEFINED VALUES A.1 Communication Devices . . . . . . . . . . . . . . A-1 A.2 Data Links . . . . . . . . . . . . . . . . . . . . A-2 A.3 System Processors . . . . . . . . . . . . . . . . A-2 APPENDIX B DATA LINK SPECIFIC INFORMATION B.1 DDCMP . . . . . . . . . . . . . . . . . . . . . . B-1 B.2 LAPB . . . . . . . . . . . . . . . . . . . . . . . B-1 B.3 Ethernet . . . . . . . . . . . . . . . . . . . . . B-1 APPENDIX C IMPLEMENTATION SPECIFIC DUMP/LOAD CHARACTERISTICS C.1 Secondary Loader . . . . . . . . . . . . . . . . . C-1 C.2 Tertiary Loader . . . . . . . . . . . . . . . . . C-1 APPENDIX D REVISION HISTORY D.1 Changes from Version 1.1 to Version 2.0 . . . . . D-1 D.2 Changes from Version 2.0 to Version 2.1.0 . . . . D-2 D.3 Changes from Version 2.1.0 to Version 3.0.0 . . . D-2 Table of Contents Page 5 APPENDIX E ETHERNET LOOP TESTING E.1 Introduction . . . . . . . . . . . . . . . . . . . E-1 E.1.1 Goals . . . . . . . . . . . . . . . . . . . . . E-1 E.1.2 Loop Testing Functions . . . . . . . . . . . . . E-1 E.1.3 Functional Model . . . . . . . . . . . . . . . . E-2 E.1.4 Conformance Requirements . . . . . . . . . . . . E-3 E.2 Interfaces . . . . . . . . . . . . . . . . . . . . E-3 E.2.1 Data Interface . . . . . . . . . . . . . . . . . E-4 E.2.1.1 LoopDirect . . . . . . . . . . . . . . . . . . E-4 E.2.1.2 LoopAssisted . . . . . . . . . . . . . . . . . E-5 E.2.1.3 LoopPoll . . . . . . . . . . . . . . . . . . . E-6 E.2.1.4 LoopAbort . . . . . . . . . . . . . . . . . . E-7 E.2.2 Network Management Interface . . . . . . . . . . E-7 E.2.2.1 EnableServer . . . . . . . . . . . . . . . . . E-7 E.2.2.2 DisableServer . . . . . . . . . . . . . . . . E-7 E.2.2.3 EnableAssistance . . . . . . . . . . . . . . . E-7 E.2.2.4 DisableAssistance . . . . . . . . . . . . . . E-7 E.2.2.5 ReadStatus . . . . . . . . . . . . . . . . . . E-8 E.3 Loop Test Examples . . . . . . . . . . . . . . . . E-8 E.3.1 Local Control Test Example . . . . . . . . . . . E-8 E.3.2 Remote Control Test Example . . . . . . . . . . E-9 E.4 Operation . . . . . . . . . . . . . . . . . . . . E-9 E.4.1 Loop Server . . . . . . . . . . . . . . . . . E-10 E.4.2 Loop Requester . . . . . . . . . . . . . . . . E-11 E.4.2.1 LoopDirect Function . . . . . . . . . . . . E-11 E.4.2.2 LoopAssisted Function . . . . . . . . . . . E-11 E.4.2.3 LoopPoll Function . . . . . . . . . . . . . E-12 E.4.2.4 LoopAbort Function . . . . . . . . . . . . . E-12 E.5 Protocol Messages . . . . . . . . . . . . . . . E-12 E.5.1 Reply Message . . . . . . . . . . . . . . . . E-13 E.5.2 Forward Data Message . . . . . . . . . . . . . E-13 Introduction Page 6 INTRODUCTION Certain maintenance functions need to be performed remotely at a low level in the overall network architecture. These are functions that cannot depend on high level software being operational in the system being maintained. In the context of this specification, low level implies direct usage of data link services. High level means such network functions as routing and end-to-end, virtual circuit type protocols, both of which are also users of data link services. This specification assumes that only a minimal level of data link services are available to support maintenance operations, and that these maintenance operations provide a base on which any higher level functions can be built. This document describes the structure, functions, interfaces, and protocols needed for low level maintenance. DNA is the model on which DECnet implementations are based. A DECnet network is a family of software modules, data bases, and hardware components used to tie DIGITAL systems together for resource sharing, distributed computation or remote system communication. DNA is a layered structure. Modules in each layer perform distinct functions. Modules within a single DNA layer (but typically in different computer systems) communicate using specific protocols. Modules in different layers (but typically in the same computer system) interface using subroutine calls or a system-dependent method. In this document interfaces are described in terms of calls to subroutines. This document assumes that the reader is familiar with computer communications and DECnet. The primary audience consists of those who implement DECnet systems or other systems under different architectures, but requiring the same functions. However, the document may be useful to anyone interested in the details of DECnet structure. The other current DNA functional specifications are: ___ ____ ______ ________ _____ __________ _____________ 5.6.0, Order No. AA-K177A-TK ___ _______ ____ ______________ _______ ________ _______ __________ _____________ ___ ________ ____ ____ __________ _____________ Order No. AA-Y298A-TK ___ ________ ____ _______ ____________ _____________ 1.0.0, Order No. AA-X440A-TK ___ _______ __________ __________ _____________ Order No. AA-X437A-TK ___ _______ ________ ________ __________ _____________ 4.0.0, Order No. AA-X439A-TK Introduction Page 7 ___ _______ _____ __________ _____________ No. AA-X435A-TK ___ _______ _______ __________ _____________ No. AA-K182A-TK ___ ________ _ _ _____ ____ _______ _ ____ ____ _____ ___ ________ _____ ______________ Xerox), Order No. AA-K759B-TK ______ _______ _______ ____________ ______ ___ _______ ___________ (Order No. AA-N149A-TC) provides an overview of the network architecture and an introduction to each of the DNA functional specifications. Functional Description Low level maintenance functions are divided into three categories. Operation within any category depends on the operability of at least part of the preceding category. The categories are: 1. Communications test 2. System console 3. System load/dump Each of these functions can be viewed either from the active or passive end. The active end is the one that is driving the maintenance function and the passive end is the one that is responding. Communications test determines if the data link communications path is operative. System console provides low level access to a system for the functions of: . Identify processor . Read data link counters . Boot system . Console carrier The console carrier is a general purpose console input/output channel. It provides a common communication mechanism to allow remote access regardless of console command specifics. Introduction Page 8 System load/dump copies the contents of processor memory to or from a remote system. boot causing a system to initialize itself. Initialization may include load used to mean the process of transferring a system image into processor memory from some source. This is one potential effect of a boot command. The source of major interest in this specification is a remote system, accessed via a communication channel. Design Scope The low level maintenance operations require certain characteristics to be present, attempt to meet certain goals, and lack some features that are not within the scope of the design. Requirements The maintenance operation design must have the following characteristics: . The functions previously mentioned must be included in the design. . Active and passive sides of maintenance operations can be implemented and used independently. The three categories of maintenance operations are inter-dependent only in simple, clearly defined ways. . Effects of errors (such as operator errors, protocol errors, and hardware errors) are minimized, always leaving a system in a well defined state. . It must be compatible with inter-company standard Ethernet loopback protocol. . Implementations may select subsets of functions based on particular product need. Goals The maintenance operation design tries to have the following characteristics: . Functions and protocols are upward compatible with the DNA Maintenance Operation Protocol (MOP) version 2.1. Introduction Page 9 . Algorithms, particularly those found in memory-only systems, are processing and memory efficient. Communications efficiency is a secondary goal. In the specific case of down-line load and up-line dump, overall speed of operation is an important goal. . Extensible to accommodate newly developed functions or modification of current functions. . Operates independently of the underlying communication mechanism (e.g. DDCMP, Ethernet, etc.). . No complex algorithms or data bases. Minimal state kept in the smallest systems. Non-goals The maintenance operation design does not try to have the following characteristics: . Isolation of components that have failed in a failing system. . System security in the low level maintenance functions. MODELS This section describes the relationship of the low level maintenance operations to other network layers and modules. Although this specification primarily relates the maintenance operations to DNA, the same relationships can also be applied within other network architectures, such as the DIGITAL System Communication Architecture. Relationship to DIGITAL Network Architecture The maintenance operations reside in the DNA Network Management Layer. They are direct users of the DNA Data Link Layer. The other DNA layers are not required in the support of the low level maintenance operations unless such services as remote file access are to be used. The following diagram shows the overall layering of DNA. A later diagram shows the simplified model that is applicable to the low level maintenance operations. Models Page 10 .----------------------------. | User Modules | `----------------------------' | | | | | V .- | ------- | ------------------------------------. .------| | Network | Management Modules | | `- | ------- | ------------------------------------' | | | | | | | | V V | | | .- | -------------------------------- | ------. | |----> | | Network Application Modules | | | | `- | -------------------------------- | ------' | | | | | | | | V V V | | | .---------------------------------------. | | |----> | Session Control Modules | | | | `---------------------------------------' | | | | | | | V | | | .---------------------------. | | |------------> | End Communication Modules | | | | `---------------------------' | | | | | | | V | | | .---------------------------. | | |------------> | Routing Modules | | | | `---------------------------' | | | | | | | V V V | .-------------------------------------------. |------------> | Data Link Modules | | `-------------------------------------------' | | | V | .---------------------------. `------------> | Physical Link Modules | `---------------------------' | `-------------------------------- NOTE Horizontal arrows show direct access for control and observation of parameters, counters, etc. Vertical arrows show interfaces between layers for normal user operations such as file access, down-line load, and logical link usage. Each layer in DNA consists of functional modules and protocols. Generally, modules use the services of the next lower layer. In this document, the service relationship is demonstrated in the way the interfaces are modeled, as calls to subroutines. Note that the Network Management Layer interfaces directly with each of the lower Models Page 11 layers. Also, the layers above Session Control interface directly with it. For this reason the upper three layers are sometimes referred to as the "end user." Modules of the same type in the same layer communicate with each other to provide their services. The rules governing this communication and the messages required constitute the protocol for those modules. Messages are typically exchanged between equivalent modules in different nodes. However, equivalent modules within a single node can also exchange messages. A brief description of each layer follows in order from the highest to the lowest layer: User Layer. services and programs. Programs such as the Network Control Program, which interfaces with the Network Management Layer, and file transfer programs, which interface with the Network Application Layer, reside in the User Layer. Network Management Layer. only one that has direct access to each lower layer for control purposes. Modules in this layer provide user control over and access to network parameters and counters. These modules also perform up-line dumping, down-line loading, and testing functions. Network Application Layer. Layer support network functions, such as remote file access and file transfer, used by the User and Network Management Layers. Session Control Layer. system-dependent aspects of logical link communication, which allows messages to be sent from one node to another in a network. Session Control functions include name-to-address translation, process addressing, and, in some systems, process activation and access control. End Communication Layer. the system-independent aspects of logical link communication. Routing Layer. called packets, between source and destination nodes. Data Link Layer. concerning data integrity and physical channel management. Physical Link Layer. part of the device driver for each communications device plus the communications hardware itself. The hardware includes interface devices, modems, and the communication lines. Models Page 12 Simplified Network Model The following diagram shows a simplified relationship of the maintenance operations to the rest of the network architecture. .------. User | User | Layer `------' . . . . . . . . . . . | . . . . . . . . . . . . . . . . | .-------------. Network | Maintenance | Management | Operations | Layer `-------------' . . . . . . . . . | . | . | . . . . . . . . . . . . . . | | | .-------' | ` --------. Data | | | Link .-------. .----------. .-------. Layer | DDCMP | | Ethernet | | Other | | Data | | Data | | Data | | Link | | Link | | Link | `-------' `----------' `-------' Low Level Maintenance Operation Model The following diagram shows the components within the maintenance operation module. .----------------------------------------------------------------------. | U s e r P r o c e s s e s | `----------------------------------------------------------------------' | | | | | | | | | | | .-----------. | .-----------. | | .-----------. | | | `-| Dump/Load | `-| Dump/Load | | | | Dump/Load | | | | | Data Base |===| Server | | | | Requester | | | | `-----------' `-----------' | | `-----------' | | | | | | | | | | | .-------------------' | | | | | | | | | | | | .-------' | | | .----------' | | | | | | | | | | | | | | | | .-------' | | | | .-----------. | | .---------. | | .--------. .----------. | Console | | `--| Console | | `--| Loop | | Loop | | Requester | | | Server | | | Server | | Requester| `-----------' | `---------' | `--------' `----------' | | | | | | .-----------------------------------------------------------------------. | D a t a L i n k | `-----------------------------------------------------------------------' Models Page 13 Requesters are the processes responsible for initiation of maintenance operations. This can be done either at higher level user request, or because of information obtained from a lower level. Requesters are the active side of a maintenance operation. Servers are the processes that respond to maintenance requesters. They are the passive side of a maintenance operation. Servers should not try to do more than they are capable of. For example, it is not acceptable to always volunteer to load every system that requests it and then take too long to get done because the local resources are overextended. The diagram shows servers and requesters as separate to represent their functional independence. In an implementation that supports multiple servers and/or requesters that use the same protocol type, they may have to be more closely coupled so that messages received through the data link are properly demultiplexed. Also, servers and requesters that allow multiple users must further demultiplex messages to the proper user processes. The Dump/Load Data Base contains default information that the Dump/Load Server uses to fill in necessary values in incomplete requests. Lines to the top of processes indicate flow of the control data that initiates processing. Lines to the side indicate Network Management control. The double horizontal line indicates data base access. INTERFACES The following sections describe the interfaces related to maintenance operations. The function descriptions are in terms of subroutines with input and output arguments. These subroutines are to be understood as abstract, functional descriptions. Actual implementations may vary, for example in synchronization techniques, as long as they provide the same functions. References to buffers in all of the following subroutine descriptions assume a buffer descriptor containing buffer address, maximum buffer length, and, if applicable, length of information in buffer. Data Link Interface Maintenance operations can be performed over communication channels provided by different data link disciplines. All of the potential data link user interfaces are abstracted into the functions required for maintenance operations. This section describes that interface. This section is included to define exactly what services a data link must provide so that the low level maintenance functions can be performed. It is an abstract representation of all possible data link interfaces, in terms that are directly applicable to low level Interfaces Page 14 maintenance operations. From the perspective of maintenance operations, there are two data link configurations: point-to-point and multiaccess. Point-to-point data links are those where there is a single node on the each end of a logical channel. Transmits and receives are always between these two nodes. Multipoint is treated as point-to-point, in the sense that each logical channel (tributary) is identified and used independently. Multiaccess data links are those where the number and identification of all adjacent nodes are not necessarily known. On multiaccess data links, node identification must accompany transmit and receive requests. Additionally, multiaccess data links may provide multicast service for communications with a class of nodes. Independently of configuration, some data links may allow concurrent operation of both normal and maintenance traffic. Others may allow maintenance traffic only in a mode that excludes normal traffic. This interface assumes that all data links offer the same basic services, framing and error checking. The data link frames messages and provides the length of received messages. Messages are sent and received in the order they were offered by the sender. Messages that the data link delivers to the receiver have been checked for bit errors. It is possible for messages to be lost with no notification to either sender or receiver. The interface function descriptions refer to data link configuration and maintenance exclusiveness as necessary to indicate differences of operation. The Data Link Interface contains the following functions: . Maintenance-check -- check to see if maintenance service is needed. . Open -- open a port. . Close -- close a port. . Transmit -- send a frame. . Transmit-poll -- check for completion of a Transmit. . Receive -- receive a frame. . Receive-poll -- check for completion of a Receive. . Receive-abort -- abort a Receive. Interfaces Page 15 Maintenance-check Function: Checks the channel to see if maintenance service is needed. Applicable only on exclusive maintenance channels. Inputs: Channel-id - the unique identification of the channel to check. Outputs: Return-code - the status of the request. One of: Running normally - the channel is running or attempting to run normal user traffic. Maintenance needed - the channel wants to run maintenance traffic. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the check can be made. Open Function: Opens a port so that the user can transmit and receive frames. Inputs: Channel-id - the unique identification of the channel on which the port is to be opened. Pad - an indication that the data link is to use its own standard padding technique if padding is necessary. Maintenance operations use this option, when available, for all but the multiaccess channel loop protocol. Id-list - a list of identification data, such as protocol types or multicast addresses, that identify this user of the data link. Data link specific and applicable only on concurrent maintenance channels. For example, in the Ethernet Data Link this abstract id-list function is accomplished using the Ethernet Data Link Open, Enable-protocol, and Enable-multicast functions. Outputs: Return-code - the status of the request. One of: Interfaces Page 16 Success - a port was opened. No resources - the data link does not have sufficient resources to open a port. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where a port can be opened. Port-id - a port identification to be used in the other data link interface functions. Close Function: Closes an open port and releases all its resources. A port cannot be closed unless all outstanding transmit or receive requests are completed. Inputs: Port-id - a port identification assigned by the Open function. Outputs: Return-code - the status of the request. One of: Success - the port is closed. Unrecognized port - there is no open port with the specified identification. Calls outstanding - there are uncompleted transmit or receive requests outstanding on the port. Transmit Function: Queues a frame to be transmitted. The user tests for completion by using Transmit-poll. Transmission of a frame always succeeds or fails within such a small amount of time that an abort function is not necessary. Inputs: Port-id - a port identification assigned by the Open function. Interfaces Page 17 Destination-address - the address of the frame destination. This can be either a physical address or a multicast address. Applicable only on multiaccess channels. Protocol-type - a protocol type to identify the data at the receiving system. Applicable only on concurrent maintenance channels. Input-buffer - a buffer containing the data to be sent. Until the request is completed, the user must not disturb the contents of the buffer. Outputs: Return-code - the status of the request. One of: Request accepted - the data link will attempt to transmit the frame. Notification of completion is via the Transmit-poll function. No resources - the data link does not have sufficient resources to queue a transmit for this port. Unrecognized port - there is no open port with the specified identification. Channel in wrong state - the channel is not in a state where it can send a frame. Transmit-poll Function: Checks for the completion of a transmit request. The data link transmits frames in the order in which the user submits them. Successful completion of this function implies only that the local transmitter believes that it sent the frame. It does not necessarily imply that the destination received it. Inputs: Port-id - a port identification assigned by the Open function. Outputs: Return-code - the transmit request for this port. One of: Not complete - no transmit for this port is done. None outstanding - there are no outstanding transmits for this port. Interfaces Page 18 Transmit successful - a frame successfully left the local transmitter. Transmit failed - the local transmitter could not transmit the frame. Unrecognized port - there is no open port with the specified identification. Channel in wrong state - the channel is not in a state where it can send a frame. Input-buffer - the buffer that was supplied in the Transmit function. Receive Function: Queues a buffer to receive a frame. On multiaccess or concurrent maintenance channels, the receive is filtered according to the id-list established in the Open function. Inputs: Port-id - a port identification assigned by the Open function. Output-buffer - a descriptor of a buffer to contain the received frame. Outputs: Return-code - the status of the request. One of: Request accepted - if a message is received for the specified port, the data link will put it into the buffer. Notification of completion is via the Receive-poll function. No resources - the data link does not have sufficient resources to queue a receive for this port. Unrecognized port - there is no open port with the specified identification. Channel in wrong state - the channel is not in a state where it can receive a frame. Interfaces Page 19 Receive-poll Function: Check for the completion of a receive request. The data link gives received frames to the user in the order in which they arrived. Inputs: Port-id - a port identification assigned by the Open function. Outputs: Return-code - the status of the receive request. One of: Not complete - no outstanding receive for this port is done. None outstanding - there are no outstanding receives for this port. Receive successful - a frame was successfully received into the buffer. Receive with overrun - a frame was successfully received, but had to be truncated to fit into the buffer. Receive aborted - the user cancelled the receive request with the Receive-abort function. Unrecognized port - there is no open port with the specified identification. Channel in wrong state - the channel is not in a state where it can receive a frame. Destination-address - the address to which the received frame was addressed. Applicable only on multiaccess channels. Source-address - the address from which the received frame came. Applicable only on multiaccess channels. Protocol-type - the protocol type from the received frame. Applicable only on concurrent maintenance channels. Output-buffer - the received data. Receive-abort Function: Aborts all outstanding receive requests. The buffers are returned via the Receive-poll function. They may be returned as aborted or Interfaces Page 20 as normally completed. Inputs: Port-id - a port identification assigned by the Open function. Output-buffer - a descriptor of a buffer for a pending receive. Outputs: Return-code - the status of the request. One of: Success - the request is now complete. Unrecognized port - there is no open port with the specified identification. Unrecognized buffer - the specified buffer is not queued for the specified port. User Level Maintenance Operation Interface This section describes the functions available to the maintenance operation user. The descriptions relate each function to its respective component in the maintenance operation model. The functions are divided into three groups: . Dump/Load Functions . Loop Test Functions . Remote Console Functions The Dump/Load Functions are: . Force-load -- load a remote system. . Force-load-poll -- check for completion of a Force-load. . Load-self -- load the local system. . Load-self-poll -- check for completion of a Load-self. . Force-dump -- dump a remote system. . Force-dump-poll -- check for completion of a Force-dump. . Dump-self -- dump the local system. Interfaces Page 21 . Dump-self-poll -- check for completion of a Dump-self. The Loop Test Functions are: . Loop-direct -- loop test direct with another system. . Loop-assisted -- loop test with third-party assistance. . Loop-poll -- check for completion of a loop. . Loop-abort -- abort a loop. The Remote Console Functions are: . Request-poll -- check for remote execution control request. . Identify-self -- send system identification. . Boot -- force remote system to load. . Read-identity -- read remote identity. . Read-identity-poll -- check for completion of a Read-identity. . Read-counters -- read remote data link counters. . Read-counters-poll -- check for completion of a Read-counters. . Reserve-remote-console -- reserve remote system's console. . Release-remote-console -- release remote system's console. * . Send-console-command -- send command message to remote console. * . Console-response-poll -- check for completion of Send-console- command. * . Send-console-response -- send console response data to remote command Console Requester. * . Console-abort -- abort a pending console function. * Requires that the Console Server be reserved. Dump/Load Functions The following functions are performed by either the Dump/Load Requester or the Dump/Load Server. Interfaces Page 22 Force-load Function: Forces a down-line load of the system on the specified channel. This function is a call to the Dump/Load Server. It is a server function rather than a requester function since the server is the component that will actually service the load request that is forced from the target system. The Force-load function queues the request. The user checks for completion with the Force-load-poll function. Inputs: Channel-id - the unique identification of the channel over which the load is to be performed. If not specified, the channel-id from the Dump/Load Data Base is used. Destination-address - the identification of the target system. If not specified but needed, the destination-address from the Dump/Load Data Base is used. Destination-address is needed on multiaccess channels. NOTE Either the channel-id or the destination-address must be included in order to identify the target system. If both are included, the destination-address is used as the data base search key to find other values in the Dump/Load Data Base. Load-file - the identification of the file that is to be down-line loaded into the target system. If not specified, the file identification from the Dump/Load Data Base is used. Secondary-loader - the identification of the file that contains the secondary loader program to use. If not specified but needed, the file identification from the Dump/Load Data Base is used. Tertiary-loader - the identification of the file that contains the tertiary loader program to use. If not specified but needed, the file identification from the Dump/Load Data Base is used. Outputs: Return-code - the status of the request. One of: Request accepted - the load process will be initiated. Notification of completion is via the Force-load-poll function. Interfaces Page 23 No resources - the Dump/Load Server does not have sufficient resources to queue the request. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where a load can be done. Receipt-number - a receipt number to identify this request in the Force-load-poll function. Force-load-poll Function: Checks for completion of a pending Force-load function. This function is a call to the Dump/Load Server. Inputs: Receipt-number - the receipt number assigned by the Force-load function to identify the request. Outputs: Return-code - the status of the request. One of: In process - the load is proceeding. Success - the down-line load completed successfully. Force boot failed - could not force the target system to enter a booting state. Memory load error - the target system reported an error in attempting to deposit part of the load. File open error - could not open one of the files. Invalid file contents - invalid data in one of the files. File I/O error - I/O error reading one of the files. Channel communication error - error in transmit or receive on the channel. Channel protocol error - error in protocol usage by the target system. Unrecognized channel - there is no channel with the specified identification. Interfaces Page 24 Unrecognized target - the Dump/Load Data Base was needed but did not contain an entry for the specified target. Channel in wrong state - the channel is not in a state where a load operation can be done. File-indicator - the indication of which file a file error relates to. Not meaningful for non-file related errors. One of: Load file Secondary loader Tertiary loader Load-self Function: Requests a down-line load of the local system. This is the communications channel equivalent of a system loading itself from local mass storage. Note that only one self-load can be in progress at a time. If a second request is made before a previous one completes, the new request simply replaces the old one. This function is a call to the Dump/Load Requester. Inputs: Channel-id - the unique identification of the channel on which the load is to be done. Destination-address - the identification of the system that is to assist in the load. Applicable only on multiaccess channels. If the address is applicable but not specified, the load will be taken from whatever system is able to help (for further details, see operation section). System-processor - the processor type of the local system. If not specified, the assisting system must assume a type. Defined types are in Appendix A. Software-id - the type of software desired. If not specified, the assisting system must assume a type. Other-info - further, implementation-specific information. Zero or more other-info parameters may be included, each consisting of: Parameter-id - identification of the parameter. Identifications are related to the standard parameters (e.g. communications-processor, system-bus) on an implementation-specific basis. Parameter-value - the value of the parameter. Interfaces Page 25 Outputs: Return-code - the status of the request. One of: Request accepted - the load process will be initiated. Notification of completion is via the Load-self-poll function. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where a load can be done. Load-self-poll Function: Checks for completion of the pending Load-self function. This function is a call to the Dump/Load Requester. Inputs: None. Outputs: Return-code - the status of the request. One of: Requesting - the load is being requested. In process - the load is proceeding. Successful - the load completed successfully. Failure - the load failed. Start-address - on successful load completion, the starting memory address of the loaded image. Local-address - the network address that the local system is to use. Not returned if not received. Local-name - the network name that the local system is to use. Not returned if not received. Host-address - the network address of the host that this system is to use. Not returned if not received. Host-name - the network name of the host that this system is to use. Not returned if not received. Host-date-time - the date and time at the host system. Not returned if not received. Interfaces Page 26 Force-dump Function: Forces an up-line dump of the system on the specified channel. This function is a call to the Dump/Load Server. It is a server function rather than a requester function since the server is the component that will actually dump the target system. The Force-dump function queues the request. The user checks for completion with the Force-dump-poll function. Inputs: Channel-id - the unique identification of the channel over which the dump is to be performed. If not specified, the channel-id from the Dump/Load Data Base is used. Destination-address - the identification of the target system. If not specified but needed, the destination-address from the Dump/Load Data Base is used. Destination-address is needed on multiaccess channels. NOTE Either the channel-id or the destination-address must be included in order to identify the target system. If both are included, the destination-address is used as the data base search key to find other values in the Dump/Load Data Base. Dump-file - the identification of the file that is to be up-line dumped into on the target system. If not specified, the file identification from the Dump/Load Data Base is used. Dump-address - the memory address in the target system to begin dumping from. If not specified and not obtainable from the target, the value from the Dump/Load Data Base is used. Dump-count - the number of memory units to dump. Memory units are whatever is customary for the processor type: usually, but not necessarily, eight-bit bytes. If not specified, and not obtainable from the target, the value from the Dump/Load Data Base is used. Outputs: Return-code - the status of the request. One of: Request accepted - the dump process will be initiated. Notification of completion is via the Force-dump-poll function. Interfaces Page 27 No resources - the Dump/Load Server does not have sufficient resources to queue the request. Unrecognized destination - there is no destination with the specified identification. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where a dump can be done. Receipt-number - a receipt number to identify this request in the Force-dump-poll function. Force-dump-poll Function: Checks for completion of a Force-dump function. Inputs: Receipt-number - the receipt number assigned by the Force-dump function to identify the request. Outputs: Return-code - the status of the request. One of: In process - the dump is proceeding. Success - the up-line dump completed successfully. Remote dump failed - could not force the target system to cooperate. The higher level may be able to remedy this with a Force-load. Memory read error - the target system reported an error in reading memory. File open error - could not open the dump file. Invalid file contents - invalid data in the dump file. File I/O error - I/O error reading or writing the dump file. Channel communication error - error in transmit or receive on the channel. Channel protocol error - error in protocol usage by the target system. Interfaces Page 28 Unrecognized channel - there is no channel with the specified identification. Unrecognized target - the Dump/Load Data Base was needed, but did not contain an entry for the specified target. Channel in wrong state - the channel is not in a state where a dump operation can be done. Dump-self Function: Requests an up-line dump of the local system. This is the communications channel equivalent of a system dumping itself to local mass storage. Note that only one self-dump can be in progress at a time. If a second request is made before a previous one completes, the new request simply replaces the old one. This function is a call to the Dump/Load Requester. Inputs: Channel-id - the unique identification of the channel on which the dump is to be done. Destination-address - the identification of the system that is to assist in the dump. Applicable only on multiaccess channels. If applicable but not specified, the dump will go to whatever system is able to help. Dump-address - the address in local memory at which the dump is to begin. If not specified, the assisting system must assume an address. Dump-count - the number of memory units to dump. Memory units are whatever is customary for the processor type; usually, but not necessarily, eight bit bytes. If not specified, the assisting system must assume a count. System-processor - the processor type of the local system. If not specified, the assisting system must assume a type. Defined types are in Appendix A. Software-id - the type of software that was running. If not specified, the assisting system must assume a type. Defined types are in Appendix A. Other-info - further, implementation-specific information. Zero or more other-info parameters may be included, each consisting of: Parameter-id - identification of the parameter. Identifications are related to the standard parameters (e.g. communications-processor, system-bus) on an Interfaces Page 29 implementation-specific basis. Parameter-value - the value of the parameter. Outputs: Return-code - the status of the request. One of: Request accepted - the dump process will be initiated. Notification of completion is via the Dump-self-poll function. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where a dump can be done. Dump-self-poll Function: Checks for completion of the pending Dump-self function. This function is a call to the Dump/Load Requester. Inputs: None. Outputs: Return-code - the status of the request. One of: Requesting - the dump is being requested. In process - the dump is proceeding. Successful - the dump completed successfully. Failure - the dump failed. Loop Test Functions The specific goals in the design of the Loop Test functions are: . Provide for all forms of loop test that are necessary to diagnose a system's ability to communicate. . Allow each system to assume the responsibility to diagnose its own ability to communicate. Interfaces Page 30 . For multiaccess channels, allow a network management system to diagnose some other system's ability to communicate. . Minimize processing and memory requirements, particularly in systems other than the requesting system. The realization of these goals is different for multiaccess channels and point-to-point channels, since multiaccess channels have a broader communication ability. On a point-to-point channel, a system using the Loop Test functions on its own behalf and having all of them available can ascertain its ability to communicate with the system on the other end of the channel. For multiaccess channels, the Loop Test functions are modeled after the Ethernet standard. See Appendix E or the Ethernet Specification, Version 2.0, for a detailed description. Some multiaccess channels may support the concept of a generic loopback assistant. These are systems that are willing to assist in some forms of multiaccess loopback testing. The following descriptions refer to these systems as the loopback assistant multicast group. The amount of the Loop Test interface that is implemented can cover the full range from none at all to full capability. However, those systems that do not provide the full interface capability proportionately limit their capacity for self diagnosis and become more dependent on some centralized test facility. The following functions are all calls to the Loop Requester. Loop-direct Function: Determine if direct communication with a remote system is possible. Inputs: Channel-id - the unique identification of the channel on which the loop is to be done. Destination-address - the identification of the system that is to be looped to. Applicable only on multiaccess channels. If applicable and not included, the loopback assistant group multicast address is used. Interfaces Page 31 Input-buffer - a buffer containing the data to be looped. Output-buffer - a buffer to contain the looped back data. If not present, the looped back data is not returned to the user. Outputs: Return-code - the status of the request. One of: Request accepted - the loop will be attempted. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is in a state where a loop cannot be done. Receipt-number - the request identification used in the Loop-poll or Loop-abort function to identify this request. Loop-assisted Function: Determine if some other system can communicate with the specified remote system. Applicable only on multiaccess channels. Inputs: Channel-id - the unique identification of the channel on which the loop is to be done. Destination-address - the identification of the system that is to be looped to. The destination-address cannot be a multicast address. Assistant-address - the identification of the third party system to assist in the test. The address cannot be a multicast address. Assistance-level - the amount of assistance desired: transmit - the assistant station is only to relay the request, the request is to be returned from the destination system. receive - the assistant station is only to relay the reply, the request is to be sent to the destination station. full - the assistant station is to relay both request and reply. Input-buffer - a buffer containing the data to be looped. Interfaces Page 32 Output-buffer - a buffer to contain the looped back data. If not present, the looped back data is not returned to the user. Outputs: Return-code - the status of the request. One of: Request accepted - the loop will be attempted. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is in a state where a loop cannot be done. Receipt-number - the request identification used in the Loop-poll or Loop-abort function to identify this request. Loop-poll Function: Used to poll for completion of a Loop-direct or Loop-assisted. Inputs: Receipt-number - the request identification assigned to this request by the Loop function. Outputs: Return-code - the status of the operation. One of: Not complete - the loop is not yet done. Success - the data came back correctly. Aborted - the request was aborted with a Loop-abort. Compare error - the data came back, but it did not match what was sent. Transmit failed - the local transmitter could not send the initial message. Channel communication error - no response was received. Either the initial message or the response did not arrive. Responding-address - the identification of the remote system that satisfied the request. Applicable only on multicast channels. For Loop-assisted with transmit assistance, this is the remote system address. For Loop-assisted with receive or full assistance, it is the assistant system address. Interfaces Page 33 Output-buffer - the looped back data received, whether correct or not. Present only if the buffer was furnished on the Loop call. Loop-abort Function: Used to abort a Loop-direct or Loop-assisted, for example if the user decides that the reply has taken too long. Inputs: Receipt-number - the request identification assigned to this request by the Loop-direct or Loop-assisted function. Outputs: none. Remote Console Functions There is an aspect of the Console Server operational model that affects the user interface in a way that must be explained here. This is the relationship between data access functions and control functions. Data access Read-identity). The model assumes that the Console Server has necessary access abilities without higher level involvement. Control execution of a processor (for example, Boot). The model assumes that the Console Server cannot do this directly. The higher level must therefore poll the Console Server for this type of request and the information needed to honor it. Most of the remote console functions are calls to the Console Requester. Console Requester operations are of two types, those that require exclusive access to the remote console and those that do not. Unless otherwise noted, the following functions are calls to the Console Requester. Request-poll Function: Checks to see if certain remote requests have been made. These are requests that directly modify local system processor Interfaces Page 34 execution. Remote requests are not queued: only the most recent is available. Each remote request can be read only once. The higher level process is responsible for polling often enough to ensure a minimum number of lost requests. This is a call to the Console Server. Inputs: Channel-id - the unique identification of the channel on which to check for remote requests. Outputs: Return-code - the status of the request. One of: No requests - no remote requests have been received. Request read - a remote request has been returned. Request truncated - a console command request has been received; however all of the command data was lost. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the request can be received. Request-type - the type of request made by the remote system. One of: Boot Console command Boot-server - for a boot request, an indication of the server system to be used to honor the request. One of: Default-server - the system that this system would normally use. Command-source - the system involved in this request. Boot-device - for a boot request, an indication of the device this system is to use to honor the request. One of: Default-device - the device that this system would normally use. Specified-device - the device specified by the command source. Device-id - for specified-device, identification of the device to boot from. Interfaces Page 35 Verification-code - for a boot request, the 4 or 8 byte verification code sent by the requesting system. Source-address - the identification of the system that sent the request. Applicable only on multiaccess channels. Command-data-buffer - for a console command, the buffer containing the command message. Command-break-flag - for a console command, indicates when a break condition is to precede the command message to the console. Identify-self Function: Causes a system identification message to be sent. This is a call to the Console Server. Inputs: Channel-id - the unique identification of the channel on which to send the identity. Destination-address - the identification of the destination system. Applicable only to multiaccess channels. If applicable and not present, the identity message will be sent to the remote console multicast group. Outputs: Return-code - the status of the request. One of: Success - identity sent. Transmit failed - the data link failed to send the message. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the request can be received. Boot Function: Force the remote processor to initialize itself. This may cause the system to reload its system image either locally or remotely. Interfaces Page 36 Inputs: Channel-id - the unique identification of the channel on which to send the boot command. Destination-address - the identification of the destination system. Applicable only to multiaccess channels. Verification code - a code to send to the remote system so it will honor the request. The code can be either 4 or 8 bytes long. If it is 4 bytes, no additional parameters can be sent. If additional parameters are to be sent, the code must be 8 bytes long. Boot-server - for a boot request, an indication of the server system to be used to honor the request. One of: Default-server - the system that this system would normally use. Command-source - the system involved in this request. Boot-device - for a boot request, an indication of the device this system is to use to honor the request. One of: Default-device - the device that this system would normally use. Specified-device - the device specified by the command source. Device-id - for specified-device, identification of the device to boot from. Software-id - the software that the remote system is to load. Outputs: Return-code - the status of the request. One of: Success - request sent. Transmit failed - the local transmitter could not transmit the request. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the boot can be done. Interfaces Page 37 Read-identity Function: Reads the identity of the specified system. Inputs: Channel-id - the unique identification of the channel on which to read the identity. Destination-address - the identification of the destination system. Applicable only to multiaccess channels. Outputs: Receipt-number - the receipt number used in the Console-abort or Read-identity-poll functions to identify this request. Read-identity-poll Function: Polls for completion of a Read-identity function. Inputs: Receipt-number - the request identification assigned to this request by the Read-identity function. Outputs: Return-code - the status of the request. One of: Not complete - the operation is still in process. Success - identity read. Transmit failed - the local transmitter could not transmit the request. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the read can be done. Maintenance-version - the version number of the Low Level Maintenance Operations Architecture that the system is using. Functions - a list of flags indicating whether or not various maintenance functions are currently supported on the system. The possible functions are: Interfaces Page 38 Loop Dump Primary loader (can only load secondary loader) Multi-block loader (can load tertiary loader or system) Boot Console carrier Data link counters Console carrier reservation Console-user - the identification of the system that has the remote console reserved. Not returned if not received. Reservation-timer - the maximum number of seconds that are allowed with no remote console requests before the reservation expires. Not returned if not received. Console-command-size - the maximum allowable size of a console command message. Not returned if not received. Console-response-size - the maximum allowable size of a console response message. Not returned if not received. Hardware-address - the unique hardware address of the remote system. This may or may not be the address in use to identify the system. Not returned if not received. Communication-device - the device type of the communication subsystem over which the remote system received the request. Not returned if not received. Defined types are in Appendix A. Software-id - the type of software running in the remote system. Not returned if not received. Defined types are in Appendix A. System-processor - the processor type of the remote system. Not returned if not received. Defined types are in Appendix A. Data-link-type - the data link mechanism over which the remote system received the request. Not returned if not received. Defined types are in Appendix A. Data-link-buffer-size - the size of the data link buffer, which determines the maximum size MOP message that the station can accept. It includes all except the DDCMP header. The default value is 262 (256 plus the current MOP header size). A server may ignore this field, so that all requesters must support 262 byte messages. Not returned if not received. Other-info - further, implementation-specific information. Zero or more other-info parameters may be included, each consisting of: Parameter-id - identification of the parameter. Identifications are related to the standard parameters (e.g., communication-device, system-processor) on an implementation- specific basis. Interfaces Page 39 Parameter-value - the value of the parameter. Read-counters Function: Reads the data link counters from the specified system. Inputs: Channel-id - the unique identification of the channel on which to read the counters. Destination-address - the identification of the destination system. Applicable only to multiaccess channels. Outputs: Receipt-number - the receipt number used in the Console-abort or Read-counters-poll functions to identify this request. Read-counters-poll Function: Polls for completion of a Read-counters function. Inputs: Receipt-number - the request identification assigned to this request by the Read-counters function. Outputs: Return-code - the status of the request. One of: Not complete - the operation is still in process. Success - counters read. Transmit failed - the local transmitter could not transmit the request. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the read can be done. Interfaces Page 40 Counters - a block of counter information as defined for the particular data link (see Appendix B). Reserve-remote-console Function: Reserves the remote system console for use by this system. This must be done before the console carrier can be used. The remote console stays reserved as long as this system makes any console request before the remote system's reservation timer expires. If the remote console reservation timer expires, this system's console reservation is lost without notification. Reservation of a remote console allocates and initializes a collection of local resources, known as a port. Those console functions that require a reservation are requested via the port identification. Initialization of the port allows the command node to synchronize the command and response data streams with the target node's Console Server. In cases where a remote system console can be accessed over more than one communication channel, it is the responsibility of that system and the user of the remote console to ensure that there are no conflicts of control. Inputs: Channel-id - the unique identification of the channel on which to reserve the remote system console. Destination-address - the identification of the destination system. Applicable only to multiaccess channels. Verification code - a code to send to the remote system so it will honor the request. Outputs: Return-code - the status of the request. One of: Success - request sent. No resources - this system has insufficient resources to assign a port for remote console requests. Transmit failed - the local transmitter could not transmit the request. Unrecognized channel - there is no channel with the specified identification. Interfaces Page 41 Channel in wrong state - the channel is not in a state where the reservation can be made. Port-id - a port identification to be used in the other Remote Console Interface functions that require a reservation. Release-remote-console Function: Releases this system's access to the remote system console. This provides an optimization over allowing the remote system's reservation timer to expire and deallocates the local port resources. Note that even though a message cannot be sent to the remote system, the local resources will still be released. In other words, from the standpoint of the local system, this function does not fail. Inputs: Port-id - a port identification assigned by the Reserve-remote-console function. Outputs: Return-code - the status of the request. One of: Success - request sent. Transmit failed - the local transmitter could not transmit the request. Unrecognized port - there is no open port with the specified identification. Channel in wrong state - the channel is not in a state where a transmit can be done. Send-console-command Function: Sends console command data and polls the Console Server of the target system. This function is used with no command data to achieve a poll of the target system without sending a command. Inputs: Interfaces Page 42 Port-id - a port identification assigned by the Reserve-remote- console function. Command-break-flag - a logical value, where true indicates that the data in the command-data-buffer is to be preceeded by a break condition in the serial byte stream. This is for target system console implementations with an RS232-C type interface. Command-data-buffer - a buffer containing command data to be sent to the remote system. This must not be larger than the maximum size command the remote system can receive, as indicated through the Read-identity function. Response-data-buffer - a buffer to receive data from the remote system. This must be at least as large as the maximum size response the remote system can send, as indicated through the Read-identity-poll function. Outputs: Return-code - the status of the request. One of: Success - console command accepted for transmission. Unrecognized port - there is no open port with the specified identification. Function denied - a previous Send-console-command function was still pending. Invalid buffer size - the command buffer is larger than the target Server allows, or the response buffer is smaller than the target Server allows. Receipt-number - the request identification used in the Console- abort or Console-response-poll functions to identify this request. Console-response-poll Function: Polls for completion of the Send-console-command function. Inputs: Receipt-number - the request identification assigned to the Send- console-command function. Outputs: Return-code - the status of the request. One of: Interfaces Page 43 Pending - the exchange is not yet complete. Success - console data sent and acknowledged. Data lost - success, but data was lost during the exchange. Transmit failed - the local transmitter could not transmit the request. command-data-buffer - the buffer which contained the command sent to the remote system. Invalid if pending status is returned. Response-data-buffer - the buffer with the received response data from the remote system. Invalid if pending status is returned. Data-lost-flags - indicators as to the type and reason for the Data lost return-code. Present only if Data lost code returned. Any of: Command-data-lost - a logical value that is true if the command data in the Console Command And Poll message was lost. Response-data-lost - a logical value that is true if the remote console server detected lost console data due to a buffer overrun or other error condition. The data in the response-data-buffer is possibly incomplete. Receive-data-lost - a logical value that is true if the receive-data-buffer was too small to receive all of the data that was sent. Send-console-response Function: Causes a console response to be sent to the Console Requester of the remote command system. This is a call to the Console Server of the target system. It is used to respond to remote console requests from the console user. Inputs: Channel-id - the unique identification of the channel on which the response is to be made. Destination-address - the identification of the command system. Applicable only to multiaccess channels. If applicable and not present, the console-user address is implied. Command-data-lost-flag - a logical value that is true if the command data in the received console command was lost. Interfaces Page 44 Response-data-lost-flag - a logical value that is true if there was a loss of data in the console response. This is provided for implementations where the user of the Console Server cannot block the source of the console output data stream. Response-data-buffer - a buffer containing data to be sent to the remote system. This must not be larger than the maximum response buffer size in the local system id. Outputs: Return-code - the status of the request. One of: Success - console response data sent. Invalid buffer size - the buffer is larger than the server allows. Function denied - a previous send-console-response request is still active. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in the reserved state or the console carrier protocol has not been enabled. Invalid destination-address - the supplied destination-address does not match the console-user address in the local system ID. Transmit failed - the local transmitter could not transmit the request. Console-abort Function: Aborts a pending console request. Console-abort only affects an individual request and does not cause any change in console state. Inputs: Receipt-number - the number assigned to the request. The following requests can be aborted: . Read-identity . Read-counters . Send-console-command Interfaces Page 45 Outputs: None. Network Management Interface This section defines the control and observation functions for the maintenance operations. The Network Management Interface functions are: . Set-state -- enable or disable local maintenance function. . Read-state -- read states of switchable functions. . Add-dump/load-entry -- add a new entry to the Dump/Load Data Base. . Remove-dump/load-entry -- Remove an entry from the Dump/Load Data Base. . Set-dump/load-parameter -- set a dump/load parameter. . Read-dump/load-list -- read the list of dump/load entries. . Read-dump/load-parameter -- read dump/load parameters. . Set-console-parameter -- set a local console parameter. . Read-console-parameter -- read a local console parameter. Set-state Function: Enables or disables various local maintenance operation functions or components. Inputs: Channel-id - the unique identification of the channel for which the function state is to be switched. Function - the function whose state is to be switched. One of: Console Server - controls whether the Console Server will respond to any incoming requests. Dump/Load Server - controls whether the Dump/Load Server will respond to any incoming requests. Interfaces Page 46 Dump/Load assistance - controls whether the Dump/Load Server will respond to dump or load requests to the dump/load assistance multicast group. Loop Server - controls whether the Loop Server will respond to any incoming requests. Loop assistance - controls whether the Loop Server will respond to loop requests to the loopback assistance multicast group. Remote console reservation - controls whether any remote system is allowed to reserve the local console. State - the state that the function is to be switched to. One of: On - the function is allowed to operate. Off - the function is not allowed to operate. Outputs: Return-code - the status of the request. One of: Success - state switched. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where a switch can be done. Read-state Function: Reads the states of the switchable local maintenance functions. All of the states are either on or off as described for the Set-state function. Inputs: Channel-id - the unique identification of the channel to read the states for. Outputs: Return-code - the status of the request. One of: Success - states read. Interfaces Page 47 Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the read can be done. Console-state - the state of the Console Server. Dump/load-state - the state of the Dump/Load Server. Loop-state - the state of the Loop Server. Loop-assistance-state - the state of loop assistance. Remote-console-reservation-state - the state of remote console reservations. Add-dump/load-entry Function: Adds an entry to the Dump/Load Data Base. Inputs: Channel-id - the unique identification of the channel that identifies the data base entry. Destination-address - the identification of the target system that identifies the data base entry. NOTE Either the channel-id or the destination-address must be included in order to identify the target system. If both are included, the destination- address is used as the data base search key to find the entry in the Dump/Load Data Base. Outputs: Return-code - the status of the request. One of: Success - entry added. Already defined - the Dump/Load Data Base already contains an entry for the specified target. Interfaces Page 48 Remove-dump/load-entry Function: Removes an entry from the Dump/Load Data Base. Inputs: Channel-id - the unique identification of the channel that identifies the data base entry. Destination-address - the identification of the target system that identifies the data base entry. NOTE Either the channel-id or the destination-address must be included in order to identify the target system. If both are included, the destination- address is used as the data base search key to find the entry in the Dump/Load Data Base. Outputs: Return-code - the status of the request. One of: Success - entry removed. Unrecognized target - the Dump/Load Data Base does not contain an entry for the specified target. Set-dump/load-parameter Function: Stores parameter values into the Dump/Load Data Base. Inputs: Channel-id - the unique identification of the channel that identifies the data base entry. Destination-address - the identification of the target system that identifies the data base entry. NOTE Either the channel-id or the destination-address must be included in order to identify the target system. If both are included, the destination- address is used as the data base search key to find other values in the Dump/Load Data Base. Interfaces Page 49 Parameter-type - the particular parameter to set. One of: Load-file Secondary-loader Tertiary-loader Dump-file Secondary-dumper Dump-address Dump-count Parameter-value - the new value of the parameter specified by parameter-type. Outputs: Return-code - the status of the request. One of: Success - parameter set. Unrecognized target - the Dump/Load Data Base does not contain an entry for the specified target. Read-dump/load-list Function: Reads the list of Dump/Load Data Base entries. Inputs: Buffer - descriptor of a buffer to contain the list. Outputs: Return-code - the status of the request. One of: Success - parameters read. Buffer too small - the buffer could not hold all the entries. Those that would not fit are not returned. Buffer - descriptor of buffer containing the list. Each entry consists of destination-address or channel-id if the destination address is not set. Read-dump/load-parameters Function: Reads the Dump/Load Data Base entry for a channel. Interfaces Page 50 Inputs: Channel-id - the unique identification of the channel that identifies the data base entry. Destination-address - the identification of the target system that identifies the data base entry. NOTE Either the channel-id or the destination-address must be included in order to identify the target system. If both are included, the destination- address is used as the data base search key to find other values in the Dump/Load Data Base. Outputs: Return-code - the status of the request. One of: Success - parameters read. Unrecognized target - the Dump/Load Data Base does not contain an entry for the specified target. Parameter-entries - the parameters that are set. Each parameter entry consists of a parameter-type and a parameter-value as described for the Set-dump/load-parameter function. Set-console-parameter Function: Stores parameter values to be used by the remote console server. The User Layer is the source of the values. It may obtain them, for example, through physical switch settings or terminal interaction with a person. Inputs: Channel-id - the unique identification of the channel for which the values are to be changed. Parameter-type - the particular parameter to set. The parameters are described for the Read-identity-poll function. They are: Maintenance-version Functions Reservation-timer Console-command-size Console-response-size Hardware-address Communication-device Interfaces Page 51 Software-id System-processor Data-link-type Other-info (in the form of an other-info parameter-type) Parameter-value - the new value of the parameter specified by parameter-type. Outputs: Return-code - the status of the request. One of: Success - parameter set. Unrecognized channel - there is no channel with the specified identification. Channel in wrong state - the channel is not in a state where the parameter can be stored. Read-console-parameters Function: Reads the console parameters for a channel. Inputs: Channel-id - the unique identification of the channel for which the parameters are to be read. Outputs: Return-code - the status of the request. One of: Success - parameters read. Unrecognized channel - there is no channel with the specified identification. Parameter-entries - the console parameters that are set. Each parameter entry consists of a parameter-type and a parameter-value as described for the Set-console-parameter function. Interface Usage Examples This section contains examples of how the maintenance functions might be used. The examples are not exhaustive and do not restrict the way the functions might be used. Interfaces Page 52 For examples of multicast Loop Test, see Appendix E or the Ethernet Specification, Version 2.0. A System Boot Monitor In this example, a system can be booted by remote command, can decide locally to reboot itself, or can decide it is thoroughly broken and needs expert help. The process responsible for all this is in the User Layer and uses the low level maintenance interface functions. The monitor process is implemented so that it is a highly reliable process. Even if nothing else in the system works, this process has a high probability of running. The monitor process watches for remote boot commands through the Request-poll function. If a boot request is received, it checks the verification code, and if the code is acceptable, the monitor process halts all other processing in the system and calls the Load-self function, requesting normal operating software. The monitor then goes into load polling as described below. On a locally determined timer, the monitor process checks over system operation. If it finds that operation is not proceeding properly, it halts all other processing and calls the Load-self function, requesting diagnostics rather than normal operating software. The monitor then goes into load polling. When the monitor has a Load-self outstanding, it does two things. It continues to watch for remote boot commands through Request-poll. It polls for completion of the Load-self with Load-self-poll. If the load fails or takes too long ("too long" is locally defined), the monitor enables reservation of its console with the Set-state function and periodically does an Identify-self on a timer preset according to system needs and communication speed. If the channel being used is a multiaccess channel, the Identify-self goes to the remote console multicast group. A remote monitor can then assist the system as necessary. A Minimal ASCII Console Carrier A very simple console carrier mechanism can be implemented to process only one transmit and one receive character at a time. This is suitable for systems that have already implemented an ASCII console. This requires a minimum of resources, yet provides a highly reliable connection. Data will be lost only if the connected processes try to "pump" data at a rate greater than the connection can accommodate, at which point overrun errors will occur. The local (command) system initiates a console connection by calling the Reserve-remote-console function, identifying the remote (target) system. It then issues a Read-identity call to the target and waits Interfaces Page 53 for a response from the target by using the Read-identity-poll function. If the target has not reserved the console or a timer expires, the process is repeated. The target system's console server must be able to process the console reservation from the host system and will open its console to the host system if all the necessary conditions are met. Once the console is reserved, the user process in the target system, i.e., that system's console processor, must be periodically polling the Console Server for console commands using the Request-poll function. When both systems are ready to communicate, the command system has the responsibility both to transmit commands and poll for responses from the target system. The target system has to respond to console command and poll messages and maintain the console reservation timer. When the command system has data to send, it calls the Send-console- command function, then waits for the response by periodically calling the Console-response-poll function. If a failure is observed, the command system makes any necessary corrections and reissues the Send- console-command. This process is repeated until all pending command data has been sent and acknowledged. If data was returned with the final acknowledgment, it is processed and another Send-console-command call is made to "flush" the remote console response buffer. Even when there is no data to send or being returned, the command system still must periodically call the Send-console-command function to keep the reservation alive and to receive possible unsolicited "response" data from the remote console. If the command system does not receive a response to a Send-console-command within a specified "no response time," then it calls the Console-abort function and issues a Request- identity to try to ascertain the state of the target system and the reason for its failure to respond. At the other end, the target system's user process must periodically call the Request-poll function. When the user process receives a console command it must process it and acknowledge it by calling the Send-console-response function. At either end, data overrun is blocked by the Console Responder or Server returning an error status code to the user if the previous message has not been acknowledged. Unblocking of a data stream that may have experienced some kind of prolonged discontinuity is achieved by the command system detecting the error condition, releasing and then re-reserving the target console. This will force the target system to reinitialize its Console Server and, hopefully, unblock the data stream. Operation Page 54 OPERATION This section describes the operation that supports the various interfaces. The operation is described in terms of the model section and uses an Algol-like colloquial, high-level language for specification of algorithms. For this version of the specification, operation is not presented in the form of a complete implementation model. Instead, to allow quicker review, and since the protocols are quite simple, descriptions are in English or simplified algorithmic form. The descriptions assume, for example, that transmits and receives will be properly demultiplexed between the Data Link Layer and the simplified processes presented here. They also assume that Data Link Open and Close functions are performed outside themselves. Operation and message formats are, as much as possible, drawn from the existing Maintenance Operation Protocol (MOP) Version 2.1. This means that some algorithms, such as down-line load, are directly drawn from existing products with proven field records. Common Algorithms In all maintenance protocols, an invalid message is treated as if it never arrived or had data errors. Many of the maintenance algorithms require timeout and retransmission of a message when a response is not received. There are two variations of this algorithm. The first is persistent. It will not terminate unless stopped by a hard error or high level intervention. The second terminates when a fixed retry count is exhausted. In the higher level algorithms they are referred to as Must-transact, message for the persistent variety, and Transact, message for the fixed retry variety. Message is the message that is to be sent. A receive buffer, and other outputs of the call, are assumed to avoid obscuring the important algorithms. These algorithms also assume synchronous transmit and receive functions, with a receive timeout calculated according to channel speed and size of receive buffer plus 1 second for remote response time. These algorithms result in either a transmit or receive error or a message received in response to the message transmitted. The algorithms assume that the data link has a service-timer and a suggested maximum-retries for maintenance operation. Control of these parameters is outside the scope of this specification. Operation Page 55 The Must-transact algorithm is: Set no intervention, no error, and no message received. WHILE no intervention AND no error AND no message received. Transmit message. IF successful transmit: Receive message. CASE return-status Receive successful: Set message received. Receive aborted: Set intervention. ENDCASE ELSE IF fatal transmit error: Set error. ENDIF ENDIF ENDWHILE The Transact algorithm is: Set retry counter to 0, no error, and no message received. WHILE no error and no message received. Transmit message. IF successful transmit: Receive message. IF successful receive: Set message received. ELSE IF receive timed out: IF retry counter <= maximum-retries: Increment retry counter. ELSE Set channel communication error. ENDIF ELSE Set error from Receive. ENDIF ENDIF ELSE Set error from Transmit. ENDIF ENDWHILE Dump/Load This section describes the operation of the Dump/Load Server and Requester. In this section the term "target system" describes the system being dumped or loaded (i.e. the one running the Dump/Load Requester). The term "assisting system" describes the system that is providing file services (i.e. the one running the Dump/Load Server). Operation Page 56 NOTE See Appendix C for implementation specific Dump/Load information. Dump/Load Server The Dump/Load Server is by far more complex than the Dump/Load Requester. This is because the Dump/Load Requester is designed to run in systems with minimal resources available. Functions are therefore shifted as much as is practical or possible into the Server. The description of Dump/Load Server operation is divided into two major sections, dump and load. Both sections use the Remote Console to force dump or load cooperation from the target system. This usage is presented in a simplified form that assumes an algorithm similar to that described for the Transact function, where: . Transmit message becomes a request for the required console operation (Boot or Dump). . Receive message becomes a check for the required response (a request program for Boot; a request dump service for Dump). Assistance Volunteer This function is only applicable on multiaccess channels. It requires the following messages: . Request dump service. Sent by a target system to request assistance as a result of a Dump-self function. May contain considerable information as to system configuration as described in the Dump-self function. . Request program. Sent by a target system to request assistance as a result of Load-self function. May contain considerable information as to system configuration as described in the Load-self function. . Assistance volunteer. Sent by a potential assisting system in response to a request dump service or request program message. This function is performed in Dump/Load Servers on systems that are part of a dump/load assistance multicast group. It is performed when a request program or request dump service message is received not the request is for a secondary loader. In that case, a server that Operation Page 57 can do so simply responds with the secondary program rather than volunteering assistance, and maintains no further state relative to the request. The Server determines its ability to assist by checking for the presence of the necessary information, either in the request or in its own Dump/Load Data Base. If it can assist, and the request was not for a secondary loader, it replies with a single transmission of an assistance volunteer message. It maintains no state to recall that any of this has been done, as it may not be selected by the target to be the assistant. Dump Operation Dump operation requires the following messages: . Request dump service. Sent by a target system as a result of a Dump-self function. Says that the system requires assistance in dumping itself. May contain considerable information as to system configuration as described in the Dump-self function. . Request memory dump. Sent by an assisting system to obtain a segment of memory. . Memory dump data. Contains a segment of memory sent by a target system in response to a request memory dump message. . Dump complete. Sent by the assisting system to indicate that the dump is done. The dump algorithm is: Perform dump. IF failure on first message: Use Remote Console to force dump. IF successful: Perform dump. ELSE Set error. ENDIF ENDIF Operation Page 58 The algorithm for a dump server is: Open output file. WHILE no error and more to dump Transact, request memory dump. IF no error: IF message received is memory dump data: Write segment to file. Update memory address to dump from. ELSE Set channel protocol error. ENDIF ENDIF ENDWHILE IF no error: Complete file as necessary. ENDIF Transmit, dump complete. Close output file. Load Operation Load operation requires the following messages: . Request program. Sent by a target system as a result of a Load-self function. Says that the system requires assistance in loading itself. May contain considerable information as to system configuration as described in the Load-self function. Also indicates whether the request is for an intermediate loader or for the final program (the "operating system"). . Memory load with transfer address. Sent by an assisting system to load a secondary loader program. Sent in response to a program request message for a secondary loader or as the last load of a tertiary loader. . Request memory load. Sent by a target system in response to a memory load message. Indicates whether or not the memory was successfully loaded and requests another segment. . Memory load. Contains a segment of memory to load. Sent by an assisting system in response to a program request message for a tertiary loader or operating system, or a request memory load message. Operation Page 59 . Parameter load with transfer address. Contains various system parameters and a final transfer memory address. Sent by an assisting system at the end of a multi- segment load. NOTE See Appendix C for special conventions related to existing PDP-11 down-line load programs. The load algorithm is: Perform load with initial program type determined from higher level request or default data base. IF failure on first message: Use Remote Console to boot target system. IF success: Perform load with initial program type from program request. ELSE Set error. ENDIF ENDIF The algorithm to perform a load is: Set no error and operating system not loaded. Set program to load from input of initial program identification. WHILE no error and not done: Open program image file and determine starting address, number of bytes, and transfer address. IF program type = secondary loader: Read entire program from file. Send memory load with transfer address. Set done. ELSE Perform multi-segment program load. Set retry counter to 0. WHILE no error and received message is request memory load and requested segment number in message = load number: IF program type = tertiary loader: Send memory load (empty) with transfer address. ELSE (must be operating system) Send parameter load with transfer address. ENDIF IF no error and received message is request memory load and requested segment number in message = load number and retry counter < maximum-retries: Increment retry counter. ELSE Set channel communication error. ENDIF ENDWHILE ENDIF IF no error: Operation Page 60 IF program type = operating system: IF message received is request memory load and requested segment number in message = load number + 1: Set operating system loaded. ELSE Set channel protocol error. ENDIF ENDIF ENDIF ENDWHILE The algorithm for a multi-segment program load is: Set load segment number to 0. Set requested segment number to 0. WHILE no error and more to load: Read a segment of memory from file. Set retry count to 0. WHILE no error and requested segment = load segment: Transact, memory load message. IF no error: IF request memory load received: Set requested segment number from message. IF requested segment number = load segment number: IF retry count < maximum-retries: Increment retry count. ELSE Set channel communication error. ENDIF ELSE IF requested segment number <> load segment number + 1: Set channel protocol error. ENDIF ENDIF ELSE Set channel protocol error. ENDIF ENDIF ENDWHILE Increment load segment number. ENDWHILE Dump/Load Requester The Dump/Load Requester is as simple as possible in its operation to avoid burdening a small system that needs to dump or load itself with minimal resources available. The operation is described in stages to indicate how a system with minimal resources could approach the functions. A system with the resources to begin at one of the later stages can and should do so, only implementing needed capabilities (such as initial request) from Operation Page 61 earlier stages. Both dump and load operate similarly from the higher level's perspective. They are invoked with a Dump-self or Load-self function and checked for completion with the matching poll function. The poll function returns a state that depends on the progress being made so that the high level can decide to abort and restart or whatever else it deems appropriate. Both dump and load have a special function available on multiaccess channels. This function allows them to select an assistant from the dump/load assistance multicast group. The initial request message is first sent to the multicast address. The first Assistance Volunteer message responder is selected as the assistant and the operation proceeds from there the same as for a point-to-point channel. The initial request is sent via the Must-transact function. During this stage of the operation, the poll function returns a "requesting" state. Dump Operation The first stage is to get the dump started with a Must-transact of a request dump service message. This succeeds when a request memory message is received. During this stage, the poll function returns a "requesting" state. On success, proceed to the next stage. The second stage is the actual dump. During this stage, the poll function returns an "in-process" state. A dump data message is sent in response to each request memory message. A failure on a transmit or a receive terminates the operation with a failure or receipt of any other message. A timeout on a receive or the receipt of a dump complete message terminates the operation with success. Load Operation The first stage is to load a secondary loader program with a Transact of a request program. This succeeds when a memory load with transfer address is received and started. The message must contain an entire secondary loader. Note that a primary loader accepts only a secondary loader; it does not use the assistance volunteer function. The second stage is to load a tertiary loader program. The first segment is obtained with a Must-transact of a request program message. Subsequent segments are obtained with a simple transmit of a request memory load message. The request memory message is used to acknowledge the successful or failing storage of the previous memory segment and either requests the same one again or the next one. The load is completed by receipt of a memory load with transfer address. The program loaded must be a tertiary loader. Operation Page 62 The third stage is to load the "operating system". This could actually be any type of program. The load procedure is the same as for the tertiary loader, except that the final message is a transfer address and parameters. The transfer address and parameters are passed up to the higher level with the notification of successful completion. Also, the final message is acknowledged with a request memory for the next segment, which the assistant understands as an acknowledgement rather than a request. During the second and third stages, the Dump/Load Requester keeps a timer while waiting for a message from the assistant. If this timer runs out, the Dump/Load Requester declares the load as failed with a "failed" error return. This timer is set according to the service- timer for the particular data link. Also during the second and third stages, the loaders must not accept a Memory Load with Transfer Address message with any memory image in it. This is to avoid confusion with additional secondary loaders received in response to the primary loader. Loop Test This section describes the operation of the Loop Test Server and Requester for point-to-point channels. The operation for multicast channels is the Ethernet standard, found in Appendix E or Version 2.0 of the Ethernet Specification. The operational descriptions assume the following Loop Test protocol messages. . Looped Data - a message identifiable as a response to some request. . Loop Data - a message that is to be looped to its sender. Loop Serv