        '                                   - 1 -       5                      XMODEM/YMODEM PROTOCOL REFERENCE 9                  A compendium of documents describing the   -                             XMODEM and YMODEM   0                          File Transfer Protocols                      1                          Edited by Chuck Forsberg                             9                  Please distribute as widely as possible.   2                        Questions to Chuck Forsberg          .                            Omen Technology Inc2                         17505-V Sauvie Island Road/                           Portland Oregon 97231 .                            Voice: 503-621-3406=             Modem (Telegodzilla): 503-621-3746 Speed 1200,300 /                           Compuserve: 70715,131 5                     UUCP: ...!tektronix!reed!omen!caf                               '                                   - 2 -        1.  ROSETTA STONE   E Here are some definitions which reflect the current vernacular in the H computer media.  The attempt here is identify the file transfer protocol rather than specific programs.  I XMODEM  refers to the original 1979 file transfer etiquette introduced by E         Ward Christensen's 1979 MODEM2 program.  It's also called the C         MODEM or MODEM2 protocol.  Some who are unaware of MODEM7's F         unusual batch file mode call it MODEM7.  Other aliases includeC         "CP/M Users's Group" and "TERM II FTP 3".  This protocol is H         supported by every serious communications program because of its=         universality, simplicity, and reasonable performance.   E XMODEM/CRC replaces XMODEM's 1 byte checksum with a two byte Cyclical ?         Redunancy Check (CRC-16), giving modern error detection          protection.   J YMODEM  refers to the XMODEM/CRC protocol with the throughput and/or batch2         transmission enhancements described below.     2.  YET ANOTHER PROTOCOL?   C Since its development half a decade ago, the Ward Christensen modem F protocol has enabled a wide variety of computer systems to interchangeE data.  There is hardly a communications program that doesn't at least  claim to support this protocol.   J Recent advances in computing, modems and networking have revealed a number' of weaknesses in the original protocol:   F    + The short block length caused throughput to suffer when used withG      timesharing systems, packet switched networks, satellite circuits, ,      and buffered (error correcting) modems.  B    + The 8 bit arithemetic checksum and other aspects allowed lineB      impairments to interfere with dependable, accurate transfers.  F    + Only one file could be sent per command.  The file name had to beD      given twice, first to the sending program and then again to the      receiving program.   D    + The transmitted file could accumulate as many as 127 extraneous      bytes.   0    + The modification date of the file was lost.  H A number of other protocols have been developed over the years, but none have displaced XMODEM to date:        	 Chapter 2               J X/YMODEM Protocol Reference      10-10-85                                3      G    + Lack of public domain documentation and example programs have kept J      proprietary protocols such as MNP, Blast, and others tightly bound to%      the fortunes of their suppliers.   G    + Complexity discourages the widespread application of BISYNC, SDLC, $      HDLC, X.25, and X.PC protocols.  E    + Performance compromises and moderate complexity have limited the I      popularity of the Kermit protocol, which was developed to allow file 1      transfers in environments hostile to XMODEM.   J The YMODEM Protocol extensions were developed as a means of addressing theH weaknesses described above while maintaining XMODEM's simplicity as much as possible.  = YMODEM is supported by the public domain programs YAM (CP/M), G YAM(CP/M-86), YAM(CCPM-86), IMP (CP/M), KMD (CP/M), MODEM76.ASM (CP/M), H rb/sb (Unix, VMS, Berkeley Unix, Venix, Xenix, Coherent, IDRIS, Regulus)I as well as Professional-YAM.1 These programs have been in use since 1981.   J The 1k packet length capability described below may be used in conjunctionG with the Batch Protocol, or with single file transfers identical to the I XMODEM/CRC protocol except for the minimal changes to support 1k packets.   E Another extension is simply called the g option.  It provides maximum I throughput when used with end to end error correcting media, such as X.PC E and error correcting modems, including the emerging 9600 bps units by  Electronic Vaults and others.   H To complete this tome, Ward Christensen's original protocol document and8 John Byrns's CRC-16 document are included for reference.  I References to the MODEM or MODEM7 protocol have been changed to XMODEM to D accommodate the vernacular.  In Australia, it is properly called the Christensen Portocol.   F Watch for an article describing the YMODEM protocol in a more coherentC fashion later this year.  The article will include some interesting ; history on the development of microcomputer file transfers.                 
 __________  .  1. Available for IBM PC,XT,AT, Unix and Xenix        	 Chapter 2               J X/YMODEM Protocol Reference      10-10-85                                4      # 2.1  Some Messages from the Pioneer   / #: 130940 S0/Communications 25-Apr-85  18:38:47  Sb: my protocol ' Fm: Ward Christensen 76703,302 (EDITED)  To: all   I Be aware the article2 DID quote me correctly in terms of the phrases like  "not robust", etc.  G It was a quick hack I threw together, very unplanned (like everything I H do), to satisfy a personal need to communicate with "some other" people.  G ONLY the fact that it was done in 8/77, and that I put it in the public ; domain immediately, made it become the standard that it is.    I think its time for me to  H (1) document it; (people call me and say "my product is going to includeJ it - what can I 'reference'", or "I'm writing a paper on it, what do I put in the bibliography") and   H (2) propose an "incremental extension" to it, which might take "exactly"J the form of Chuck Forsberg's YAM protocol.  He wrote YAM in C for CP/M andH put it in the public domain, and wrote a batch protocol for Unix3 calledF rb and sb (receive batch, send batch), which was basically XMODEM with8    (a) a record 0 containing filename date time and size    (b) a 1K block size option     (c) CRC-16.  H He did some clever programming to detect false ACK or EOT, but basically left them the same.   F People who suggest I make SIGNIFICANT changes to the protocol, such asJ "full duplex", "multiple outstanding blocks", "multiple destinations", etcJ etc don't understand that the incredible simplicity of the protocol is oneJ of the reasons it survived to this day in as many machines and programs as it may be found in!   J Consider the PC-NET group back in '77 or so - documenting to beat the bandJ - THEY had a protocol, but it was "extremely complex", because it tried toI be "all things to all people" - i.e. send binary files on a 7-bit system, J etc.  I was not that "benevolent". I (emphasize > I < ) had an 8-bit UART,    
 __________    2. Infoworld April 29 p. 16  :  3. VAX/VMS versions of these programs are also available.        	 Chapter 2               J X/YMODEM Protocol Reference      10-10-85                                5      G so "my protocol was an 8-bit protocol", and I would just say "sorry" to 4 people who were held back by 7-bit limitations.  ...  F Block size: Chuck Forsberg created an extension of my protocol, calledD YAM, which is also supported via his public domain programs for UNIXF called rb and sb - receive batch and send batch.  They cleverly send a< "block 0" which contains the filename, date, time, and size.H Unfortunately, its UNIX style, and is a bit weird4 - octal numbers, etc.I BUT, it is a nice way to overcome the kludgy "echo the chars of the name" C introduced with MODEM7.  Further, chuck uses CRC-16 and optional 1K D blocks.  Thus the record 0, 1K, and CRC, make it a "pretty slick new; protocol" which is not significantly different from my own.   I Also, there is a catchy name - YMODEM.  That means to some that it is the B "next thing after XMODEM", and to others that it is the Y(am)MODEME protocol.  I don't want to emphasize that too much - out of fear that F other mfgrs might think it is a "competitive" protocol, rather than anD "unaffiliated" protocol.  Chuck is currently selling a much-enhancedJ version of his CP/M-80 C program YAM, calling it Professional Yam, and itsF for the PC - I'm using it right now.  VERY slick!  32K capture buffer,J script, scrolling, previously captured text search, plus built-in commandsG for just about everything - directory (sorted every which way), XMODEM, H YMODEM, KERMIT, and ASCII file upload/download, etc.  You can program itG to "behave" with most any system - for example when trying a number for F CIS it detects the "busy" string back from the modem and substitutes aA diff phone # into the dialing string and branches back to try it.         3.  XMODEM PROTOCOL ENHANCEMENTS  I This chapter discusses the protocol extensions to Ward Christensen's 1982 % XMODEM protocol description document.   E The original document recommends the user be asked wether to continue B trying or abort after 10 retries.  Most programs no longer ask theG operator whether he wishes to keep retrying.  Virtually all correctable J errors are corrected within the first few retransmissions.  If the line isH so bad that ten attempts are insufficient, there is a significant dangerD of undetected errors.  If the connection is that bad, it's better to6 redial for a better connection, or mail a floppy disk.          
 __________  H  4. The file length, time, and file mode are optional.  The pathname and-     file length may be sent alone if desired.         J Chapter 3                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                                6       3.1  Graceful Abort   I YAM and Professional-YAM recognize a sequence of two consecutive CAN (Hex J 18) characters without modem errors (overrun, framing, etc.) as a transferF abort command.1 The check for two consecutive CAN characters virtuallyJ eliminates the possibility of a line hit aborting the transfer.  YAM sendsD five CAN characters when it aborts an XMODEM or YMODEM protocol fileG transfer, followed by five backspaces to delete the CAN characters from J the remote's keyboard input buffer (in case the remote had already aborted the transfer).     3.2  CRC-16 Option  H The XMODEM protocol uses an optional two character CRC-16 instead of theF one character arithmetic checksum used by the original protocol and byD most commercial implementations.  CRC-16 guarantees detection of allE single and double bit errors,  all errors with an odd number of error I bits, all burst errors of length 16 or less, 99.9969% of all 17-bit error E bursts, and 99.9984 per cent of all possible longer error bursts.  By J contrast, a double bit error, or a burst error of 9 bits or more can sneak- past the XMODEM protocol arithmetic checksum.   J The XMODEM/CRC protocol is similar to the XMODEM protocol, except that theC receiver specifies CRC-16 by sending C (Hex 43) instead of NAK when H requesting the FIRST packet.  A two byte CRC is sent in place of the one byte arithmetic checksum.   H YAM's c option to the r command enables CRC-16 in single file reception,A corresponding to the original implementation in the MODEM7 series J programs.  This remains the default because many commercial communications@ programs and bulletin board systems still do not support CRC-16,, especially those written in Basic or Pascal.  F XMODEM protocol with CRC is accurate provided both sender and receiverE both report a successful transmission.  The protocol is robust in the I presence of characters lost by buffer overloading on timesharing systems.   I The single character ACK/NAK responses generated by the receiving program I adapt well to split speed modems, where the reverse channel is limited to 1 ten per cent or less of the main channel's speed.   C XMODEM and YMODEM are half duplex protocols which do not attempt to G transmit information and control signals in both directions at the same     
 __________  H  1. This is recognized when YAM is waiting for the beginning of a packet4     or for an acknowledge to one that has been sent.        J Chapter 3                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                                7      E time.  This avoids buffer overrun problems that have been reported by A users attempting to exploit full duplex aynchronous file transfer  protocols such as Blast.  H Professional-YAM adds several proprietary logic enhancements to XMODEM'sF error detection and recovery.  These compatible enhancements eliminateH most of the bad file transfers other programs make when using the XMODEM* protocol under less than ideal conditions.     3.3  1024 Byte Packet Option  J The choice to use 1024 byte packets is expressed to the sending program on# its command line or selection menu.   H Programs using the Hoff protocol use a two character sequence emitted byJ the receiver (CK) to automatically trigger the use of 1024 byte packets asH an alternative to specifying this option on this command line.  AlthoughI this two character sequence works well on single process micros in direct C communication, timesharing systems and packet switched networks can E separate the successive characters by several seconds, rendering this  method unreliable.  E An STX (02) replaces the SOH (01) at the beginning of the transmitted J block to notify the receiver of the longer packet length.  The transmittedJ packet contains 1024 bytes of data.  The receiver should be able to accept? any mixture of 128 and 1024 byte packets.  The packet number is C incremented by one for each packet regardless of the packet length.   I The sender must not change between 128 and 1024 byte packet lengths if it H has not received a valid ACK for the current packet.  Failure to observeG this restriction allows certain transmission errors to pass undetected.   H If 1024 byte packets are being used, it is possible for a file to "grow"I up to the next multiple of 1024 bytes.  This does not waste disk space if H the allocation granularity is 1k or greater.  When 1024 byte packets areG used with YMODEM batch transmission, the file length transmitted in the G file name packet allows the receiver to discard the padding, preserving # the exact file length and contents.   G CRC-16 should be used with the k option to preserve data integrity over H phone lines.2 1024 byte packets may be used with batch file transmission! or with single file transmission.         
 __________  .  2. Some programs enforce this recommendation.        J Chapter 3                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                                8      &           Figure 1.  1024 byte Packets  :           SENDER                                  RECEIVER@                                                   "s -k foo.bar"$           "foo.bar open x.x minutes"3                                                   C &           STX 01 FE Data[1024] CRC CRC5                                                   ACK &           STX 02 FD Data[1024] CRC CRC5                                                   ACK 1           STX 03 FC Data[1000] CPMEOF[24] CRC CRC 5                                                   ACK 
           EOT 5                                                   ACK   4           Figure 2.  Mixed 1024 and 128 byte Packets  :           SENDER                                  RECEIVER@                                                   "s -k foo.bar"$           "foo.bar open x.x minutes"3                                                   C &           STX 01 FE Data[1024] CRC CRC5                                                   ACK &           STX 02 FD Data[1024] CRC CRC5                                                   ACK %           SOH 03 FC Data[128] CRC CRC 5                                                   ACK 0           SOH 04 FB Data[100] CPMEOF[28] CRC CRC5                                                   ACK 
           EOT 5                                                   ACK   " 4.  YMODEM Batch File Transmission  I The YMODEM Batch protocol is an extension to the XMODEM/CRC protocol that F allows 0 or more files to be transmitted with a single command.  (ZeroD files may be sent if none of the requested files is accessible.) TheJ design approach of the YMODEM Batch protocol is to use the normal routinesH for sending and receiving XMODEM packets in a layered fashion similar to packet switching methods.e  D Why was it necessary to design a new batch protocol when one alreadyD existed in MODEM7?1 The batch file mode used by MODEM7 is unsuitable    
 __________  D  1. The MODEM7 batch protocol transmitted CP/M FCB bytes f1...f8 andH     t1...t3 one character at a time.  The receiver echoed these bytes as     received, one at a time.        J Chapter 4                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                                9      E because it does not permit full pathnames, file length, file date, orrJ other attribute information to be transmitted.  Such a restrictive design,D hastily implemented with only CP/M in mind, would not have permittedH extensions to current areas of personal computing such as Unix, DOS, andD object oriented systems.  In addition, the MODEM7 batch file mode is1 somewhat susceptible to transmission impairments.i  F As in the case of single a file transfer, the receiver initiates batch: file transmission by sending a "C" character (for CRC-16).  B The sender opens the first file and sends packet number 0 with the following information.2C  C Only the pathname (file name) part is required for batch transfers.n  G To maintain upwards compatibility, all unused bytes in packet 0 must beo set to null.  G Pathname The pathname (conventionally, the file name) is sent as a null F      terminated ASCII string.  This is the filename format used by theG      handle oriented MSDOS(TM) functions and C library fopen functions.e*      An assembly language example follows:1                               DB      'foo.bar',0oI      No spaces are included in the pathname.  Normally only the file nameeD      stem (no directory prefix) is transmitted unless the sender hasI      selected YAM's f option to send the full pathname.  The source driveT"      (A:, B:, etc.) is never sent.        Filename Considerations:p  J         + File names should be translated to lower case unless the sendingA           system supports upper/lower case file names.  This is atE           convenience for users of systems (such as Unix) which storeg,           filenames in upper and lower case.  G         + The receiver should accommodate file names in lower and upper            case.w  C         + The rb(1) program on Unix systems normally translates theaB           filename to lower case unless one or more letters in the-           filename are already in lower case.-  F         + When transmitting files between different operating systems,H           file names must be acceptable to both the sender and receiving           operating systems.    
 __________  7  2. Only the data part of the packet is described here.         J Chapter 4                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                               10      @      If directories are included, they are delimited by /; i.e.,5      "subdir/foo" is acceptable, "subdir\foo" is not.h  G Length The file length and each of the succeeding fields are optional.3eJ      The length field is stored in the packet as a decimal string countingD      the number of data bytes in the file.  The file length does notD      include any CPMEOF (^Z) characters used to pad the last packet.  F      If the file being transmitted is growing during transmission, theC      length field should be set to at least the final expected files      length, or not sent.c  G      The receiver stores the specified number of characters, discardingB@      any padding added by the sender to fill up the last packet.  I Modification Date A single space separates the modification date from then      file length.s  F      The mod date is optional, and the filename and length may be sent/      without requiring the mod date to be sent.   I      The mod date is sent as an octal number giving the time the contentscF      of the file were last changed measured in seconds from Jan 1 1970?      Universal Coordinated Time (GMT).  A date of 0 implies theiI      modification date is unknown and should be left as the date the filee      is received.M  J      This standard format was chosen to eliminate ambiguities arising from,      transfers between different time zones.  G      Two Microsoft blunders complicate the use of modification dates in E      file transfers with MSDOS(TM) systems.  The first is the lack ofoH      timezone standardization in MS-DOS.  A file's creation time can notG      be known unless the timezone of the system that wrote the file4 is/C      known.  Unix solved this problem (for planet Earth, anyway) by G      stamping files with Universal Time (GMT).  Microsoft would have toiF      include the timezone of origin in the directory entries, but doesC      not.  Professional-YAM gets around this problem by using the zyI      parameter which is set to the number of minutes local time lags GMT. D      For files known to originate from a different timezone, the -zTF      option may be used to specify T as the timezone for an individual      file transfer./      
 __________    3. Fields may not be skipped.  4  4. Not necessarily that of the transmitting system!        J Chapter 4                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                               11      G      The second problem is the lack of a separate file creation date incC      DOS.  Since some backup schemes used with DOS rely on the fileeE      creation date to select files to be copied to the archive, back-bI      dating the file modification date could interfere with the safety ofhG      the transferred files.  For this reason, Professional-YAM does notmI      modify the date of received files with the header information unlessl!      the d parameter is non zero.K    G Mode A single space separates the file mode from the modification date.NA      The file mode is stored as an octal string.  Unless the fileoE      originated from a Unix system, the file mode is set to 0.  rb(1)tH      checks the file mode for the 0x8000 bit which indicates a Unix typeJ      regular file.  Files with the 0x8000 bit set are assumed to have beenH      sent from another Unix (or similar) system which uses the same file<      conventions.  Such files are not translated in any way.    F Serial Number A single space separates the serial number from the fileI      mode.  The serial number of the transmitting program is stored as an J      octal string.  Programs which do not have a serial number should omitE      this field, or set it to 0.  The receiver's use of this field is       optional.  F The rest of the packet is set to nulls.  This is essential to preserveI upward compatibility.5 After the filename packet has been received, it is"D ACK'ed if the write open is successful.  The receiver then initiatesB transfer of the file contents according to the standard XMODEM/CRCI protocol.  If the file cannot be opened for writing, the receiver cancels 4 the transfer with CAN characters as described above.  J After the file contents have been transmitted, the receiver again asks forI the next pathname.  Transmission of a null pathname terminates batch filesG transmission.  Note that transmission of no files is not necessarily ancE error.  This is possible if none of the files requested of the senderT could be opened for reading.  B In batch transmission, the receiver automatically requests CRC-16.  B The Unix programs sb(1) and rb(1) included in the source code fileC RBSB.SHQ (rbsb.sh) should answer other questions about YMODEM batchs	 protocol.       
 __________  F  5. If, perchance, this information extends beyond 128 bytes (possibleJ     with Unix 4.2 BSD extended file names), the packet should be sent as a!     1k packet as described above.y        J Chapter 4                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                               12      /           Figure 3.  Batch Transmission Sessions  :           SENDER                                  RECEIVER@                                                   "sb foo.*<CR>"&           "sending in batch mode etc."@                                                   C (command:rb)*           SOH 00 FF foo.c NUL[123] CRC CRC5                                                   ACKh3                                                   C %           SOH 01 FE Data[128] CRC CRCs5                                                   ACKs&           SOH 02 FD Data[1024] CRC CRC5                                                   ACKu%           SOH 03 FC Data[128] CRC CRCg5                                                   ACKk0           SOH 04 FB Data[100] CPMEOF[28] CRC CRC5                                                   ACKi
           EOT 5                                                   NAKp
           EOTi5                                                   ACKs3                                                   Ci$           SOH 00 FF NUL[128] CRC CRC5                                                   ACKt  3        Figure 4.  Filename packet transmitted by sb   6        -rw-r--r--  6347 Jun 17 1984 20:34 bbcsched.txt  B        00 0100FF62 62637363 6865642E 74787400   |...bbcsched.txt.|B        10 36333437 20333331 34373432 35313320   |6347 3314742513 |B        20 31303036 34340000 00000000 00000000   |100644..........|-        30 00000000 00000000 00000000 00000000u        80 000000CA 56r                                        J Chapter 4                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                               13      C        Figure 5.  Header Information used by YMODEM Implementationsi    E _____________________________________________________________________ F | Program   | Batch | Length | Date | Mode | S/N | 1k-Blk | g-Option |F |___________|_______|________|______|______|_____|________|__________|F |Unix rb/sb | yes   | yes    | yes  | yes  | no  | yes    | sb only  |F |___________|_______|________|______|______|_____|________|__________|F |VMS rb/sb  | yes   | yes    | no   | no   | no  | yes    | no       |F |___________|_______|________|______|______|_____|________|__________|F |Pro-YAM    | yes   | yes    | yes  | no   | yes | yes    | yes      |F |___________|_______|________|______|______|_____|________|__________|F |CP/M YAM   | yes   | no     | no   | no   | no  | yes    | no       |F |___________|_______|________|______|______|_____|________|__________|F |KMD/IMP    | yes   | no     | no   | no   | no  | yes    | no       |F |___________|_______|________|______|______|_____|________|__________|F |MEX        | no    | no     | no   | no   | no  | yes    | no       |F |___________|_______|________|______|______|_____|________|__________|   4.1  IMP/KMD Record Countm  J Due to programming constraints, these programs do not send the file lengthF as described above.  Instead, they send (and look for) the CP/M recordC count stored in the last two bytes of the header packet.  The leasta4 significant bits are stored in the penultimate byte.  J KMD and IMP use the record count to allow the receiving program to displayA the file size and estimated transmission time; the file length is 0 determined by the actual number of records sent.     5.  g Option File Transmission  G Developing technology is providing phone line data transmission at evereJ higher speeds using very specialized techniques.  These high speed modems,I as well as session protocols such as X.PC, provide high speed, error freeiC communications at the expense of considerably increased delay time._  B This delay time is moderate compared to human interactions, but it; cripples the throughput of most error correcting protocols.n  F The g option to YMODEM has proven effective under these circumstances.J The g option is driven by the receiver, which initiates the batch transferG by transmitting a G instead of C.  When the sender recognizes the G, itrF bypasses the usual wait for an ACK to each transmitted packet, sendingC succeeding packets at full speed, subject to XOFF/XON or other flown control exerted by the medium.  @ The sender expects an inital G to initiate the transmission of aF particular file, and also expects an ACK on the EOT sent at the end ofE each file.  This synchronization allows the receiver time to open andn      J Chapter 5                                     XMODEM Protocol Enhancements              J X/YMODEM Protocol Reference      10-10-85                               14       close files as necessary.c    0         Figure 6.  g Option Transmission Session  8         SENDER                                  RECEIVER>                                                 "sb foo.*<CR>"&         "sending in batch mode etc..."A                                                 G (command:rb -g)s(         SOH 00 FF foo.c NUL[123] CRC CRC1                                                 G,#         SOH 01 FE Data[128] CRC CRC $         SOH 02 FD Data[1024] CRC CRC#         SOH 03 FC Data[128] CRC CRCl.         SOH 04 FB Data[100] CPMEOF[28] CRC CRC         EOTt3                                                 ACKr1                                                 G8"         SOH 00 FF NUL[128] CRC CRC     6.  XMODEM PROTOCOL OVERVIEW   8/9/82 by Ward Christensen.p  A I will maintain a master copy of this.  Please pass on changes oreI suggestions via CBBS/Chicago at (312) 545-8086, CBBS/CPMUG (312) 849-1132. or by voice at (312) 849-6279.   6.1  Definitions     <soh>    01H   <eot>    04H   <ack>    06H   <nak>    15H   <can>    18H   <C>      43H    ' 6.2  Transmission Medium Level Protocol   3 Asynchronous, 8 data bits, no parity, one stop bit.   F The protocol imposes no restrictions on the contents of the data beingG transmitted.  No control characters are looked for in the 128-byte dataeH messages.  Absolutely any kind of data may be sent - binary, ASCII, etc.I The protocol has not formally been adopted to a 7-bit environment for the H transmission of ASCII-only (or unpacked-hex) data , although it could beH simply by having both ends agree to AND the protocol-dependent data withJ 7F hex before validating it.  I specifically am referring to the checksum,1 and the block numbers and their ones- complement.P      J Chapter 6                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               15      H Those wishing to maintain compatibility of the CP/M file structure, i.e.I to allow modemming ASCII files to or from CP/M systems should follow this  data format:  -    + ASCII tabs used (09H); tabs set every 8.   (    + Lines terminated by CR/LF (0DH 0AH)  5    + End-of-file indicated by ^Z, 1AH.  (one or more)   D    + Data is variable length, i.e. should be considered a continuousE      stream of data bytes, broken into 128-byte chunks purely for the       purpose of transmission.   A    + A CP/M "peculiarity": If the data ends exactly on a 128-byte A      boundary, i.e. CR in 127, and LF in 128, a subsequent sector F      containing the ^Z EOF character(s) is optional, but is preferred.I      Some utilities or user programs still do not handle EOF without ^Zs.e  G    + The last block sent is no different from others, i.e.  there is no       "short block".2<               Figure 7.  XMODEM Message Block Level Protocol  & Each block of the transfer looks like:8       <SOH><blk #><255-blk #><--128 data bytes--><cksum>	 in which:  <SOH>         = 01 hex@ <blk #>       = 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.8                 Formally, this is the "ones complement".@ <cksum>       = the sum of the data bytes only.  Toss any carry.   6.3  File Level Protocol  ) 6.3.1  Common_to_Both_Sender_and_ReceiversG All errors are retried 10 times.  For versions running with an operatorfE (i.e. NOT with XMODEM), a message is typed after 10 errors asking then$ operator whether to "retry or quit".  J Some versions of the protocol use <can>, ASCII ^X, to cancel transmission.J This was never adopted as a standard, as having a single "abort" characterG makes the transmission susceptible to false termination due to an <ack>tH <nak> or <soh> being corrupted into a <can> and cancelling transmission.  J The protocol may be considered "receiver driven", that is, the sender need> not automatically re-transmit, although it does in the current implementations.          J Chapter 6                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               16      % 6.3.2  Receive_Program_Considerations E The receiver has a 10-second timeout.  It sends a <nak> every time it J times out.  The receiver's first timeout, which sends a <nak>, signals theB transmitter to start.  Optionally, the receiver could send a <nak>J immediately, in case the sender was ready.  This would save the initial 10H second timeout.  However, the receiver MUST continue to timeout every 10( seconds in case the sender wasn't ready.  J Once into a receiving a block, the receiver goes into a one-second timeoutG for each character and the checksum.  If the receiver wishes to <nak> atF block for any reason (invalid header, timeout receiving data), it must= wait for the line to clear.  See "programming tips" for idease  G Synchronizing:  If a valid block number is received, it will be: 1) theiE expected one, in which case everything is fine; or 2) a repeat of thelB previously received block.  This should be considered OK, and onlyC indicates that the receivers <ack> got glitched, and the sender re- @ transmitted; 3) any other block number indicates a fatal loss ofJ synchronization, such as the rare case of the sender getting a line-glitchC that looked like an <ack>.  Abort the transmission, sending a <can>l    % 6.3.3  Sending_program_considerations:J While waiting for transmission to begin, the sender has only a single veryH long timeout, say one minute.  In the current protocol, the sender has aI 10 second timeout before retrying.  I suggest NOT doing this, and letting I the protocol be completely receiver-driven.  This will be compatible withp existing programs.  I When the sender has no more data, it sends an <eot>, and awaits an <ack>, H resending the <eot> if it doesn't get one.  Again, the protocol could beD receiver-driven, with the sender only having the high-level 1-minute timeout to abort.     J Here is a sample of the data flow, sending a 3-block message.  It includesD the two most common line hits - a garbaged block, and an <ack> reply5 getting garbaged.  <xx> represents the checksum byte.n                                J Chapter 6                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               17      ;               Figure 8.  Data flow including Error Recovery   0 SENDER                                  RECEIVER9                               times out after 10 seconds,o5                               <---              <nak>c" <soh> 01 FE -data- <xx>       --->5                               <---              <ack>s= <soh> 02 FD -data- xx         --->       (data gets line hit) 5                               <---              <nak>a" <soh> 02 FD -data- xx         --->5                               <---              <ack>t" <soh> 03 FC -data- xx         --->5 (ack gets garbaged)           <---              <ack> 5 <soh> 03 FC -data- xx         --->              <ack>s" <eot>                         --->>                               <---       <anything except ack>" <eot>                         --->5                               <---              <ack> 
 (finished)   6.4  Programming Tipss  G    + The character-receive subroutine should be called with a parametertI      specifying the number of seconds to wait.  The receiver should firstvC      call it with a time of 10, then <nak> and try again, 10 times.e  F      After receiving the <soh>, the receiver should call the characterI      receive subroutine with a 1-second timeout, for the remainder of theaJ      message and the <cksum>.  Since they are sent as a continuous stream,G      timing out of this implies a serious like glitch that caused, say,e.      127 characters to be seen instead of 128.  @    + When the receiver wishes to <nak>, it should call a "PURGE"I      subroutine, to wait for the line to clear.  Recall the sender tossesoJ      any characters in its UART buffer immediately upon completing sending:      a block, to ensure no glitches were mis- interpreted.  C      The most common technique is for "PURGE" to call the charactereI      receive subroutine, specifying a 1-second timeout,1 and looping backmG      to PURGE until a timeout occurs.  The <nak> is then sent, ensuringa      the other end will see it.   H    + You may wish to add code recommended by John Mahr to your characterE      receive routine - to set an error flag if the UART shows framingnG      error, or overrun.  This will help catch a few more glitches - then    
 __________  D  1. These times should be adjusted for use with timesharing systems.        J Chapter 6                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               18      F      most common of which is a hit in the high bits of the byte in twoJ      consecutive bytes.  The <cksum> comes out OK since counting in 1-byteF      produces the same result of adding 80H + 80H as with adding 00H +	      00H.t       7.  XMODEM/CRC Overviewk  $ 1/13/85 by John Byrns -- CRC option.  H Please pass on any reports of errors in this document or suggestions forI improvement to me via Ward's/CBBS at (312) 849-1132, or by voice at (312)s	 885-1105.e  F The CRC used in the Modem Protocol is an alternate form of block checkF which provides more robust error detection than the original checksum.F Andrew S. Tanenbaum says in his book, Computer Networks, that the CRC-F CCITT used by the Modem Protocol will detect all single and double bitI errors, all errors with an odd number of bits, all burst errors of lengthrE 16 or less, 99.997% of 17-bit error bursts, and 99.998% of 18-bit andn longer bursts.  J The changes to the Modem Protocol to replace the checksum with the CRC areF straight forward. If that were all that we did we would not be able toE communicate between a program using the old checksum protocol and onetH using the new CRC protocol. An initial handshake was added to solve thisH problem. The handshake allows a receiving program with CRC capability toE determine whether the sending program supports the CRC option, and to G switch it to CRC mode if it does. This handshake is designed so that itiB will work properly with programs which implement only the originalE protocol. A description of this handshake is presented in section 10.r  =             Figure 9.  Message Block Level Protocol, CRC modec  2 Each block of the transfer in CRC mode looks like:@      <SOH><blk #><255-blk #><--128 data bytes--><CRC hi><CRC lo>	 in which:  <SOH>        = 01 hexb? <blk #>      = binary number, starts at 01 increments by 1, and ,                wraps 0FFH to 00H (not to 01)( <255-blk #>  = ones complement of blk #.F <CRC hi>     = byte containing the 8 hi order coefficients of the CRC.F <CRC lo>     = byte containing the 8 lo order coefficients of the CRC.   7.1  CRC Calculation   7.1.1  Formal_DefinitionE To calculate the 16 bit CRC the message bits are considered to be theoI coefficients of a polynomial. This message polynomial is first multipliedEI by X^16 and then divided by the generator polynomial (X^16 + X^12 + X^5 +o      J Chapter 7                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               19      H 1) using modulo two arithmetic. The remainder left after the division isI the desired CRC. Since a message block in the Modem Protocol is 128 bytes J or 1024 bits, the message polynomial will be of order X^1023. The hi orderJ bit of the first byte of the message block is the coefficient of X^1023 inI the message polynomial.  The lo order bit of the last byte of the message : block is the coefficient of X^0 in the message polynomial.  >            Figure 10.  Example of CRC Calculation written in C   /*C  * This function calculates the CRC used by the XMODEM/CRC Protocol 8  * The first argument is a pointer to the message block.C  * The second argument is the number of bytes in the message block.a:  * The function returns an integer which contains the CRC.9  * The low order 16 bits are the coefficients of the CRC.   */  int calcrc(ptr, count)
 char *ptr;
 int count; {      int crc, i;1       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); }]  $ 7.2  CRC File Level Protocol Changes  ) 7.2.1  Common_to_Both_Sender_and_Receiver D The only change to the File Level Protocol for the CRC option is theH initial handshake which is used to determine if both the sending and theJ receiving programs support the CRC mode. All Modem Programs should supportE the checksum mode for compatibility with older versions.  A receiving.F program that wishes to receive in CRC mode implements the mode settingI handshake by sending a <C> in place of the initial <nak>.  If the sending G program supports CRC mode it will recognize the <C> and will set itselfoG into CRC mode, and respond by sending the first block as if a <nak> had G been received. If the sending program does not support CRC mode it will_J not respond to the <C> at all. After the receiver has sent the <C> it willE wait up to 3 seconds for the <soh> that starts the first block. If it_H receives a <soh> within 3 seconds it will assume the sender supports CRCH mode and will proceed with the file exchange in CRC mode. If no <soh> isI received within 3 seconds the receiver will switch to checksum mode, sende      J Chapter 7                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               20      D a <nak>, and proceed in checksum mode. If the receiver wishes to useE checksum mode it should send an initial <nak> and the sending program F should respond to the <nak> as defined in the original Modem Protocol.D After the mode has been set by the initial <C> or <nak> the protocolI follows the original Modem Protocol and is identical whether the checksum| or CRC is being used.M    % 7.2.2  Receive_Program_ConsiderationsnC There are at least 4 things that can go wrong with the mode setting|
 handshake.  -   1.  the initial <C> can be garbled or lost.u  '   2.  the initial <soh> can be garbled.s  0   3.  the initial <C> can be changed to a <nak>.  J   4.  the initial <nak> from a receiver which wants to receive in checksum       can be changed to a <C>.  H The first problem can be solved if the receiver sends a second <C> afterH it times out the first time. This process can be repeated several times.A It must not be repeated too many times before sending a <nak> andnG switching to checksum mode or a sending program without CRC support mayiI time out and abort. Repeating the <C> will also fix the second problem ifeH the sending program cooperates by responding as if a <nak> were received" instead of ignoring the extra <C>.  I It is possible to fix problems 3 and 4 but probably not worth the troublefI since they will occur very infrequently. They could be fixed by switchingdI modes in either the sending or the receiving program after a large numbercF of successive <nak>s. This solution would risk other problems however.    % 7.2.3  Sending_Program_ConsiderationsbG The sending program should start in the checksum mode. This will insurenE compatibility with checksum only receiving programs. Anytime a <C> iswG received before the first <nak> or <ack> the sending program should set H itself into CRC mode and respond as if a <nak> were received. The senderH should respond to additional <C>s as if they were <nak>s until the firstH <ack> is received. This will assist the receiving program in determiningI the correct mode when the <soh> is lost or garbled. After the first <ack> 3 is received the sending program should ignore <C>s.P                    J Chapter 7                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               21      ' 7.3  Data Flow Examples with CRC Option   D Here is a data flow example for the case where the receiver requestsD transmission in the CRC mode but the sender does not support the CRCE option. This example also includes various transmission errors.  <xx>F represents the checksum byte.   D       Figure 11.  Data Flow: Receiver has CRC Option, Sender Doesn't  6 SENDER                                        RECEIVER/                         <---                <C>a:                                 times out after 3 seconds,/                         <---                <C> :                                 times out after 3 seconds,/                         <---                <C> :                                 times out after 3 seconds,/                         <---                <C>n:                                 times out after 3 seconds,1                         <---                <nak>t <soh> 01 FE -data- <xx> --->1                         <---                <ack> 8 <soh> 02 FD -data- <xx> --->        (data gets line hit)1                         <---                <nak>n <soh> 02 FD -data- <xx> --->1                         <---                <ack>b <soh> 03 FC -data- <xx> --->1    (ack gets garbaged)  <---                <ack>e;                                 times out after 10 seconds,C1                         <---                <nak>d <soh> 03 FC -data- <xx> --->1                         <---                <ack>t <eot>                   --->1                         <---                <ack>p  D Here is a data flow example for the case where the receiver requestsJ transmission in the CRC mode and the sender supports the CRC option.  ThisI example also includes various transmission errors.  <xxxx> represents thei 2 CRC bytes.                                J Chapter 7                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               22      ?            Figure 12.  Receiver and Sender Both have CRC Options  5 SENDER                                       RECEIVERC2                           <---                 <C> <soh> 01 FE -data- <xxxx> --->4                           <---                 <ack>; <soh> 02 FD -data- <xxxx> --->         (data gets line hit)s4                           <---                 <nak> <soh> 02 FD -data- <xxxx> --->4                           <---                 <ack> <soh> 03 FC -data- <xxxx> --->4 (ack gets garbaged)       <---                 <ack>@                                      times out after 10 seconds,4                           <---                 <nak> <soh> 03 FC -data- <xxxx> --->4                           <---                 <ack> <eot>                     --->4                           <---                 <ack>     8.  MORE INFORMATION  I More information may be obtained by calling Telegodzilla at 503-621-3746. $ Hit RETURNs for baud rate detection.  D A version this file with boldface, underlining, and superscripts forD printing on Epson or Gemini printers is available on Telegodzilla as "YMODEME.DOC" or "YMODEME.DQC".c  $ UUCP sites can obtain this file with<              uucp omen!/usr/spool/uucppublic/ymodem.doc /tmp  H The following L.sys line calls Telegodzilla (Pro-YAM in host operation).H Telegodzilla waits for carriage returns to determine the incoming speed.E If none is detected, 1200 bps is assumed and a greeting is displayed.i  J In response to "Name Please:" uucico gives the Pro-YAM "link" command as aF user name.  The password (Giznoid) controls access to the Xenix systemD connected to the IBM PC's other serial port.  Communications betweenH Pro-YAM and Xenix use 9600 bps; YAM converts this to the caller's speed.  , Finally, the calling uucico logs in as uucp.  I omen Any ACU 1200 1-503-621-3746 se:--se: link ord: Giznoid in:--in: uucpb  / Contact omen!caf if you wish the troff sources.                 J Chapter 9                                         Xmodem Protocol Overview              J X/YMODEM Protocol Reference      10-10-85                               23       9.  YMODEM Programse  J A demonstration version of Professional-YAM is available as YAMDEMO.LQR (A? SQueezed Novosielski library).  This may be used to test YMODEMe implementations.  J Unix programs supporting the YMODEM protocol are available on TelegodzillaE in the "upgrade" subdirectory as RBSB.SHQ (a SQueezed shell archive).aI Most Unix like systems are supported, including V7, Sys III, 4.2 BSD, SYS   V, Idris, Coherent, and Regulus.  G A version for VAX-VMS is available in VRBSB.SHQ, in the same directory.'  C A CP/M assembly version is available as MODEM76.AQM and MODEM7.LIB.-  J Irv Hoff has added YMODEM 1k packets and YMODEM batch transfers to the KMDJ and IMP series programs, which replace the XMODEM and MODEM7/MDM7xx seriesI respectively.  Overlays are available for a wide variety of CP/M systems.y  : MEX and MEX-PC also support some of the YMODEM extensions.  H Questions about YMODEM, the Professional-YAM communications program, and2 requests for evaluation copies may be directed to:      Chuck Forsberg       Omen Technology Inc      17505-V Sauvie Island Roadn      Portland Oregon 97231      Voice: 503-621-3406(      Modem: 503-621-3746 Speed: 1200,300(      Usenet: ...!tektronix!reed!omen!caf      Compuserve: 70715,131      Source: TCE022h                                            J Chapter 9                                         Xmodem Protocol Overview                      )                                  CONTENTSI    J 1.  ROSETTA STONE.....................................................   2  J 2.  YET ANOTHER PROTOCOL?.............................................   2J     2.1  Some Messages from the Pioneer...............................   4  J 3.  XMODEM PROTOCOL ENHANCEMENTS......................................   5J     3.1  Graceful Abort...............................................   6J     3.2  CRC-16 Option................................................   6J     3.3  1024 Byte Packet Option......................................   7  J 4.  YMODEM Batch File Transmission....................................   8J     4.1  IMP/KMD Record Count.........................................  13  J 5.  g Option File Transmission........................................  13  J 6.  XMODEM PROTOCOL OVERVIEW..........................................  14J     6.1  Definitions..................................................  14J     6.2  Transmission Medium Level Protocol...........................  14J     6.3  File Level Protocol..........................................  15J     6.4  Programming Tips.............................................  17  J 7.  XMODEM/CRC Overview...............................................  18J     7.1  CRC Calculation..............................................  18J     7.2  CRC File Level Protocol Changes..............................  19J     7.3  Data Flow Examples with CRC Option...........................  21  J 8.  MORE INFORMATION..................................................  22  J 9.  YMODEM Programs...................................................  23                                            '                                   - i -                             ,                              LIST OF FIGURES    J  Figure 1.  1024 byte Packets.........................................   7  J  Figure 2.  Mixed 1024 and 128 byte Packets...........................   7  J  Figure 3.  Batch Transmission Session................................  11  J  Figure 4.  Filename packet transmitted by sb.........................  11  J  Figure 5.  Header Information used by YMODEM Implementations.........  13  J  Figure 6.  g Option Transmission Session.............................  14  J  Figure 7.  XMODEM Message Block Level Protocol.......................  15  J  Figure 8.  Data flow including Error Recovery........................  17  J  Figure 9.  Message Block Level Protocol, CRC mode....................  18  J Figure 10.  Example of CRC Calculation written in C...................  19  J Figure 11.  Data Flow: Receiver has CRC Option, Sender Doesn't........  21  J Figure 12.  Receiver and Sender Both have CRC Option..................  22                                                  (                                   - ii -         .  YMODEM Programs  D A demonstration version of Professional-YAM is available as YAMDEMO.   DL 4 - General Programming :