Voice Project Note To Voice Project Date August 31, 1983 3:06 pm From Stewart.pa Location PARC Subject Teleload Organization CSL XEROX Release as /Indigo/Voice/Documentation/Teleload.tioga Came from /Indigo/Voice/Documentation/Teleload.tioga Last edited by Stewart.pa, August 31, 1983 3:06 pm Abstract This document describes the LarkControlPackage program. Environment The df file /Indigo/Voice/Top/Teleload.df describes a collection of software whose general purpose is the downloading and support of microprocessor based Ethernet systems and whose specialized purpose is downloading, debugging, and control of Etherphones (Lark). Teleload encompasses network protocols for remote debugging, specialized knowledge of Etherphones, and a user interface program called LarkControl which in its present form provides services for as many as 64 Etherphones on a particular Ethernet. Teleload Protocol Teleload, as embodied in the Cedar interface TeleLoad.Mesa, provides a set of Pup based facilities usable for downloading, interrogating, and debugging cooperative network hosts. As the implementation of this protocol has only been used for Lark processors, there is no doubt a degree of excess specialization. Related protocols are used by TeleSwat and the TeleDebugger. TeleSwat is protocol by which the BCPL program Swat can debug a remote machine, and the TeleDebugger a Mesa system providing analagous facilities for the Mesa Development Environment. Teleload requires a cooperative host as the debuggee. Except for one case, all Teleload actions are initiated by the debugger. The debuggee merely responds to requests. While some attempt is made at correctly handling non-idempotent requests, the user must beware that lost packets can be important. The native reliability of the research internet reduces the problems to sensible levels. The exception to the passive debuggee arises on initial power-up of the debuggee or on unexpected entry to the Monitor. The Monitor refers to that code in the debuggee that gets control of the machine on power-up or unknown interrupt, and which implements the server end of the TeleLoad protocol. The Monitor is typically in ROM or EPROM. On initial power-up, and in other circumstances which cause control to enter the Monitor from a user program, the Monitor attempts to attract the attention of a debugger. The Monitor periodically broadcasts a "Help-me" packet until someone responds. After the response, the Monitor assumes that the debugger will not forget about it and initiates no further communications. If the Monitor thinks that it knows the network address of a debugger, it will try there first. If there is no response after a number of attempts, then a broadcast will be tried. Most of the inner nature of TeleLoad can be discerned by examination of a typical request from the debugger machine to the debuggee. Consider the case of a request to store data in the debuggee's memory. The packet will be a Pup addressed to the TeleLoad socket on the debuggee. The PupType field will be of value coreStoreRequest. The PupID field will be a sequence number. The debuggee is permitted, but not required, to ignore duplicates. Finally, the Pup data field will contain a data structure with several fields, followed by an array of data to be stored. The record stored in the data field is something like this: CorePktObject: TYPE = RECORD [ setHost: BOOLEAN, setAdvice: BOOLEAN, advice: CARDINAL address: CoreAddress, count: CARDINAL, data: ARRAY OF Byte ]; If the setHost bit is set, the debuggee will make a note of the source of the packet. The source will be the TeleLoad Host and it is to this host that the Monitor will send Help-Me packets. Since the Monitor may not implement the full Pup routing algorithm, packets are sent to (or returned to) the original Pup host and to the original Ethernet host. If the debugger is on a different network, this latter trick will have the effect of rending the reply to the same gateway from which which the request was received. If the setAdvice bit is set, the debuggee will make a note of the value of the advice field. The debuggee does not interpret this data. It is intended as a way to communicate between copies of the debugger. The Etherphone system makes no use of this facility. Address is the destination address of the data block in the debuggee's memory. Count is the size of the block in eight bit bytes, and data is the data itself. When the debuggee receives this packet, the contents of the data block are written to the specified address. The contents are then copied back into the packet, the PupType is incremented and the packet is returned to its original sender. Every request type, such as coreStoreRequest, has a corresponding reply type, which is the request type plus one. The purpose of copying the data block back into the packet is so that the debugger may obtain verification that the write took place correctly. The debuggee may choose not to perform the Pup checksum algorithm, so the debugger is advised to check the reply packet against the original request. Presently defined TeleLoad packet types are: coreStoreRequest -- write debuggee's main memory coreFetchRequest -- read debuggee's main memory slaveStoreRequest -- write debuggee's secondary memory slaveFetchRequest -- write debuggee's secondary memory The Etherphone is a dual processor system with a main and a slave CPU. The slaveStoreRequest and slaveFetchRequest represent one of the many specializations of the TeleLoad idea to the Etherphone. A better alternative is probably to have a system dependent partition of the "address space" of the debuggee to refer to different memories. The TeleLoad protocol has the notion of a machine "state" consisting of register contents and whatever else that doesn't fit the notion of main memory. The packet types that deal with starting and stopping execution of a user program deal with this state. stateFetchRequest -- return system dependent state, typically registers goRequest -- begin execution with given state singleStepRequest -- execute a single instruction with given state goFromBreakRequest -- proceed from a breakpoint with the given state In the case of the singleStepRequest, the debuggee will respond to the single step request packet, then execute the single instruction, then (typically) reenter the Monitor and start sending Help me packets containing "I just executed a single step." goFromBreakRequest is an accellerator for the sequence of single stepping, replacing the stepped instruction with a breakpoint instruction, and resuming execution. debugRequest -- Please enter the Monitor. eventBooted -- "Help me" packet callRequest -- Please call the given procedure with the given arguments LarkControl To use LarkControl, first run the utility package ThUtils, then Run LarkControlPackage. This registers with the executive the command LarkControl. LarkControl takes a single argument, which must be accepable to the network name-lookup services and resolve to a Pup address on the network containing the Etherphones. Thus onee might call for LarkControl 173##. When started, LarkControl puts up a viewer labelled "Lark Control, Net 173" or equivalent. The viewer is composed of three regions, a master control area at the top, containing controls which apply to all controlled Larks, a scrollable region in the middle, containing one line for each Lark, and a typescript region at the bottom, in which messages of general interest are displayed. On command, LarkControl can also create individual debugging viewers for particular Larks. User interaction with LarkControl is through actions in the master control area or scrollable Lark area, or through one of the interactive debugging viewers. LarkControl Commands Master control region MasterControl: Off => don't respond to events Manual => respond to events by printing them Auto => respond to events with appropriate action PrintHelp Button: Tells you about this document. StatusAll Button: red, yellow, blue => Aquire status and GV data for each Lark blue => set debugging pointers shift => print status in log ResetAll Button: Same as the individual Reset buttons, but for each Lark. StartAll Button: Aquire status from each lark and consider automatic load. Always sets debugging pointers. shift => print status in log NewSoftware Button: Re-Parse all loaded Lark software. Does not reset the program pointers of any Larks. Use StatusAll for that. When started, LarkControl puts up a viewer labelled "Lark Control, Net 173" or equivalent. The viewer is composed of three regions, a master control area at the top, containing controls which apply to all controlled Larks, a scrollable region in the middle, containing one line for each Lark, and a typescript region at the bottom, in which messages of general interest are displayed. On command, LarkControl can also create individual debugging viewers for particular Larks. User interaction with LarkControl is through actions in the master control area or scrollable Lark area, or through one of the interactive debugging viewers.