Copyright Xerox Corporation 1979Inter-Office MemorandumToCommunications ProtocolsDateDecember 20, 1978FromDavid BoggsLocationPalo AltoSubjectTeleSwat ProtocolOrganizationParcXEROX Filed on: [Maxc1]TeleSwat.bravoThere may not be a debugger in Peoria, but there is a debugger in Palo Alto and a way to movepackets between Palo Alto and Peoria.This memo documents the protocol by which Swat communicates with a remote Swatee. I maintaina lot of software which is used at other Xerox sites, and I often get calls from users when a programlands in Swat. The caller is rarely facile with Swat's command language, and it is very difficult toguide him through the steps necessary to gather debugging information (assuming for the momentthat he has the symbol file on his disk). Many programs are also available as boot files, for whichthe only debugger available until now was SSD: a super simple octal debugger. The need for across-net debugger has been clear for a long time. Pup gateways have a rudimentary debuggerserver in them, but the effort required to build the remote user has prevented development, and ithas remained only a toy. Bolt Beranek and Newman has developed several cross-net debuggers. Iknow of two: one for debugging ArpaNet Imps and one for debugging PDP-11 BCPL programs.There are many ways to do remote debuggers. A useful way to classify them is to ask where thelogic of the debugger runs: in the machine being debugged or in the machine where the humandebugger is. I considered putting a Telnet server into Swat, and using Chat to control the remoteSwat. Swat's keyboard and display stream would then be paralleled with the Telnet streams. Theadvantages of this approach are that it would use existing software, and Swat could then acceptcommands from either the remote Chat or the local keyboard, allowing joint debugging by the guywith the broken machine and the remote guru. The disadvantage is that it takes a lot of code toimplement a Telnet server and Swat, like all Alto programs, is short on space. A server built on thestandard Pup package would consume about 6K. Building a Telnet server from scratch is too muchwork. That eliminated this approach.The interface between a debugger and a debugee is usually quite simple, and the other approachwhere the debugger runs in the remote machine with just a small nub in the debugee lookedpromising. The debugger must be able to fetch and store memory locations in the debugee, and tellit to stop and go. In addition there must be conventions for saving and restoring the debugee'sstate, and interrupting (manually and by breakpoints) and resuming. Since there is not alwaysnetwork software present in our machines and because of our dislike of omnipotent operatingsystems, it is not possible to force a remote machine into the debugger without its consent, so thateliminates the stop command. This approach greatly reduces the amount of mechanism in theremote machine - it is possible to write a server which implements Fetch, Store and Go in a fewhundred instructions. The prospect of including such a debug nub in boot files and then being ableto symbolically debug them with Swat convinced me that this was the way to go.How Swat does it &pX]g~qi cr]pX-r7Bp ]r]p -r7Bp Yr]p-r 7BpSsp M$ GtX Fi% C=p#: A` @3b >W =)"B ;W :%7 8[ 7G 5;rprp 2dH 00+ /Z=% -"> ,P:% *[ )FX 'e &< S $% !G ? 20 N wG Q m:* V cS #@ YN -u =d BTeleSwat Protocol2Swat contains a very simple Pup Level 0 Ethernet driver, a Level 1 Raw Pup dispatcher, and aLevel 2 TeleSwat User and Server. The ^Z command specifies the address space which Swat peersinto: any bank of memory, or any file created by OutLd (usually, of course, this is Swatee), or anyhost in the internet, in which case Swat becomes a TeleSwat user and the remote host is assumed toimplement the server half of this protocol.The $$^Y command makes Swat a TeleSwat server: it then ignores the keyboard and answers Fetch,Store and Go packets from the net. If the target address space is set to Swatee using the ^Zcommand before making it a server, then things work as you would expect, except remotely. If theserver's target address space is set to bank 0, the user Swat will be examining the server Swat'srunning core image (in principle the server's target address space could even be another host...).Servers other than Swat are not expected to be this fancy; the address space which the serverreferences on behalf of the user is outside of this protocol.The TeleSwat user is where the debugger logic is running and most of the Swat in the server is notbeing used. A boot file, which usually doesn't hook up to the local disk and therefore can't callSwat, can contain a tiny debug nub which implements the server half of the TeleSwat protocol andwhich gets control when the program tries to call Swat. In this case Fetch and Store requests go tothe running core image.The ProtocolThe protocol is designed to minimize work for the server, placing the burden on the user. Theserver is completely passive: it only does something in response to a command from a TeleSwatuser, and the only packets it generates are acknowledgements. Duplicate suppression, retransmissionof lost packets, etc is the responsibility of the user. The protocol is connectionless: except for theGo command, the server is not required to maintain any state from one packet to the next.There are three commands and five packet types. The user should employ the Pup ID as a packetsequence number for duplicate suppression. To respond to a request, the server need only set thetype to 'ack', exchange the source and destination ports, append the requested information if any,and send the Pup back to its physical source (note that the server doesn't have to worry aboutrouting).In Fetch and Store commands, the user may optionally request that the server send back a block ofwords surrounding the word being fetched or stored. The server may ignore this and only sendback the requested word, but if it complies, the user can then implement a cache and reduce thenumber of packets it generates. When the machines are directly connected via an Ethernet, thecache doesn't buy much, but when they are separated by a 9.6 KB hop, it wins big. I haveexperimentally determined that the optimum block size is about 16 or 32 words; Swat asks for 32word blocks. The size of the surrounding block of memory requested by the user can be any powerof two up to 256; the server may choose to send a block of a different size (for example: the servermay have a small packet buffer which can hold a block of up to 32 words; if the user requests a256 word block the server may respond with a 32 word block). The base address of a block is theaddress of the fetch or store command which the ack packet is acknowledging ANDed with thenegative block size in the ack packet.The Go command involves a 3-way hand-shake to protect against lost acknowledgements. Theproblem is similar to closing a connection. The user says Go; if the packet is lost, no ack comesback and the user retransmits. If the ack is lost, the user also retransmits since he can't distinguishthis from having the Go command clobbered. If the server resumes the Swatee as soon as itreceives a Go, but its ack is lost, the user will be unsure of whether the server heard it, since theserver has stopped listening and isn't around to retransmit acks. So when the server receives a Gocommand, it acknowledges it and then dallies for up to 10 seconds, so that it can retransmit a lostack. When the user gets the ack, it sends a GoReply packet (the third packet in the hand-shakesequence). If the server gets this and the previous packet was a Go, it stops dallying and resumesthe Swatee. If it gets any other command, it abandons the Go command. If the GoReplycommand is lost, the server dallies for 10 seconds and then resumes the Swatee. The Pup ID of a fpG bH `^ _ U ]H \ + XA WY"; U3. TOS RP QE> O= L^ K/3 IW H7- F CTu @(pE >] =R ;*= :< 6K 5c.3 3N 2YB 0 -O ,#+2 *>! )? '=rp &A $J #Y !A =# v3rp  $ S @X I 6Z ,9 ,03 %vp * "G #@ -) O L>]TeleSwat Protocol3GoReply packet should be one greater than the previous Go packet.DetailsAll numbers are octal. The well known TeleSwat server socket is 60. For this description (andhistorical reasons) the data words and bytes in a Pup are numbered from one, not zero.Store (user to server)Pup Type: 200Pup ID: arbitrary (server sends it back in the ack)Pup Contents: the first data word of the packet contains the address of the word to bestored into. The second data word is the value to store. If the third data word is non-zero,then the user is requesting the server to send a block of that many words surrounding theaddress specified in word 1. The block should reflect the result of the store.Ack: The first data word of the ack is the address of a word in the debugee. The seconddata word is ignored. If the third word is non-zero, then a block of that many words of thedebugee begins in the fourth data word. The base address of the block is (word 1) AND -(word 3). Note that the server doesn't have to send a block, and may choose to send ablock of a different size, usually smaller.Fetch (user to server)Pup Type: 201Pup ID: arbitrary (server sends it back in the ack)Pup Contents: the first data word is the address to fetch. The second data word is ignored.If the third data word is non-zero, it is a request for a block of that many words as in theStore command.Ack: The first data word is the requested address. The second data word is the contents ofthat address. If the third data word is non-zero, then the interpretation is as for the Storecommand.Go (user to server)Pup Type 202Pup ID: arbitrary (server sends it back in the ack)Pup Contents: noneAck: no contentsGoReply (user to server)Pup Type: 203Pup ID: the ID of a previous Go command plus onePup Contents: noneNot acknowledgedAcknowledgement (server to user)Pup Type: 204Pup ID: same as corresponding requestPup Contents: See descriptions above. fpG bA ^u [pN ZAV WvpS Rd3P IOZAM&3LPOI$<GBFRrpDBC+ ?vp< ;339;!8)V6 3x)21P 0n -Bvp* (3' # vp 0~RKR a &vp u% % =ZaTeleSwat Protocol4Caution: the length of the data portion of a Fetch or Store packet can be as little as 2 (fetch) or 4(store) bytes, in which case word 3 (block length) is meaningless. Similarly for acks: if the length isless than 6 bytes, no block follows.Revision HistoryDecember 11, 1978: first release.December 20, 1978: the second data word in a Store ack is unspecified. fpG b aqb? `26 _$ [u Xp! UFz R=> TIMESROMAN  TIMESROMAN  TIMESROMANLOGO TIMESROMAN  TIMESROMAN  TIMESROMAN e j/FTELESWAT.bravoTaftSeptember 3, 1979 5:45 PM