Return to proto.ms CVS log

Up to [Research Unix] / researchv10dc / vol2 / Mpx

Annotation of researchv10dc/vol2/Mpx/proto.ms, revision 1.1

1.1     ! root        1: .so ../ADM/mac
        !             2: .XX 39 593 "Blit down-load and communications protocols"
        !             3: .de UL
        !             4: .lg 0
        !             5: .if n .ul
        !             6: \%\&\\$3\f(HI\\$1\f1\&\\$2
        !             7: .lg
        !             8: ..
        !             9: .EG
        !            10: .TL
        !            11: Blit down-load and communications protocols
        !            12: .AU
        !            13: Rob Pike
        !            14: .AI
        !            15: .MH
        !            16: .AB
        !            17: A description of the protocols used in the Blit software to communicate
        !            18: between host and terminal.
        !            19: Four protocols are presented:
        !            20: the two down-load protocols,
        !            21: the
        !            22: .I mpx
        !            23: communication protocol,
        !            24: and the layer control protocol between
        !            25: .I mpx
        !            26: and
        !            27: .I mpxterm .
        !            28: User-level protocols such as in
        !            29: .I jim ,
        !            30: .I jx
        !            31: and
        !            32: .I joff
        !            33: are not described.
        !            34: .AE
        !            35: .2C
        !            36: .NH
        !            37: Byte order
        !            38: .PP
        !            39: All data representations in the Blit protocols are 68000 style,
        !            40: that is, high byte first in a word, high word first in a long-word.
        !            41: This convention was chosen because Blits may be run on a variety
        !            42: of host computers, but it was thought there would be only one
        !            43: processor in the Blit.
        !            44: Fortunately, both processors used in Blits have the same byte order.
        !            45: Regarding program binaries, which are processor-dependent,
        !            46: the following
        !            47: .I 68ld
        !            48: protocol descriptions are for the 68000 and may not
        !            49: apply to the W32000 (and
        !            50: .I 32ld ?).
        !            51: .NH
        !            52: \f468ld\fP protocol for stand-alone down-loading
        !            53: .PP
        !            54: .I 68ld
        !            55: sends a control-P (octal
        !            56: .CW 020 )
        !            57: character to initiate down-loading.
        !            58: The protocol is an error-corrected packet protocol,
        !            59: running in one of three modes, according to
        !            60: .I 68ld
        !            61: options.
        !            62: The default runs without CRC's or acknowledgements, and is therefore
        !            63: not error-corrected, but runs significantly faster than the other
        !            64: modes, due to scheduling turn-around, on some Unix systems.
        !            65: .CW "68ld -x"
        !            66: generates and checks CRC's, but the terminal
        !            67: replies with an ACK packet only after the last data packet.
        !            68: .CW "68ld -e"
        !            69: is fully error-corrected, with an ACK for each packet.
        !            70: .PP
        !            71: Each packet is formatted like this:
        !            72: .DS
        !            73: .UL "<typ^seq> <size> <address>"
        !            74: .UL "[<data bytes>]"
        !            75: .UL "[<CRC1> <CRC2>]"
        !            76: .DE
        !            77: where the notation
        !            78: .CW <>
        !            79: signifies one byte and
        !            80: .CW []
        !            81: a optional sequence of bytes.
        !            82: .PP
        !            83: The maximum length of the entire packet, including CRC's, is 128 bytes.
        !            84: .CW typ
        !            85: specifies the ac\%knowledg\%ment handling for each packet,
        !            86: although in practise all packets have the same type.
        !            87: .CW typ=0x80
        !            88: implies full error correction,
        !            89: .CW typ=0x40
        !            90: implies no error correction or CRC's,
        !            91: and
        !            92: .CW typ=0xC0
        !            93: implies only error detection, with a final ACK packet.
        !            94: .UL seq
        !            95: is a 6-bit sequence number.
        !            96: .UL size
        !            97: is the number of address and data bytes in the packet, excluding header and CRC.
        !            98: All packets contain the 4-byte address to which the data should be copied.
        !            99: If
        !           100: .UL size
        !           101: is 4,
        !           102: which is only true on the last packet of the down-load,
        !           103: .UL address
        !           104: is the boot address of the program;
        !           105: receipt of this packet is the signal to begin execution.
        !           106: If
        !           107: .UL size
        !           108: is greater than 4,
        !           109: the data bytes are part of the program.
        !           110: If the packet is correctly received, the terminal returns
        !           111: an ACK, consisting of
        !           112: the first
        !           113: .UL typ^seq
        !           114: byte from the packet.
        !           115: The CRC is sent low byte first,
        !           116: and applies to the entire packet except the two CRC bytes.
        !           117: The polynomial used is (16, 15, 2, 0).
        !           118: Timeouts or
        !           119: out-of-sequence ACKs cause the retransmission of
        !           120: all un-acknowledged packets.
        !           121: .NH
        !           122: \f468ld\fP protocol for down-loading \f4mpxterm\fP binaries
        !           123: .PP
        !           124: .I 68ld
        !           125: issues a
        !           126: .CW JMPX
        !           127: ioctl to determine that the standard output is an
        !           128: .I mpx
        !           129: channel.
        !           130: It then issues a
        !           131: .CW JBOOT
        !           132: ioctl to initiate the down-load protocol.
        !           133: If
        !           134: .I 68ld
        !           135: is invoked with the
        !           136: .CW -z
        !           137: option,
        !           138: .CW JZOMBOOT
        !           139: is instead sent, signifying that after down-loading the process is to
        !           140: be suspended until
        !           141: .I joff
        !           142: starts it running.  The protocol is the same in either case.
        !           143: .PP
        !           144: .I 68ld
        !           145: next sends the arguments to the program.
        !           146: It first sends the argument count,
        !           147: including the program name itself.
        !           148: It next sends the number of characters in the complete list of arguments,
        !           149: including a null character terminating each argument string.
        !           150: It then sends 3 numbers defining the program size:
        !           151: the text size, data size and bss size, in that order.
        !           152: All these integers are 32 bits long.
        !           153: .I mpx
        !           154: answers with the 32-bit address at which the program
        !           155: will be loaded.  Text, data and bss are contiguous inside the Blit.
        !           156: If the returned address is zero,
        !           157: there was insufficient memory in the terminal and
        !           158: .I 68ld
        !           159: must send a
        !           160: .CW JTERM
        !           161: ioctl to restore the terminal state.
        !           162: .PP
        !           163: .I 68ld
        !           164: next sends the argument strings, each terminated by a null.
        !           165: Then, it sends the relocated binary in two sections, transmitted identically:
        !           166: text and data.  Bss is zeroed out by the Blit, and is not transmitted.
        !           167: Text and data are sent as unformatted byte streams,
        !           168: whose combined length must agree with the length of the sections
        !           169: as reported earlier in the protocol.
        !           170: When the Blit has received all the characters, execution begins.
        !           171: .PP
        !           172: The protocol is not error-corrected, because it runs over
        !           173: an error-corrected communications channel provided by
        !           174: .I mpx .
        !           175: .NH
        !           176: \f4mpx\fP communications protocol
        !           177: .PP
        !           178: Communication between
        !           179: .I mpx
        !           180: and
        !           181: .I mpxterm
        !           182: is on an eight-bit byte, eight-channel, error-corrected packet-multiplexed protocol.
        !           183: The protocol is symmetrical with respect to the host and terminal;
        !           184: it is implemented by the same source code at both ends.
        !           185: Each channel is double-buffered, so a process writing on a channel does
        !           186: not block unless both packet slots on that channel are awaiting acknowledgements.
        !           187: When the ACK is received, the packet slot is made available.
        !           188: .PP
        !           189: The layout of a packet is:
        !           190: .DS L
        !           191: .UL "<1:1|cntl:1|seq:3|cbits:3>"
        !           192: .UL "<dsize:8> <dsize bytes of data>"
        !           193: .UL "<CRC1> <CRC2>"
        !           194: .DE
        !           195: where the notation
        !           196: .CW <>
        !           197: signifies a byte and
        !           198: .CW x:\f2n\fP
        !           199: signifies
        !           200: .I n
        !           201: bits of
        !           202: .CW x .
        !           203: Bits are numbered from the high bit of the byte.
        !           204: The CRC is sent low byte first,
        !           205: and applies to the entire packet except the two CRC bytes.
        !           206: The polynomial used is (16, 15, 2, 0).
        !           207: .PP
        !           208: The first bit (i.e. high bit of first byte) of a packet is always on.
        !           209: The next bit
        !           210: .UL cntl ) (
        !           211: states whether the packet is a control packet.
        !           212: The next three bits
        !           213: .UL seq ) (
        !           214: are the sequence number, modulo 7,
        !           215: and the bottom three are the channel number.
        !           216: .UL dsize
        !           217: is the number of bytes of data, excluding the entire header and CRC.
        !           218: The maximum value of
        !           219: .UL dsize
        !           220: is 64, although this has been 32 and 128 from time to time.
        !           221: In retrospect, 64 was a bad choice, because the maximum packet size is not
        !           222: a power of two.
        !           223: The maximum number of channels could be increased by moving the
        !           224: sequence number into the
        !           225: .UL dsize
        !           226: byte and giving the extra bits to the channel number.
        !           227: This was not done originally to simplify playing with the
        !           228: maximum packet sizes.
        !           229: .PP
        !           230: Most packets are data packets, that is, packets sent by a user process
        !           231: and containing user data.
        !           232: These all have
        !           233: .UL cntl
        !           234: set to zero.
        !           235: .PP
        !           236: Control packets, with
        !           237: .UL cntl
        !           238: set to one, are always ACKs or NAKs (negative acknowledgements).
        !           239: If
        !           240: .UL dsize
        !           241: is zero, the control packet is an acknowledgement, and signifies that
        !           242: it and all lesser-sequenced packets have been received correctly.
        !           243: If
        !           244: .UL dsize
        !           245: is non-zero, the first data byte is
        !           246: .CW 0206
        !           247: for an ACK, or
        !           248: .CW 0225
        !           249: for a NAK.
        !           250: A NAK is a request for retransmission of the packet and all lesser-sequenced
        !           251: unacknowledged packets.
        !           252: A control packet can contain an extra data byte, set by the user.
        !           253: Originally, the byte was used to hold characters for echoing to the terminal,
        !           254: so the ACK packet for a typed character could include the echo,
        !           255: halving the packet traffic.
        !           256: Now, however, only unblock messages (see next section) are transmitted this way.
        !           257: .NH
        !           258: Blit-\f4mpx\fP layer protocol
        !           259: .PP
        !           260: On top of the error-corrected communications protocol,
        !           261: .I mpx
        !           262: and
        !           263: .I mpxterm
        !           264: communicate by an asymmetric protocol to establish new processes,
        !           265: delete processes, initiate down-loading, etc.
        !           266: .PP
        !           267: All messages from the Blit to
        !           268: .I mpx
        !           269: begin with a byte stating the nature of the message.
        !           270: Most commonly, the message contains data to be sent to the associated
        !           271: Unix process
        !           272: (since this communication runs above the multiplexed protocol,
        !           273: the channel number is implicit),
        !           274: but sometimes the message contains control information for
        !           275: .I mpx .
        !           276: The message tags are shown in Figure 1.
        !           277: .1C
        !           278: .KF
        !           279: .TS
        !           280: center;
        !           281: c c c
        !           282: lFCW cFCW l.
        !           283: =
        !           284: Name   Value   Meaning
        !           285: _
        !           286: C_SENDCHAR     1       Send character to Unix process
        !           287: C_NEW  2       Create new Unix process group
        !           288: C_UNBLK        3       Unblock layer process
        !           289: C_DELETE       4       Delete layer process group
        !           290: C_EXIT 5       Exit
        !           291: C_BRAINDEATH   6       Send hangup signal to Unix process group
        !           292: C_SENDNCHARS   7       Send several characters to Unix process
        !           293: C_RESHAPE      8       Layer has been reshaped
        !           294: _
        !           295: .TE
        !           296: .ce
        !           297: \fBFigure 1.\fR Protocol messages
        !           298: .SP
        !           299: .KE
        !           300: .2C
        !           301: .PP
        !           302: The following descriptions ignore the control byte, which is
        !           303: always the zeroth byte of the message.
        !           304: .CW C_SENDCHAR
        !           305: sends a single character (the first byte of the message) to the Unix process.
        !           306: .CW C_SENDNCHARS
        !           307: sends the number of characters specified by the first byte to the
        !           308: Unix process; the data starts at the second byte.
        !           309: .CW C_NEW
        !           310: creates a new process group (shell) on Unix.
        !           311: The implicit channel number of the message is used thereafter
        !           312: for full-duplex communication between the terminal and Unix processes.
        !           313: The data in the packet
        !           314: specifies the size of the layer for the terminal process.
        !           315: The format is:
        !           316: .DS
        !           317: .UL "<charx> <chary> <bitsx> <bitsy>"
        !           318: .DE
        !           319: where
        !           320: .I char
        !           321: is the number of standard-size characters across the window,
        !           322: and
        !           323: .I bits
        !           324: is the number of screen pixels,
        !           325: within the border.
        !           326: .CW C_RESHAPE
        !           327: has the same format as
        !           328: .CW C_NEW
        !           329: and specifies the dimensions of a layer after reshaping.
        !           330: .CW C_DELETE
        !           331: states that the user deleted the layer,
        !           332: and that a hangup signal should be sent to the associated process group.
        !           333: .CW C_BRAINDEATH
        !           334: says that the terminal program faulted (e.g. generated a bus error)
        !           335: and that the associated Unix process should be sent a hangup signal.
        !           336: .CW C_EXIT
        !           337: states that the user selected the
        !           338: .CW Exit
        !           339: button on the
        !           340: .I mpxterm
        !           341: menu.
        !           342: .PP
        !           343: Although the multiplexed protocol is error-corrected, it may back up,
        !           344: because the terminal process may not read the packet data out of the
        !           345: protocol's buffers.
        !           346: The message
        !           347: .CW C_UNBLK
        !           348: is therefore sent when a terminal process has emptied out the packet
        !           349: buffer so there is room for more data at user level in the terminal.
        !           350: These messages are only generated when the protocol backs up;
        !           351: if packets are emptied quickly by the terminal process
        !           352: (which is usually true), unblocks are unnecessary and are not generated.
        !           353: .PP
        !           354: Packets traveling from
        !           355: .I mpx
        !           356: to the Blit
        !           357: are always data to be copied into the terminal process's RCV queue.
        !           358: Process 0 is the demultiplexor process,
        !           359: and packets sent to it are
        !           360: ioctl
        !           361: messages that must be handled by the terminal:
        !           362: .CW JBOOT ,
        !           363: .CW JTERM ,
        !           364: etc.
        !           365: A packet sent during initialization, either
        !           366: .CW JTIMO
        !           367: or
        !           368: .CW JMTIMO ,
        !           369: sets the protocol timeout parameters, because the terminal cannot
        !           370: sense the baud rate.
        !           371: .CW JTIMO
        !           372: (followed by the timeout period in seconds)
        !           373: is used by Berkeley and Eighth Edition systems;
        !           374: .CW JMTIMO
        !           375: (followed by the timeout period in milliseconds)
        !           376: is used by System V and derivative systems.
        !           377: I have no idea why there is a difference.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.