- 1 -



XMODEM/YMODEM PROTOCOL REFERENCE
A compendium of documents describing the

XMODEM and YMODEM

File Transfer Protocols











Editedby Chuck Forsberg














Pleasedistribute as widely aspossible.

Questions to Chuck Forsberg





OmenTechnology Inc
17505-VSauvie Island Road
Portland Oregon 97231
Voice: 503-621-3406
Modem (Telegodzilla): 503-621-3746 Speed 1200,300
Compuserve: 70715,131
UUCP: ...!tektronix!reed!omen!caf















- 2 -



1. ROSETTA STONE

Here are some definitions whichreflectthe current vernacular in the
computer media. The attempt here is identify the file transferprotocol
rather than specific programs.

XMODEMrefers to the original 1979 file transfer etiquette introduced by
Ward Christensen's 1979MODEM2 program. It's also called the
MODEM or MODEM2protocol. Somewho areunawareof MODEM7's
unusualbatch file modecall itMODEM7. Other aliases include
"CP/M Users's Group" and "TERM II FTP 3". Thisprotocol is
supported by every serious communications program because of its
universality, simplicity, and reasonable performance.

XMODEM/CRC replaces XMODEM's 1 byte checksum with a twobyte Cyclical
Redunancy Check(CRC-16), giving modernerror detection
protection.

YMODEMrefers to the XMODEM/CRC protocol with the throughput and/or batch
transmission enhancements described below.


2. YETANOTHERPROTOCOL?

Since its development half a decade ago, the Ward Christensen modem
protocol has enabled a wide variety of computersystemsto interchange
data. There ishardly a communicationsprogramthat doesn't atleast
claim to support this protocol.

Recent advancesin computing, modems and networking have revealed a number
of weaknesses in the original protocol:

+ The short block length caused throughput to sufferwhen used with
timesharing systems, packet switched networks, satellite circuits,
and buffered (error correcting) modems.

+ The 8 bit arithemetic checksum andother aspects allowed line
impairments to interfere with dependable, accuratetransfers.

+ Only one file could be sent per command. The filename had to be
given twice, firstto the sending program and thenagain to the
receiving program.

+ The transmitted file couldaccumulate as many as 127 extraneous
bytes.

+ The modification date of the file was lost.

A number of other protocols have been developedover the years,but none
have displaced XMODEM to date:




Chapter2







X/YMODEM Protocol Reference 10-20-85 3



+ Lack of public domain documentation and example programs have kept
proprietary protocols suchas MNP,Blast, and others tightly boundto
the fortunes of their suppliers.

+ Complexitydiscourages thewidespread application of BISYNC, SDLC,
HDLC, X.25, and X.PC protocols.

+ Performance compromises and moderate complexity have limited the
popularityof the Kermit protocol,which was developed to allow file
transfers in environments hostile to XMODEM.

The YMODEM Protocol extensions were developed as a means of addressing the
weaknesses described above while maintaining XMODEM's simplicity as much
as possible.

YMODEM is supported by the public domain programs YAM (CP/M),
YAM(CP/M-86), YAM(CCPM-86), IMP(CP/M),KMD (CP/M), MODEM76.ASM(CP/M),
rb/sb (Unix, VMS, Berkeley Unix, Venix,Xenix, Coherent, IDRIS,Regulus)
as wellas Professional-YAM.1 These programs have been in use since 1981.

The 1k packet length capabilitydescribed belowmay be used in conjunction
with the Batch Protocol, or with singlefile transfers identical to the
XMODEM/CRC protocol except for the minimal changes to support 1k packets.

Anotherextension is simply called the g option. It provides maximum
throughput whenused with end to end error correcting media, such as X.PC
and error correcting modems, including the emerging 9600 bps units by
Electronic Vaults and others.

To complete this tome, Ward Christensen's original protocol document and
John Byrns's CRC-16 document are included for reference.

References to the MODEMor MODEM7 protocol havebeen changed toXMODEM to
accommodate thevernacular. InAustralia, it is properly called the
Christensen Protocol.

Watch for Ward's article describing theYMODEM protocolin a more coherent
fashion"soon". The article will include history on the development of
microcomputer file transfers.








__________

1. Available for IBM PC,XT,AT,Unix and Xenix




Chapter2







X/YMODEM Protocol Reference 10-20-85 4



2.1 Some Messages fromthe Pioneer

#: 130940 S0/Communications 25-Apr-85 18:38:47
Sb: my protocol
Fm: Ward Christensen 76703,302 (EDITED)
To: all

Be aware the article2 DID quoteme correctly interms of the phrases like
"not robust", etc.

It was a quick hack I threw together, very unplanned (like everything I
do), tosatisfya personal needto communicate with "some other" people.

ONLY the fact that it was done in 8/77,and that I put it in the public
domain immediately, made it become the standardthat itis.

I thinkits time for meto

(1) document it; (people call me and say "my product isgoing to include
it - what can I'reference'", or "I'm writing apaper on it, what do I put
in the bibliography") and

(2) propose an "incremental extension" to it, which might take "exactly"
the form of Chuck Forsberg's YAM protocol. He wrote YAM in C for CP/M and
put it in the public domain, and wrote a batch protocolfor Unix3 called
rb and sb (receive batch, send batch), which was basically XMODEM with
(a) a record0 containing filename date timeand size
(b) a 1K block size option
(c) CRC-16.

He did some clever programming to detect false ACK or EOT, but basically
left them the same.

People who suggest I make SIGNIFICANT changes to the protocol, such as
"full duplex", "multiple outstanding blocks", "multipledestinations", etc
etc don't understand that the incredible simplicity of the protocol is one
of the reasons it survived to this day in as many machines and programsas
it may be foundin!

Consider the PC-NET group back in '77 or so - documenting to beat the band
- THEY had a protocol, but it was "extremely complex", because it triedto
be "allthings to all people" -i.e. send binary files on a 7-bit system,
etc. Iwas notthat "benevolent". I (emphasize> I < )had an 8-bit UART,


__________

2. Infoworld April 29 p. 16

3. VAX/VMS versions ofthese programs are alsoavailable.




Chapter2







X/YMODEM Protocol Reference 10-20-85 5



so "my protocolwas an 8-bit protocol",and I would just say "sorry" to
people who wereheld back by 7-bit limitations. ...

Block size: Chuck Forsberg created an extensionof my protocol,called
YAM, which is also supported via his public domain programs forUNIX
called rb and sb - receive batch and send batch. They cleverlysend a
"block 0" whichcontains the filename, date, time, and size.
Unfortunately, its UNIXstyle, and is abit weird4 - octal numbers, etc.
BUT, itis a nice way to overcome the kludgy "echo the chars ofthe name"
introduced withMODEM7. Further, chuckuses CRC-16 andoptional 1K
blocks. Thus the record 0, 1K,and CRC, make it a "pretty slick new
protocol" whichis not significantly different from my own.

Also, there is a catchyname - YMODEM.That means to some thatit is the
"next thing after XMODEM", and to others that it is theY(am)MODEM
protocol. I don't wantto emphasize that too much - out of fear that
other mfgrs might thinkit is a"competitive" protocol,rather than an
"unaffiliated" protocol. Chuckis currently selling a much-enhanced
versionof his CP/M-80 C program YAM, calling it Professional Yam, and its
for thePC - I'm using it rightnow. VERY slick! 32K capture buffer,
script,scrolling, previously captured text search, plus built-in commands
for just about everything - directory (sorted every which way),XMODEM,
YMODEM,KERMIT,and ASCII file upload/download,etc. You can program it
to "behave" with most any system - for example when trying a number for
CIS it detects the "busy" string back from the modem and substitutes a
diff phone # into the dialing string and branches back to try it.



3. XMODEM PROTOCOL ENHANCEMENTS

This chapter discusses the protocol extensions to Ward Christensen's 1982
XMODEM protocoldescription document.

The original document recommends the user be asked wether to continue
trying or abortafter 10 retries. Mostprograms no longer ask the
operator whether he wishes to keep retrying. Virtuallyall correctable
errors are corrected within thefirst few retransmissions. If the lineis
so bad that tenattempts are insufficient, there is a significant danger
of undetected errors. If the connection is that bad, it's better to
redial for a better connection,or maila floppy disk.





__________

4. Thefile length, time, and file mode are optional.The pathname and
file lengthmay be sent alone if desired.




Chapter3 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-85 6



3.1 Graceful Abort

YAM andProfessional-YAM recognize a sequence of two consecutive CAN (Hex
18) characters without modem errors (overrun, framing, etc.) asa transfer
abort command.1The check for two consecutive CAN characters virtually
eliminates the possibility of aline hit aborting the transfer. YAM sends
five CAN characters when it aborts an XMODEM orYMODEM protocolfile
transfer, followed by five backspaces to deletethe CANcharacters from
the remote's keyboard input buffer (in case theremote had already aborted
the transfer).


3.2 CRC-16 Option

The XMODEM protocol uses an optional two character CRC-16 instead of the
one character arithmetic checksum used by the original protocoland by
most commercialimplementations. CRC-16 guarantees detection of all
single and double bit errors, all errors with an odd number oferror
bits, all bursterrors of length 16 or less, 99.9969% of all 17-bit error
bursts,and 99.9984 percent ofall possible longer error bursts. By
contrast, a double bit error, or a burst error of 9 bits or more can sneak
past the XMODEMprotocol arithmetic checksum.

The XMODEM/CRC protocolis similar to the XMODEM protocol, except that the
receiver specifies CRC-16 by sending C (Hex 43)insteadof NAK when
requesting the FIRST packet. Atwo byte CRC issent inplace of the one
byte arithmeticchecksum.

YAM's coption to the rcommandenablesCRC-16 in single file reception,
corresponding to the original implementation inthe MODEM7 series
programs. Thisremainsthe default because many commercial communications
programs and bulletin board systems still do not support CRC-16,
especially those written in Basic or Pascal.

XMODEM protocolwith CRC is accurate provided both sender and receiver
both report a successful transmission.The protocol isrobust in the
presence of characters lost by buffer overloading on timesharing systems.

The single character ACK/NAK responses generated by thereceiving program
adapt well to split speed modems, wherethe reverse channel is limited to
ten percent orless ofthe main channel's speed.

XMODEM and YMODEM are half duplex protocols which do not attempt to
transmit information and control signals in both directions at the same


__________

1. This is recognized when YAMis waiting for the beginning ofa packet
or for an acknowledge to one that has been sent.




Chapter3 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-85 7



time. This avoids buffer overrun problems thathave been reported by
users attempting to exploit full duplexaynchronous file transfer
protocols such as Blast.

Professional-YAM adds several proprietary logicenhancements toXMODEM's
error detectionand recovery. These compatibleenhancements eliminate
most ofthe badfile transfers other programs make whenusing the XMODEM
protocol under less than ideal conditions.


3.3 1024 Byte Packet Option

The choice to use 1024 byte packets is expressed to thesendingprogramon
its command line or selection menu.2

An STX (02) replaces the SOH (01) at the beginning of the transmitted
block to notifythe receiver ofthe longer packet length. The transmitted
packet contains1024 bytes of data. The receiver should be able to accept
any mixture of 128 and 1024 byte packets. The packet number is
incremented by one for each packet regardless of the packet length.

The sender mustnot change between 128 and 1024byte packet lengths if it
has notreceived a valid ACK for the current packet. Failure to observe
this restriction allowscertaintransmission errors to pass undetected.

If 1024byte packets are being used, itis possible fora file to "grow"
up to the next multipleof 1024bytes.This does not waste disk space if
the allocation granularity is 1k or greater. With YMODEM batch
transmission, the file length transmitted in the file name packet allows
the receiver todiscardthe padding, preservingthe exact file length and
contents.

CRC-16 should be used with the k optionto preserve data integrity over
phone lines.3 1024 bytepacketsmay be used with batch file transmission
or withsingle file transmission.


4. YMODEM Batch File Transmission

The YMODEM Batch protocol is anextension to the XMODEM/CRC protocol that
allows 0 or more files to be transmitted with asingle command. (Zero
files may be sent if none of the requested files is accessible.) The
design approachof the YMODEM Batch protocol isto use the normal routines


__________

2. See"KMD/IMP Exceptions to YMODEM" below.

3. Some programs enforce this recommendation.




Chapter4 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-85 8



Figure 1. 1024 byte Packets

SENDER RECEIVER
"s -kfoo.bar"
"foo.bar openx.x minutes"
C
STX 01 FE Data[1024] CRC CRC
ACK
STX 02 FD Data[1024] CRC CRC
ACK
STX 03 FC Data[1000] CPMEOF[24] CRC CRC
ACK
EOT
ACK

Figure 2. Mixed 1024and 128byte Packets

SENDER RECEIVER
"s -kfoo.bar"
"foo.bar openx.x minutes"
C
STX 01 FE Data[1024] CRC CRC
ACK
STX 02 FD Data[1024] CRC CRC
ACK
SOH 03 FC Data[128] CRC CRC
ACK
SOH 04 FB Data[100] CPMEOF[28] CRC CRC
ACK
EOT
ACK

for sending andreceiving XMODEM packets in a layered fashion similar to
packet switching methods.

Why wasit necessary todesign a new batch protocol when one already
existedin MODEM7?1 Thebatch file modeused byMODEM7 is unsuitable
becauseit doesnot permit fullpathnames, filelength,file date, or
other attributeinformation to be transmitted.Such a restrictive design,
hastilyimplemented with only CP/M in mind, would not have permitted
extensions to current areas of personalcomputing such as Unix,DOS, and
object orientedsystems. In addition, the MODEM7 batchfile mode is
somewhat susceptible totransmission impairments.


__________

1. TheMODEM7 batch protocol transmitted CP/M FCB bytes f1...f8 and
t1...t3 onecharacter at a time. The receiver echoed thesebytes as
received, one at a time.




Chapter4 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-85 9



As in the case of single a filetransfer, the receiver initiates batch
file transmission by sending a "C" character (for CRC-16).

The sender opens the first fileand sends packet number0 with the
following information.2

Only the pathname (filename) part is required for batch transfers.

To maintain upwards compatibility, all unused bytes in packet 0must be
set to null.

Pathname The pathname (conventionally, the filename) is sent as a null
terminatedASCII string. This is the filename format usedby the
handle oriented MSDOS(TM) functions and C library fopen functions.
Anassembly language example follows:
DB 'foo.bar',0
Nospaces are included in the pathname. Normally only thefile name
stem (no directoryprefix)is transmitted unless the sender has
selected YAM's f option tosend the full pathname. The source drive
(A:, B:, etc.) is never sent.

Filename Considerations:

+ File names should be translated to lower caseunless the sending
system supports upper/lower case filenames.This isa
convenience for usersof systems (such as Unix) whichstore
filenames in upper and lower case.

+ The receiver should accommodate file names inlower and upper
case.

+ The rb(1) program on Unix systems normally translatesthe
filename to lower case unlessone or more letters in the
filename are already in lowercase.

+ When transmitting files between different operating systems,
file names must be acceptableto boththe sender and receiving
operating systems.
Ifdirectories areincluded, they are delimited by/; i.e.,
"subdir/foo" is acceptable, "subdir\foo" is not.

Length The filelength and eachof the succeeding fields are optional.3
The lengthfield is storedin the packet as a decimal string counting


__________

2. Only the data part of the packet isdescribed here.

3. Fields may not be skipped.




Chapter4 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-8510



the numberof databytes in the file. Thefile length does not
include any CPMEOF(^Z) charactersused topad thelast packet.

Ifthe file being transmitted is growing during transmission, the
length field should be setto at least thefinal expected file
length, ornot sent.

The receiver stores the specified number of characters, discarding
any padding added by the sender tofill upthe last packet.

Modification Date A single space separates the modification date from the
file length.

The mod date is optional, and the filenameand length may be sent
without requiring the mod date to be sent.

The mod date is sent as anoctal number giving thetime the contents
ofthe file were last changed measured in seconds from Jan1 1970
Universal Coordinated Time(GMT).A date of 0 implies the
modification date is unknown and should beleft asthe date the file
isreceived.

This standard format was chosen toeliminate ambiguities arising from
transfers between different time zones.

Two Microsoft blunders complicate the use of modification dates in
file transfers with MSDOS(TM) systems. The first is the lack of
timezone standardization in MS-DOS. A file's creation time can not
beknown unless the timezone of the systemthat wrote the file4 is
known. Unix solved this problem (for planet Earth, anyway) by
stamping files with Universal Time(GMT).Microsoft wouldhave to
include the timezone of origin in the directory entries, but does
not. Professional-YAM gets aroundthis problem byusing the z
parameter which isset to the number of minutes local timelags GMT.
For files known tooriginate from a different timezone, the -zT
option maybe usedto specify T asthe timezone for an individual
file transfer.

The secondproblemis the lack of a separate file creationdate in
DOS. Since some backup schemes used with DOS relyon the file
creation date to select files to be copiedto the archive,back-
dating thefile modification date could interfere with thesafety of
the transferred files. For this reason, Professional-YAM does not
modify thedate ofreceived files with theheader information unless
the d parameter isnon zero.


__________

4. Notnecessarily that of thetransmitting system!




Chapter4 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-8511



Mode A single space separates the file mode from the modification date.
The file mode is stored asan octal string. Unless the file
originatedfrom a Unix system, thefile mode is set to 0.rb(1)
checks thefile mode for the 0x8000 bit which indicates a Unix type
regular file. Files with the 0x8000 bit set are assumed to have been
sent from another Unix (orsimilar) systemwhich uses the same file
conventions. Suchfiles are not translated in anyway.


Serial Number Asingle space separates the serial number from the file
mode. Theserial number of the transmitting program is stored as an
octal string. Programs which do not have a serialnumber should omit
this field, or setit to 0. The receiver's use ofthis field is
optional.

The rest of thepacket is set to nulls. This is essential to preserve
upward compatibility.5 After the filename packet has been received, it is
ACK'ed if the write open is successful. The receiver then initiates
transfer of thefile contents accordingto the standardXMODEM/CRC
protocol. If the file cannot be openedfor writing, the receiver cancels
the transfer with CAN characters as described above.

After the file contentshave been transmitted, the receiver again asks for
the next pathname. Transmission of a null pathname terminates batch file
transmission. Note that transmission of no files is not necessarily an
error.This ispossible if none of thefiles requestedof the sender
could be openedfor reading.

In batch transmission, the receiver automatically requests CRC-16.

The Unix programs sb(1)and rb(1) included in the source code file
RBSB.SHQ (rbsb.sh) should answer other questions about YMODEM batch
protocol.












__________

5. If,perchance, thisinformation extends beyond 128 bytes (possible
with Unix 4.2 BSD extended file names), thepacket should be sent as a
1k packet as described above.




Chapter4 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-8512



Figure 3. Batch TransmissionSession

SENDER RECEIVER
"sb foo.*"
"sending in batch mode etc."
C (command:rb)
SOH 00 FF foo.c NUL[123] CRC CRC
ACK
C
SOH 01 FE Data[128] CRC CRC
ACK
STX 02 FD Data[1024] CRC CRC
ACK
SOH 03 FC Data[128] CRC CRC
ACK
SOH 04 FB Data[100] CPMEOF[28] CRC CRC
ACK
EOT
NAK
EOT
ACK
C
SOH 00 FF NUL[128] CRC CRC
ACK

Figure 4. Filename packet transmitted by sb

-rw-r--r-- 6347Jun 17 1984 20:34 bbcsched.txt

00 0100FF62 62637363 6865642E 74787400|...bbcsched.txt.|
10 36333437 20333331 34373432 35313320|6347 3314742513 |
20 31303036 34340000 00000000 00000000|100644..........|
30 00000000 00000000 00000000 00000000
80 000000CA 56




















Chapter4 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-8513



Figure 5. YMODEMHeader Information usedby various programs

_____________________________________________________________________
| Program | Batch | Length | Date | Mode | S/N | 1k-Blk | g-Option |
|___________|_______|________|______|______|_____|________|__________|
|Unix rb/sb | yes | yes | yes | yes | no | yes | sb only |
|___________|_______|________|______|______|_____|________|__________|
|VMS rb/sb | yes | yes | no | no | no | yes | no |
|___________|_______|________|______|______|_____|________|__________|
|Pro-YAM | yes | yes | yes | no | yes | yes | yes |
|___________|_______|________|______|______|_____|________|__________|
|CP/M YAM | yes | no | no | no | no | yes | no |
|___________|_______|________|______|______|_____|________|__________|
|KMD/IMP | yes | no- | no | no | no | yes | no |
|___________|_______|________|______|______|_____|________|__________|
|MEX | no | no | no | no | no | yes | no |
|___________|_______|________|______|______|_____|________|__________|

4.1 KMD/IMP Exceptionsto YMODEM

Due to programming constraints,these programs do not send the file length
as described above. Instead, they send(and look for) the CP/Mrecord
count stored inthe last two bytes of the header packet. The least
significant bits are stored in the penultimate byte.

KMD andIMP usethe record count to allow the receivingprogramto display
the file size and estimated transmission time; the filelength is
determined by the actual numberof records sent.

KMD andIMP character sequence emitted by the receiver (CK) to
automatically trigger the use of 1024 byte packets as an alternative to
specifying thisoption on this command line. Although this twocharacter
sequence works well on single process micros indirect communication,
timesharing systems andpacket switchednetworks can separate the
successive characters by several seconds, rendering this method
unreliable.

Sendingprograms may detect theCK sequence if the operating enviornment
does not preclude its efficientimplementation.

Receiving programs should retain the option of sending the standard YMODEM
C (not CK) trigger withthe standard 10second timeout to insure
compatibility with newer forms of telecommunications technology.











Chapter5 XMODEM Protocol Enhancements







X/YMODEM Protocol Reference 10-20-8514



5. g Option File Transmission

Developing technology is providing phone line data transmissionat ever
higher speeds using very specialized techniques. Thesehigh speed modems,
as wellas session protocols such as X.PC, provide highspeed, error free
communications at the expense of considerably increaseddelay time.

This delay timeis moderate compared tohuman interactions, butit
cripples the throughputof mosterror correcting protocols.

The g option toYMODEM has proven effective under thesecircumstances.
The g option isdriven by the receiver,which initiatesthe batch transfer
by transmittinga G instead of C. Whenthe sender recognizes the G, it
bypasses the usual waitfor an ACK to each transmitted packet, sending
succeeding packets at full speed, subject to XOFF/XON or other flow
controlexertedby the medium.

The sender expects an inital G to initiate the transmission of a
particular file, and also expects an ACK on theEOT sent at theend of
each file. This synchronization allowsthe receiver time to open and
close files as necessary.


Figure 6. g Option TransmissionSession

SENDER RECEIVER
"sb foo.*"
"sendingin batch mode etc..."
G (command:rb -g)
SOH 00 FF foo.c NUL[123]CRC CRC
G
SOH 01 FE Data[128] CRC CRC
STX 02 FD Data[1024] CRCCRC
SOH 03 FC Data[128] CRC CRC
SOH 04 FB Data[100] CPMEOF[28] CRC CRC
EOT
ACK
G
SOH 00 FF NUL[128] CRC CRC


6. XMODEM PROTOCOL OVERVIEW

8/9/82 by Ward Christensen.

I will maintaina master copy of this.Please pass on changes or
suggestions viaCBBS/Chicago at(312) 545-8086,CBBS/CPMUG (312) 849-1132
or by voice at (312) 849-6279.






Chapter6 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8515



6.1 Definitions

01H
04H
06H
15H
18H
43H


6.2 Transmission Medium Level Protocol

Asynchronous, 8data bits, no parity, one stop bit.

The protocol imposes norestrictions onthe contents ofthe data being
transmitted. No control characters arelooked for in the 128-byte data
messages. Absolutely any kind of data may be sent - binary, ASCII, etc.
The protocol has not formally been adopted to a7-bit environment for the
transmission ofASCII-only (or unpacked-hex) data , although itcould be
simply by having both ends agree to ANDthe protocol-dependent data with
7F hex before validating it. Ispecifically amreferring to the checksum,
and theblock numbers and theirones- complement.

Those wishing to maintain compatibilityof the CP/M file structure, i.e.
to allow modemming ASCII files to or from CP/M systems should follow this
data format:

+ ASCII tabsused (09H); tabs set every 8.

+ Lines terminated by CR/LF (0DH 0AH)

+ End-of-file indicated by ^Z, 1AH.(one ormore)

+ Data is variable length, i.e. should be considereda continuous
stream of data bytes, broken into 128-bytechunks purely for the
purpose oftransmission.

+ A CP/M "peculiarity": If the data ends exactly on a 128-byte
boundary, i.e. CR in 127, and LF in 128, asubsequent sector
containingthe ^Z EOF character(s)is optional, but is preferred.
Some utilities or user programs still do not handle EOF without ^Zs.

+ The last block sent is no different from others, i.e. there is no
"short block".










Chapter6 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8516



Figure 7. XMODEMMessageBlock Level Protocol

Each block of the transfer looks like:
<255-blk #><--128 data bytes-->
in which:
=01 hex
=binary number, starts at 01 increments by 1, and
wraps 0FFH to 00H (not to 01)
<255-blk #> =blk # after going thru 8080 "CMA" instr, i.e.
each bit complemented in the 8-bit block number.
Formally, this is the "ones complement".
=the sumof the data bytes only. Toss any carry.

6.3 File LevelProtocol

6.3.1 Common_to_Both_Sender_and_Receiver
All errors are retried 10 times. For versions running with an operator
(i.e. NOT with XMODEM),a message is typed after 10 errors asking the
operator whether to "retry or quit".

Some versions of the protocol use , ASCII ^X, to cancel transmission.
This was never adopted as a standard, as havinga single "abort" character
makes the transmission susceptible to false terminationdue to an
or being corrupted into a andcancelling transmission.

The protocol may be considered "receiver driven", that is, the sender need
not automatically re-transmit, althoughit doesin the current
implementations.


6.3.2 Receive_Program_Considerations
The receiver has a 10-second timeout. It sendsa every time it
times out. Thereceiver's first timeout, whichsends a, signals the
transmitter to start. Optionally, the receivercould send a
immediately, incase the senderwas ready. This would save theinitial10
second timeout. However, the receiver MUST continue totimeoutevery 10
secondsin casethe sender wasn't ready.

Once into a receiving ablock, the receiver goes into aone-second timeout
for each character and the checksum. If the receiver wishes to a
block for any reason (invalid header, timeout receivingdata), it must
wait for the line to clear. See "programming tips" forideas

Synchronizing:If a valid block numberis received, itwill be: 1) the
expected one, in which case everything is fine;or 2) arepeat of the
previously received block. This shouldbe considered OK, and only
indicates that the receivers got glitched, and the senderre-
transmitted; 3)any other blocknumber indicates a fatal loss of
synchronization, such as the rare case of the sender getting a line-glitch
that looked like an . Abort the transmission, sending a




Chapter6 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8517



6.3.3 Sending_program_considerations
While waiting for transmission to begin, the sender hasonly a single very
long timeout, say one minute. In the current protocol,the sender has a
10 second timeout before retrying. I suggest NOT doingthis, and letting
the protocol becompletely receiver-driven. This will be compatible with
existing programs.

When the senderhas no more data, it sends an , and awaitsan ,
resending the if it doesn't get one. Again, the protocolcould be
receiver-driven, with the sender only having the high-level 1-minute
timeoutto abort.


Here isa sample of thedata flow, sending a 3-block message. It includes
the twomost common line hits -a garbaged block, and an reply
gettinggarbaged. represents the checksumbyte.

Figure 8. Data flow including Error Recovery

SENDERRECEIVER
times outafter 10 seconds,
<---
01 FE -data- --->
<---
02 FD -data- xx ---> (data gets line hit)
<---
02 FD -data- xx --->
<---
03 FC -data- xx --->
(ack gets garbaged) <---
03 FC -data- xx --->
--->
<---
--->
<---
(finished)

6.4 Programming Tips

+ The character-receive subroutine should becalled with a parameter
specifyingthe number of seconds to wait.The receiver should first
call it with a time of 10,then and try again, 10 times.

After receiving the ,the receiver should call the character
receive subroutinewith a 1-secondtimeout, for the remainder of the
message and the . Since they are sent as acontinuous stream,
timing outof thisimpliesa serious like glitch that caused, say,
127 characters to be seen instead of 128.

+ When the receiver wishes to ,it should call a "PURGE"
subroutine, to wait for the line to clear. Recallthe sender tosses



Chapter6 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8518



any characters in its UARTbuffer immediately uponcompleting sending
a block, to ensureno glitches were mis- interpreted.

The most common technique is for "PURGE" to call the character
receive subroutine, specifying a 1-second timeout,1 and looping back
toPURGE until a timeout occurs. The is then sent, ensuring
the other end willsee it.

+ You may wish to add code recommended by John Mahr to your character
receive routine - to set an error flag if the UARTshows framing
error, or overrun. This will helpcatch afew more glitches - the
most common of which is a hit in the high bits of the bytein two
consecutive bytes. The comes out OK sincecounting in 1-byte
produces the same result of adding80H + 80H as with adding 00H +
00H.



7. XMODEM/CRC Overview

1/13/85by JohnByrns -- CRC option.

Please pass on any reports of errors inthis document or suggestions for
improvement to me via Ward's/CBBS at (312) 849-1132, orby voice at (312)
885-1105.

The CRCused inthe Modem Protocol is an alternate formof block check
which provides more robust error detection thanthe original checksum.
Andrew S. Tanenbaum says in hisbook, Computer Networks, that the CRC-
CCITT used by the ModemProtocol will detect all singleand double bit
errors,all errors withan odd number of bits, all burst errorsof length
16 or less, 99.997% of 17-bit error bursts, and99.998%of 18-bit and
longer bursts.

The changes to the Modem Protocol to replace the checksum with the CRC are
straight forward. If that were all thatwe did we wouldnot be able to
communicate between a program using theold checksum protocol and one
using the new CRC protocol. An initial handshake was added to solve this
problem. The handshake allows areceiving program with CRC capability to
determine whether the sending program supports the CRC option, and to
switch it to CRC mode if it does. This handshake is designed sothat it
will work properly withprograms which implement only the original
protocol. A descriptionof thishandshake is presented in section 10.




__________

1. These timesshould be adjusted for use withtimesharing systems.




Chapter7 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8519



Figure 9. Message Block Level Protocol, CRC mode

Each block of the transfer in CRC mode looks like:
<255-blk #><--128 databytes-->
in which:
= 01 hex
= binary number, starts at01 increments by 1, and
wraps 0FFH to 00H (not to 01)
<255-blk #> = ones complement of blk #.
= byte containing the 8 hiorder coefficients of the CRC.
= byte containing the 8 loorder coefficients of the CRC.

7.1 CRC Calculation

7.1.1 Formal_Definition
To calculate the 16 bitCRC themessagebits are considered to be the
coefficients ofa polynomial. This message polynomial is first multiplied
by X^16and then divided by thegenerator polynomial (X^16 + X^12 + X^5+
1) using modulotwo arithmetic.The remainder left after the division is
the desired CRC. Since a message block in the Modem Protocol is128 bytes
or 1024bits, the message polynomial will be oforder X^1023. The hi order
bit of the first byte of the message block is the coefficient of X^1023in
the message polynomial. The loorder bit of the last byte of the message
block is the coefficient of X^0in the message polynomial.

Figure 10. Example of CRC Calculation written in C

/*
* Thisfunction calculates theCRC used by theXMODEM/CRC Protocol
* The first argument is a pointer to the message block.
* The second argument is the number ofbytes in the message block.
* The functionreturnsan integer which contains the CRC.
* The low order 16 bits are the coefficients of the CRC.
*/
int calcrc(ptr,count)
char *ptr;
int count;
{
intcrc, i;

crc= 0;
while (--count >= 0) {
crc = crc ^ (int)*ptr++<< 8;
for (i = 0; i <8; ++i)
if (crc & 0x8000)
crc = crc << 1 ^ 0x1021;
else
crc = crc << 1;
}
return (crc& 0xFFFF);
}



Chapter7 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8520



7.2 CRC File Level Protocol Changes

7.2.1 Common_to_Both_Sender_and_Receiver
The only changeto the File Level Protocol for the CRC option is the
initialhandshake whichis usedto determine ifboth the sending and the
receiving programs support the CRC mode. All Modem Programs should support
the checksum mode for compatibility with older versions. A receiving
programthat wishes to receive in CRC mode implements the mode setting
handshake by sending a in place of the initial . If the sending
programsupports CRC mode it will recognize the andwill set itself
into CRC mode, and respond by sending the firstblock as if a had
been received. If the sending program does not support CRC modeit will
not respond to the at all. After the receiver has sent the it will
wait upto 3 seconds for the thatstarts the first block.If it
receives a within3 seconds it will assume the sender supports CRC
mode and will proceed with the file exchange inCRC mode. If no is
received within3 seconds the receiver will switch to checksum mode, send
a , and proceed inchecksum mode. If the receiver wishes to use
checksum mode it shouldsend aninitial and the sending program
should respond to the as defined in the original Modem Protocol.
After the mode has beenset by the initial or the protocol
followsthe original Modem Protocol andis identical whether the checksum
or CRC is beingused.


7.2.2 Receive_Program_Considerations
There are at least 4 things that can gowrong with the mode setting
handshake.

1. the initial can be garbled orlost.

2. the initial can be garbled.

3. the initial can be changed toa .

4. the initial from a receiverwhich wants to receive in checksum
can be changed toa .

The first problem can be solvedif the receiversends asecond after
it times out the first time. This process can be repeated several times.
It mustnot be repeatedtoo many times before sending a and
switching to checksum mode or asendingprogramwithoutCRC support may
time out and abort. Repeating the will alsofix thesecond problem if
the sending program cooperates by responding asif a werereceived
insteadof ignoring theextra .

It is possible to fix problems 3 and 4 but probably notworth the trouble
since they willoccur very infrequently. They could be fixed byswitching
modes in eitherthe sending or the receiving program after a large number
of successive s. This solution would risk other problems however.




Chapter7 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8521



7.2.3 Sending_Program_Considerations
The sending program should start in thechecksum mode. This will insure
compatibility with checksum only receiving programs. Anytime a is
received beforethe first or the sending program should set
itself into CRCmode and respond as if a were received. The sender
should respond to additional s as ifthey were s until the first
is received. Thiswill assist thereceiving program in determining
the correct mode when the is lostor garbled. After the first
is received thesendingprogramshould ignore s.


7.3 Data Flow Exampleswith CRC Option

Here isa data flow example forthe case where the receiver requests
transmission inthe CRCmode but the sender does not support the CRC
option.This example also includes various transmissionerrors.
represents the checksumbyte.

Figure 11. Data Flow: Receiver has CRC Option, Sender Doesn't

SENDER RECEIVER
<---
times out after3 seconds,
<---
times out after3 seconds,
<---
times out after3 seconds,
<---
times out after3 seconds,
<---
01 FE -data- --->
<---
02 FD -data- ---> (data gets line hit)
<---
02 FD -data- --->
<---
03 FC -data- --->
(ackgets garbaged)<---
times out after10 seconds,
<---
03 FC -data- --->
<---
--->
<---

Here isa data flow example forthe case where the receiver requests
transmission inthe CRCmode and the sender supports the CRC option. This
examplealso includes various transmission errors. represents the
2 CRC bytes.





Chapter7 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8522



Figure 12. Receiverand Sender Bothhave CRC Option

SENDER RECEIVER
<---
01 FE -data- --->
<---
02 FD -data- ---> (data gets line hit)
<---
02 FD -data- --->
<---
03 FC -data- --->
(ack gets garbaged) <---
times out after 10seconds,
<---
03 FC -data- --->
<---
--->
<---


8. MORE INFORMATION

More information may beobtained by calling Telegodzilla at 503-621-3746.
Hit RETURNs forbaud rate detection.

A version this file with boldface, underlining,and superscripts for
printing on Epson or Gemini printers isavailable on Telegodzilla as
"YMODEME.DOC" or "YMODEME.DQC".

UUCP sites can obtain this filewith
uucp omen!/usr/spool/uucppublic/ymodem.doc/tmp
A continually updated list of availablefiles is storedin
/usr/spool/uucppublic/FILES.

The following L.sys line calls Telegodzilla (Pro-YAM inhost operation).
Telegodzilla waits for carriagereturnsto determine the incoming speed.
If noneis detected, 1200 bps is assumed and a greetingis displayed.

In response to "Name Please:" uucico gives the Pro-YAM "link" command as a
user name. Thepassword (Giznoid) controls access to the Xenixsystem
connected to the IBM PC's otherserial port. Communications between
Pro-YAMand Xenix use 9600 bps;YAM converts this to the caller's speed.

Finally, the calling uucico logs in as uucp.

omen Any ACU 1200 1-503-621-3746 se:--se: link ord: Giznoid in:--in: uucp

Contactomen!caf if youwish the troff sources.






Chapter9 Xmodem Protocol Overview







X/YMODEM Protocol Reference 10-20-8523



9. YMODEM Programs

A demonstrationversionof Professional-YAM is available as YAMDEMO.LQR(A
SQueezed Novosielski library).This may be used to test YMODEM
implementations.

Unix programs supporting the YMODEM protocol are available on Telegodzilla
in the "upgrade" subdirectory as RBSB.SHQ (a SQueezed shell archive).
Most Unix like systems are supported, includingV7, SysIII, 4.2 BSD, SYS
V, Idris, Coherent, andRegulus.

A version for VAX-VMS is available in VRBSB.SHQ, in thesame directory.

A CP/M assemblyversionis available asMODEM76.AQM andMODEM7.LIB.

Irv Hoff has added YMODEM 1k packets and basic YMODEM batch transfers to
the KMDand IMPseries programs, which replace the XMODEM and
MODEM7/MDM7xx series respectively. Overlays are available for a wide
varietyof CP/Msystems.

MEX andMEX-PC also support some of theYMODEM extensions.

Questions aboutYMODEM,the Professional-YAM communications program, and
requests for evaluationcopies may be directed to:
Chuck Forsberg
Omen Technology Inc
17505-V Sauvie Island Road
Portland Oregon 97231
Voice: 503-621-3406
Modem: 503-621-3746 Speed:1200,300
Usenet: ...!tektronix!reed!omen!caf
Compuserve: 70715,131
Source: TCE022





















Chapter9 Xmodem Protocol Overview











CONTENTS


1. ROSETTA STONE..................................................... 2

2. YETANOTHERPROTOCOL?............................................. 2
2.1 Some Messages from thePioneer............................... 4

3. XMODEM PROTOCOL ENHANCEMENTS...................................... 5
3.1 Graceful Abort............................................... 6
3.2 CRC-16Option................................................ 6
3.3 1024 Byte Packet Option...................................... 7

4. YMODEM Batch File Transmission.................................... 7
4.1 KMD/IMP Exceptions to YMODEM.................................13

5. g Option File Transmission........................................14

6. XMODEM PROTOCOL OVERVIEW..........................................14
6.1 Definitions..................................................15
6.2 Transmission Medium Level Protocol...........................15
6.3 File Level Protocol..........................................16
6.4 Programming Tips.............................................17

7. XMODEM/CRC Overview...............................................18
7.1 CRC Calculation..............................................19
7.2 CRC File LevelProtocol Changes..............................20
7.3 Data Flow Examples with CRC Option...........................21

8. MORE INFORMATION..................................................22

9. YMODEM Programs...................................................23






















- i -














LIST OF FIGURES


Figure1. 1024 byte Packets......................................... 7

Figure2. Mixed 1024 and 128 byte Packets........................... 7

Figure3. Batch Transmission Session................................11

Figure4. Filename packet transmittedby sb.........................11

Figure5. YMODEM Header Information used by various programs........13

Figure6. g Option Transmission Session.............................14

Figure7. XMODEM Message Block Level Protocol.......................16

Figure8. Data flow includingError Recovery........................17

Figure9. Message Block LevelProtocol, CRC mode....................19

Figure 10. Example of CRC Calculation written in C...................19

Figure 11. Data Flow: Receiverhas CRCOption,Sender Doesn't........21

Figure 12. Receiver and SenderBoth have CRC Option..................22

























- ii -