├── README.md ├── doc ├── DSZ.TXT ├── readme.zmodem.doc ├── sexyz.txt ├── xymodem.pdf ├── zmodem.doc └── zmodem.txt ├── fymodem.c ├── fymodem.h └── makefile /README.md: -------------------------------------------------------------------------------- 1 | fymodem 2 | ======= 3 | 4 | Free YModem implementation. 5 | -------------------------------------------------------------------------------- /doc/readme.zmodem.doc: -------------------------------------------------------------------------------- 1 | this file was abstracted from the original zmodem.doc after one 2 | night I decided I had enough of all this marketing hype and wanted 3 | to know what zmodem was all about without having to wade hip-deep 4 | through advertising slogans. this text is !(C) MCS 1994 5 | 6 | the intended audience of this document are programmers looking for 7 | a compact reference text on how zmodem works and what you should 8 | know to be able to implement conforming zmodem send and receive 9 | software. this is definitely not an 'end user' document and the 10 | examples and data structures are strongly biased towards the 'C' 11 | language. (what ? are there other languages ??) 12 | 13 | a lot of work went into the preparation of this document; although 14 | I'm afraid I can't guarantee it's correctness. Jacques Mattheij 15 | or MCS shall not be liable for any damages whatsoever. this file 16 | is provided 'as is' for no fee whatsoever. use is at your own risk. 17 | if these terms are unacceptable to you than delete these files NOW!. 18 | 19 | changes relative to zmodem.doc as provided by various sources: 20 | 21 | - removal of all historical information 22 | - removal of all plugs relating to omen technology products etc. 23 | if something is public domain then leave it at that 24 | - removal of all 'poetry' 25 | - removal of all references to xmodem ymodem kermit and so on 26 | - removal of all overstrike typesetting tricks which make this 27 | file practically uneditable and unviewable 28 | - removal of a lot of irrelevant but nice facts about the wheater and 29 | some other nice subjects for conversation 30 | - removal of all implementation specific details referring to those 31 | antiques of telecom 'rz' and 'sz' 32 | - manifest constants added in the text. 33 | - moved footnotes to the appropriate place in the text 34 | - changed number base from octal to hex (welcome to the nineties) 35 | admitted it looks less ivory tower but it reads a lot easier 36 | for those who started programming after 1959 37 | 38 | some recomendations.... 39 | 40 | a lot has changed since the original zmodem came out. not so much in the 41 | protocol as well as in the world around it. I would like to de-advertise 42 | several of zmodem's advanced features: 43 | 44 | - command sending. 45 | this is the hackers dream come true. a formalized backdoor into any 46 | site supporting this file transfer protocol with a relatively easy 47 | defeated security mechanism. don't implement it; just refuse it. 48 | 49 | - file translation. 50 | the zmodem protocol specification below contains a number of facilities 51 | to change a file between one os and the next. THIS IS NOT THE PLACE ! 52 | a file TRANSFER protocol should do just that and with a minimum of fuss. 53 | if you have to start worrying about wheter zmodem just garbled that 4MB 54 | zip file of yours just downloaded from the states at $1 a minute you're 55 | ready for some agression. another point may be that the file size will 56 | change which may give rise to a lot of bugs in zmodem implementations on 57 | the far side of wherever you are downloading to / from. stick to 58 | binary. it helps. 59 | 60 | - use CRC32 and not CRC16 61 | apart from the obvious (better error detection) the original CRC16 62 | implementation is buggy 63 | 64 | - do not send the serial number in the ZFILE frame. this is not a 65 | very useful function 66 | 67 | - in many places in the orignal zmodem.doc it was suggested that if 68 | this or that failed you should step down and attempt a ymodem 69 | transfer. don't do that ! users know pretty good what they want 70 | and if they specify a zmodem transfer give them one or give them 71 | nothing. don't try to be smart. probably something is wrong and it 72 | is better to exit with some informative message than to go ahead 73 | with the wrong protocol; apart from keeping your source clean. 74 | 75 | - don't use or implement the run length encoding. it is greatly 76 | hampered by not checking if run length encoding is needed. if 77 | you specify that ability you're stuck with it. nowadays with 78 | zip 2.0/unzip 5.0 and better there is absolutely no need for a file 79 | transfer protocol to busy itself with compression. for $200 80 | you can buy a mnp class 10 modem which does all that and more 81 | completely transparently without possibly triggering a host of 82 | bugs in a relatively little exercised part of your hosts software. 83 | 84 | - lzw encoding; see run length encoding. 85 | 86 | - don't use the 'ZXSPARSE' option. chances of finding a system that 87 | implements it are small and even then 10 : 1 that the file will 88 | be sent compressed. 89 | 90 | - don't send the 'rz\r' used in the original documentation. 91 | this is a very nasty way of making a public domain protocol 92 | dependant on a company. (sorry had to abide by that in the end; 93 | some implementations trigger auto downloads on this) 94 | 95 | In general; keep it simple ! stick to multiple file binary transfers and 96 | try to get some speed out of those boxes. time is spent well on optimizing 97 | and cleaning your source rather than on some obscure seldomely used 98 | feature which will clutter your code. 99 | 100 | Whenever I give an example of how not to program in 'C' I refer to the 101 | rz.c and sz.c sources. In more than one way these are true 'classics'. 102 | If you intend to implement zmodem don't bother with these dinosaurs 103 | (to use a popular term); better to write it clean from the start. 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | -------------------------------------------------------------------------------- /doc/sexyz.txt: -------------------------------------------------------------------------------- 1 | Synchronet External X/Y/ZMODEM (SEXYZ) File Transfer Protocol Driver 2 | -------------------------------------------------------------------- 3 | 4 | $Id: sexyz.txt,v 1.28 2014/12/11 10:27:34 rswindell Exp $ 5 | 6 | The live version of this document is online at: 7 | http://wiki.synchro.net/util:sexyz 8 | 9 | Overview 10 | -------- 11 | SEXYZ was developed as a native (32-bit) TCP/socket-based replacement for the 12 | 16-bit DOS file transfer drivers (e.g. FDSZ, CE-XYZ, etc.) that we've been 13 | stuck with on 32-bit BBSes for FAR too long. While SEXYZ was designed with 14 | Synchronet BBSes in mind, it should also work with other 32-bit BBS packages 15 | that have the ability to pass socket descriptors to external file transfer 16 | protocol drivers. 17 | 18 | SEXYZ behaves much like DSZ/FDSZ and CE-XYZ: 19 | 20 | o Familiar command-line syntax 21 | o Supports the DSZLOG environment variable for result logging 22 | o Supports batch transfer file lists 23 | 24 | SEXYZ has several advantages over legacy drivers like FDSZ and CE-XYZ: 25 | 26 | o Faster (native, multi-threaded design) 27 | o Socket-based (no need for FOSSIL drivers or virtual COM ports/UARTs) 28 | o Multi-tasking friendly (does not needlessly consume CPU cycles) 29 | o Supports long filenames (e.g. not just DOS "8.3" formatted names) 30 | o Supports YMODEM-G and XMODEM-G (FDSZ does not) 31 | o Handles Telnet IAC escaping and option negotiations (optionally) 32 | o Transfers files over fast connections (e.g. 100KB/sec) without issue 33 | o Actively developed and supported 34 | o Open source (at cvs.synchro.net)! 35 | 36 | 37 | Distribution 38 | ------------ 39 | SEXYZ is freeware, licensed under the GNU General Public License (GPL) 40 | http://www.fsf.org/licensing/licenses/gpl.txt 41 | with portions licensed under the GNU Lesser General Public License (LGPL) 42 | http://www.fsf.org/licensing/licenses/lgpl.txt. 43 | 44 | You can find the current source code (in C) in the CVS repository at 45 | cvs.synchro.net. 46 | 47 | The latest and greatest build will be included in Synchronet-Win32 releases. 48 | You should be able to find/download the latest general release of SEXYZ-Win32 49 | (sexyzNNN.zip) at one or all of the following locations: 50 | 51 | http://www.synchro.net 52 | ftp://ftp.synchro.net 53 | ftp://vert.synchro.net 54 | telnet://vert.synchro.net 55 | 56 | SEXYZ can also be built from the C source code for use (natively) on Linux 57 | and other Unix variants (e.g. FreeBSD). 58 | 59 | For a client implementation of SEXYZ, use the SyncTerm Telnet/RLogin/SSH 60 | terminal program (http://syncterm.net/), available for many platforms, 61 | including Win32, *nix, and Mac OS-X. 62 | 63 | 64 | Command-line Syntax 65 | ------------------- 66 | Just running "sexyz" by itself will display the supported command-line usage 67 | (options and commands): 68 | 69 | usage: sexyz [-opts] [file | path | @list] 70 | 71 | socket = TCP socket descriptor (or leave blank for "stdio" mode on Unix) 72 | 73 | opts = -y allow overwriting of existing files when receiving 74 | -o disable ZMODEM CRC-32 mode (force CRC-16 mode instead) 75 | -s disable ZMODEM streaming (Slow ZMODEM) 76 | -k enable X/YMODEM-1K send mode 77 | -c enable XMODEM-CRC receive mode 78 | -g enable X/YMODEM-G receive mode (no error recovery) 79 | -2 set maximum ZMODEM block size to 2K 80 | -4 set maximum ZMODEM block size to 4K 81 | -8 set maximum ZMODEM block size to 8K (ZedZap) 82 | -! to pause after abnormal exit (error) 83 | -telnet to enable Telnet mode (the default) 84 | -rlogin to enable RLogin (pass-through) mode 85 | 86 | cmd = v to display detailed version information 87 | sx to send XMODEM rx to receive XMODEM 88 | sX to send XMODEM-1K rc to receive XMODEM-CRC 89 | sy to send YMODEM ry to receive YMODEM 90 | sY to send YMODEM-1K rg to receive YMODEM-G 91 | sz to send ZMODEM rz to receive ZMODEM 92 | 93 | file = filename to send or receive 94 | path = directory to receive files into 95 | list = name of text file with list of filenames to send or receive 96 | 97 | 98 | NOTE: SEXYZ actually supports either "+list" or "@list" syntax for specifying 99 | a file list on the command-line. If the list file doesn't exist, it'll 100 | treat the '+' or '@' as part of the filename to send or receive. 101 | 102 | NOTE: SEXYZ also supports "rz/sz style" command-line syntax for some commands. 103 | Examples: "sexyz -c rx" to recv XMODEM-CRC (same as "sexyz rc") 104 | "sexyz -k sx" to send XMODEM-1K (same as "seyxz sX") 105 | "sexyz rb" to recv YMODEM (same as "sexyz ry") 106 | "sexyz -k sb" to send YMODEM-1K (same as "sexyz sY") 107 | "sexyz -g ry" to recv YMODEM-G (same as "sexyz rg") 108 | "sexyz -g rx" to recv XMODEM-G 109 | 110 | 111 | Installation for Synchronet v3.12-Win32 112 | --------------------------------------- 113 | Copy sexyz.exe into your Synchronet "exec" directory. 114 | 115 | 116 | Example configuration for Synchronet v3.12-Win32 117 | ------------------------------------------------ 118 | 119 | SCFG:File Options->Transfer Protocols: 120 | 121 | [File Transfer Protocol] 122 | 1: Mnemonic (Command Key) X 123 | 2: Protocol Name XMODEM (SEXYZ) 124 | 3: Access Requirements 125 | 4: Upload Command Line %!sexyz%. %h -%p rC %f 126 | 5: Download Command Line %!sexyz%. %h -%p sX %f 127 | 6: Batch Upload Command Line 128 | 7: Batch Download Command Line 129 | 8: Bi-dir Command Line 130 | 9: Native (32-bit) Executable Yes 131 | 10: Supports DSZLOG Yes 132 | 11: Socket I/O Yes 133 | 134 | [File Transfer Protocol] 135 | 1: Mnemonic (Command Key) Y 136 | 2: Protocol Name YMODEM (SEXYZ) 137 | 3: Access Requirements 138 | 4: Upload Command Line %!sexyz%. %h -%p ry %f 139 | 5: Download Command Line %!sexyz%. %h -%p sY %f 140 | 6: Batch Upload Command Line %!sexyz%. %h -%p ry %g 141 | 7: Batch Download Command Line %!sexyz%. %h -%p sY @%f 142 | 8: Bi-dir Command Line 143 | 9: Native (32-bit) Executable Yes 144 | 10: Supports DSZLOG Yes 145 | 11: Socket I/O Yes 146 | 147 | [File Transfer Protocol] 148 | 1: Mnemonic (Command Key) G 149 | 2: Protocol Name YMODEM-G (SEXYZ) 150 | 3: Access Requirements 151 | 4: Upload Command Line %!sexyz%. %h -%p rg %f 152 | 5: Download Command Line %!sexyz%. %h -%p sY %f 153 | 6: Batch Upload Command Line %!sexyz%. %h -%p rg %g 154 | 7: Batch Download Command Line %!sexyz%. %h -%p sY @%f 155 | 8: Bi-dir Command Line 156 | 9: Native (32-bit) Executable Yes 157 | 10: Supports DSZLOG Yes 158 | 11: Socket I/O Yes 159 | 160 | [File Transfer Protocol] 161 | 1: Mnemonic (Command Key) Z 162 | 2: Protocol Name ZMODEM (SEXYZ) 163 | 3: Access Requirements 164 | 4: Upload Command Line %!sexyz%. %h -%p rz %f 165 | 5: Download Command Line %!sexyz%. %h -%p sz %f 166 | 6: Batch Upload Command Line %!sexyz%. %h -%p rz %g 167 | 7: Batch Download Command Line %!sexyz%. %h -%p sz @%f 168 | 8: Bi-dir Command Line 169 | 9: Native (32-bit) Executable Yes 170 | 10: Supports DSZLOG Yes 171 | 11: Socket I/O Yes 172 | 173 | Optional/Advanced: 174 | 175 | [File Transfer Protocol] 176 | 1: Mnemonic (Command Key) 8 177 | 2: Protocol Name ZMODEM-8K (SEXYZ) 178 | 3: Access Requirements 179 | 4: Upload Command Line %!sexyz%. %h -%p rz %f 180 | 5: Download Command Line %!sexyz%. %h -%p -8 sz %f 181 | 6: Batch Upload Command Line %!sexyz%. %h -%p rz %g 182 | 7: Batch Download Command Line %!sexyz%. %h -%p -8 sz @%f 183 | 8: Bi-dir Command Line 184 | 9: Native (32-bit) Executable Yes 185 | 10: Supports DSZLOG Yes 186 | 11: Socket I/O Yes 187 | 188 | NOTE: It is suggested you remove existing FDSZ, CE-XYZ, or sz/rz transfer 189 | protocol entries as they are no longer needed. 190 | 191 | 192 | Example configuration for Mystic v1.08-Win32 193 | -------------------------------------------- 194 | (provided by Dream Master and Jack Phlash) 195 | 196 | A. Active : Yes 197 | B. HotKey : Z 198 | C. Description: ZMODEM 199 | D. Batch : No 200 | E. Send Cmd : c:\mystic\prots\sexyz.exe %0 sz %3 201 | F. Receive Cmd: c:\mystic\prots\sexyz.exe %0 rz %3 202 | 203 | A. Active : Yes 204 | B. HotKey : Z 205 | C. Description: ZMODEM batch 206 | D. Batch : Yes 207 | E. Send Cmd : c:\mystic\prots\sexyz.exe %0 sz @%3 208 | F. Receive Cmd: c:\mystic\prots\sexyz.exe %0 rz %3 209 | 210 | 211 | Example configuration for EleBBS-Win32 212 | -------------------------------------- 213 | (provided by Mike Ehlert, aka pcm) 214 | 215 | Name ZMODEM (SEXYZ) 216 | Key Z 217 | Ext ctl file No 218 | Batch Yes 219 | Status Always available 220 | Log file DSZ.LOG 221 | Control file DSZ.CTL 222 | DL command line c:\bbs\sexyz.exe *W -quotes sz @DSZ.CTL 223 | UL command line c:\bbs\sexyz.exe *W -quotes rz 224 | DL ctl string @ 225 | UL ctl string @ 226 | DL log keyword z 227 | UL log keyword Z 228 | Log name word 10 229 | Log desc word 0 230 | 231 | You will need to have the environment variable DSZLOG set to DSZ.LOG. 232 | It should *not* have a path of course, so that it's created in the current 233 | node's directory. 234 | 235 | Once you define that under control panel > system > env variables > system 236 | variables, be sure to close the window running eleserv or telsrv and reopen 237 | it for the environment variable to become active.. Otherwise there will be 238 | no log of the transfer and EleBBS will assume it failed. 239 | 240 | Note: To support long filenames with EleBBS, you'll need Sexyz v1.74 or later 241 | and set "Quotes=true" in the [DSZLOG] section of your sexyz.ini file or use 242 | the secret "-quotes" command-line option. 243 | 244 | 245 | Note Regarding Synchronet for Unix 246 | ---------------------------------- 247 | Synchronet for Unix (prior to v3.14) did not support socket-based file 248 | transfer protocols, so SEXYZ is only currently supported on Synchronet for 249 | Unix (v3.13 and older) in "stdio" mode. 250 | 251 | You can use "stdio" mode in SEXYZ by removing '%h' (the socket descriptor) 252 | from the above command-lines. If you're using Synchronet for Unix v3.14 or 253 | later, socket I/O mode is preferred (do not use "stdio" mode). 254 | 255 | 256 | Optional Initialization File (sexyz.ini) 257 | ---------------------------------------- 258 | If the file sexyz.ini exists in the same directory as the sexyz executable 259 | (e.g. C:\sbbs\exec\sexyz.ini), it will be loaded and used to over-ride the 260 | default operating parameters shown below. Like all Synchronet .ini files, 261 | you can have a unique .ini file for different local systems by embedding 262 | the local hostname (sexyz[.host].ini) or platform (sexyz[.platform].ini) 263 | in the filename. The filenames are *not* case sensitive. Examples: 264 | 265 | C:\sbbs\exec\sexyz.dadscomputer.ini 266 | C:\sbbs\exec\sexyz.win32.ini 267 | /sbbs/exec/sexyz.linux.ini 268 | 269 | Example .ini file (with default values given): 270 | 271 | Telnet=TRUE ; set to FALSE to change the default mode 272 | TCP_NoDelay=TRUE ; disable the TCP Nagle algorithm 273 | LogLevel=INFO ; set display/log output level 274 | Debug=FALSE ; enable debug logging (overrides LogLevel) 275 | DebugTx=FALSE ; debug transmitted characters 276 | DebugRx=FALSE ; debug received characters 277 | DebugTelnet=FALSE ; debug Telnet commands 278 | PauseOnExit=FALSE ; wait for key-press on exit 279 | PauseOnAbend=FALSE ; wait for key-press on abnormal exit 280 | OutbufSize=16384 ; bytes (between 1024 and 65536) 281 | OutbufHighwaterMark=1100 ; bytes before auto-flush 282 | OutbufDrainTimeout=10 ; milliseconds before auto-flush 283 | ProgressInterval=1 ; interval (in seconds) of progress display 284 | 285 | [XMODEM] 286 | SendTimeout=10 ; seconds 287 | RecvTimeout=10 ; seconds 288 | ByteTimeout=3 ; seconds 289 | AckTimeout=10 ; seconds 290 | BlockSize=1024 ; 128 or 1024 291 | MaxBlockSize=1024 ; 128 or 1024 292 | MaxErrors=9 293 | G_Delay=1 ; millisecond yield between sent X/YMODEM-G blocks 294 | SendG=TRUE ; Support G-mode for X/YMODEM sends 295 | SendCRC=TRUE ; Support CRC-16 error detection for X/YMODEM sends 296 | 297 | [YMODEM] 298 | FallbackToXMODEM=0 ; Failed send attempts before falling back to XMODEM 299 | 300 | [ZMODEM] 301 | InitTimeout=10 ; seconds 302 | SendTimeout=15 ; seconds 303 | RecvTimeout=20 ; seconds 304 | CrcTimeout=60 ; seconds 305 | BlockSize=1024 ; 1024 is usually best to start with 306 | MaxBlockSize=1024 ; 1024 is "true" ZMODEM, 8192 for ZMODEM-8K (ZedZap) 307 | MaxErrors=9 ; maximum number of consecutive errors 308 | RecvBufSize=0 ; specify non-zero for partial streaming receives 309 | Streaming=TRUE ; set to FALSE to disable streaming (block-at-a-time) 310 | CRC32=TRUE ; set to FALSE to force CRC-16 instead 311 | EscapeTelnetIAC=TRUE ; send ZDLE/ZRUB1 instead of 0xff with -telnet 312 | Escape8thBit=FALSE ; ZDLE-escape all bytes with bit-7 set 313 | EscapeCtrlChars=FALSE ; ZDLE-escape all control characters (< 20h) 314 | 315 | [DSZLOG] 316 | Path=true ; include full path to filename in log 317 | Short=false ; use Micros~1 short path/filename in log (Windows) 318 | Quotes=false ; enclose filename in "quotes" (for EleBBS) 319 | 320 | 321 | Compatibility 322 | ------------- 323 | The XMODEM, YMODEM, and ZMODEM file transfers should be compatible with any 324 | terminal programs or remote protocol drivers that conform to the public 325 | specifications for these protocols written by Chuck Forsberg (XMODEM was 326 | actually written by Ward Christensen, but was extended by others and 327 | documented by our good friend, Chuck). 328 | 329 | SEXYZ supports the following protocols and their popular permutations: 330 | 331 | XMODEM: 128-byte blocks, 8-bit checksum error detection 332 | XMODEM-CRC: 128-byte blocks, 16-bit CRC error detection 333 | XMODEM-1K: 1024-byte blocks, 16-bit CRC error detection 334 | XMODEM-G: 1024-byte blocks, 16-bit CRC error detection, and streaming 335 | (no acknowledgements or error recovery) (a.k.a. QMODEM-G) 336 | YMODEM: 128-byte blocks, 16-bit CRC error detection, batch file transfers 337 | YMODEM-1K: 1024-byte blocks, 16-bit CRC error detection, batch file transfers 338 | YMODEM-G: 1024-byte blocks, 16-bit CRC error detection, batch file transfers 339 | and streaming (no acknowledgements or error recovery) 340 | ZMODEM: 1024-byte blocks, 16-bit or 32-bit CRC error detection, batch file 341 | transfers, resume, auto-download, and more 342 | ZMODEM-8K: 8192-byte blocks, 16-bit or 32-bit CRC error detection, batch file 343 | transfers, resume, auto-download, and more (a.k.a. ZedZap) 344 | 345 | SEXYZ will automatically fall back from 1024-byte block XMODEM/YMODEM send 346 | mode to 128-byte block XMODEM/YMODEM send mode if the receiver does not appear 347 | to support 1024-byte blocks. 348 | 349 | SEXYZ also supports automatically falling back from XMODEM/YMODEM-CRC to 350 | XMODEM/YMODEM-Checksum mode when sending to a receiver that does not support 351 | CRC-16 error detection. 352 | 353 | As of this writing, the current version of SEXYZ and the X/ZMODEM modules are: 354 | 355 | sexyz.c 1.81 356 | xmodem.c 1.36 <-- Includes YMODEM 357 | zmodem.c 1.77 358 | 359 | SEXYZ for Win32 has been tested successfully with the following Telnet clients 360 | /terminal programs: 361 | 362 | [ztelnet] 363 | OS: Linux 364 | Version: 1.2.2 365 | URL: ftp://ibiblio.org/pub/Linux/system/network/telnet/ 366 | Tested: ZMODEM uploads and downloads 367 | Failed: none 368 | 369 | [HyperTerminal Private Edition] 370 | By: Hilgraeve, Inc. 371 | OS: Win32 372 | Version: 6.3 373 | URL: http://www.hilgraeve.com/htpe/ 374 | Tested: XMODEM (checksum and CRC), XMODEM-1K, YMODEM-1K, YMODEM-G and ZMODEM 375 | both uploads and downloads 376 | Failed: ZMODEM uploads (CRC errors detected): appears to be the fault of 377 | HyperTerminal and can be reproduced with any protocol driver on the 378 | BBS/server side (even FDSZ) 379 | 380 | [mTelnet] 381 | By: enigma 382 | OS: Win32 383 | Version: 1.0 (beta 12)/w32 384 | URL: http://ozone.eesc.com 385 | Tested: ZMODEM uploads and downloads 386 | Failed: none 387 | 388 | [NetRunner] 389 | By: Mystic Software Development (James Coyle/g00r00) 390 | OS: Win32 391 | Version: 0.09 392 | URL: www.mysticbbs.com 393 | Tested: ZMODEM uploads and downloads 394 | Failed: ZMODEM uploads (CRC errors detected): appears to be the fault of 395 | NetRunner and can be reproduced with any protocol driver on the 396 | BBS/server side (FDSZ and CEXYZ both failed in the same manner) 397 | 398 | [ZOC] 399 | By: EmTec, Innovative Software, Markus Schmidt 400 | OS: Win32 401 | Version: 5.02 402 | URL: http://www.emtec.com 403 | Tested: XMODEM, YMODEM, ZMODEM uploads and downloads 404 | ZMODEM: CRC-32 405 | RZ-rx-frames: ZFILE, ZDATA, ZCRCG, ZCRCW, ZCRCE, ZEOF, ZFIN 406 | RZ-tx-frames: ZRINIT, ZRPOS, ZACK, ZFIN 407 | Failed: none 408 | 409 | 410 | Support 411 | ------- 412 | For technical support (including bug reports), see 413 | http://www.synchro.net/docs/support.html for details. 414 | 415 | When submitting problem/bug reports, please include the version output from 416 | the "sexyz v" command. We're also very interested in reports of compatibility 417 | (or incompatibility) with terminal programs or telnet clients. 418 | 419 | 420 | Credits 421 | ------- 422 | The XMODEM (a.k.a. MODEM, MODEM2) protocol was originally created by Ward 423 | Christensen in 1977. 424 | 425 | The XMODEM-CRC protocol (XMODEM derivative using a 16-CRC for error detection 426 | rather than XMODEM's 8-bit checksum) was created by John Mahr. 427 | 428 | The YMODEM, YMODEM-G and ZMODEM protocols were created and documented by Chuck 429 | Forsberg; YMODEM being primarily a set of enhancements to Ward's XMODEM and 430 | Mahr's XMODEM-CRC protocols. 431 | 432 | The X/YMODEM code used in SEXYZ was written by Rob Swindell , migrated from the Synchronet Transfer Protocols (STP) program 434 | circa 1997. 435 | 436 | The Unix "stdio" mode support in SEXYZ was written by Stephen Hurd (a.k.a. 437 | Deuce) of Synchronix/FreeBSD Synchronet stardom and "scary code" infamy. 438 | 439 | The ZMODEM code in SEXYZ is based on zmtx/zmrx v1.02 (C) Mattheij Computer 440 | Service 1994 by Jacques Mattheij . Although 441 | SEXYZ's ZMODEM code no longer resembles zmtx/zmrx much, it served as a good 442 | starting point, and Jacques' version of Chuck's ZMODEM.DOC was very helpful! 443 | 444 | The 16-bit CRC table and calculation macro was (unwittingly) contributed by 445 | Mark G. Mendel and Stephen Satchell. 446 | 447 | The 32-bit CRC table and calculation macro was (unwittingly) contributed by 448 | Gary S. Brown. 449 | 450 | SEXYZ includes portions of the Synchronet XPDEV and SMBLIB libraries which 451 | are licensed under the GNU Lesser General Public License (LGPL). 452 | http://www.fsf.org/licensing/licenses/lgpl.txt 453 | 454 | Synchronet BBS software is written by and copyright 2014 Rob Swindell. 455 | http://www.synchro.net/docs/copyright.html 456 | -------------------------------------------------------------------------------- /doc/xymodem.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/fredrikhederstierna/fymodem/98af4588e4d621c4cb88174369466b405b895c04/doc/xymodem.pdf -------------------------------------------------------------------------------- /doc/zmodem.doc: -------------------------------------------------------------------------------- 1 | zmodem.doc !copyrighted by MCS 1994 use it anyway you like but don't complain 2 | this file should be accompanied by a readme which contains some background 3 | information on implementing zmodem. 4 | 5 | GENERAL 6 | ------- 7 | 8 | Documentation about the zmodem protocol internals; should be sufficient 9 | to implement a completely functional zmodem protocol suite. 10 | 11 | Zmodem is a file transfer protocol that attempts to maximize bandwidth 12 | and minimize transfer times. it is a unidirectional protocol; i.e. the 13 | return channel only transfers control information; no data. either side 14 | may initiate the transfer; but the downloading site may respond to 15 | an initialization frame by auto starting the download software. 16 | 17 | Schematically a zmodem file transfer in progress looks like this: 18 | 19 | |----------<< back channel <<-------------| 20 | ------+------- --------+------ 21 | | Sender | | Receiver | 22 | | (upload) | | (download) | 23 | -------------- --------+------ 24 | |---------->> data channel >>-------------| 25 | 26 | Multiple files may be transferred in one session. 27 | 28 | SAMPLE 29 | ------ 30 | 31 | all zmodem transactions are done using frames. a frame consists 32 | of a header followed by one or more data subpackets. 33 | a typical (simple) zmodem file transfer looks like this : 34 | 35 | sender receiver 36 | 37 | ZRQINIT(0) 38 | ZRINIT 39 | ZFILE 40 | ZRPOS 41 | ZDATA data ... 42 | ZEOF 43 | ZRINIT 44 | ZFIN 45 | ZFIN 46 | OO 47 | 48 | zmodem continuously transmits data unless the receiver interrupts 49 | the sender to request retransmission of garbled data. 50 | zmodem in effect uses the entire file as a window. 51 | 52 | REQUIREMENTS 53 | ------------ 54 | 55 | zmodem requires an 8 bit transfer medium; but allows encoded packets 56 | for less transparent media. 57 | zmodem escapes network control characters to allow operation with 58 | packet switched networks. 59 | 60 | To support full streaming, the transmission path should either assert 61 | flow control or pass full speed transmission without loss of data. 62 | Otherwise the zmodem sender must manage the window size. 63 | 64 | zmodem places no constraints on the content files. 65 | 66 | LINK ESCAPE ENCODING 67 | -------------------- 68 | 69 | zmodem achieves data transparency by extending the 8 bit character set 70 | (256 codes) with escape sequences based on the zmodem data link escape 71 | character ZDLE 72 | 73 | Link Escape coding permits variable length data subpackets without the 74 | overhead of a separate byte count. It allows the beginning of frames to 75 | be detected without special timing techniques, facilitating rapid error 76 | recovery. 77 | 78 | Link Escape coding does add some overhead. The worst case, a file 79 | consisting entirely of escaped characters, would incur a 50% overhead. 80 | 81 | The ZDLE character is special. ZDLE represents a control 82 | sequence of some sort. If a ZDLE character appears in binary data, 83 | it is prefixed with ZDLE, then sent as ZDLEE 84 | 85 | 5 consecutive CAN characters abort a zmodem session 86 | 87 | Since CAN is not used in normal terminal operations, interactive 88 | applications and communications programs can monitor the data flow for 89 | ZDLE. The following characters can be scanned to detect the ZRQINIT 90 | header, the invitation to automatically download commands or files. 91 | 92 | Receipt of five successive CAN characters will abort a zmodem session. 93 | Eight CAN characters are sent (just to be on the safe side) 94 | 95 | The receiving program decodes any sequence of ZDLE followed by a byte with 96 | bit 6 set and bit 5 reset (upper case letter, either parity) to the 97 | equivalent control character by inverting bit 6. This allows the 98 | transmitter to escape any control character that cannot be sent by the 99 | communications medium. In addition, the receiver recognizes escapes for 100 | 0x7f and 0xff should these characters need to be escaped. 101 | 102 | zmodem software escapes ZDLE (0x18), 0x10, 0x90, 0x11, 0x91, 0x13, 103 | and 0x93. 104 | If preceded by 0x40 or 0xc0 (@), 0x0d and 0x8d are also escaped to 105 | protect the Telenet command escape CR-@-CR. The receiver ignores 106 | 0x11, 0x91, 0x13, and 0x93 characters in the data stream. 107 | 108 | HEADERS 109 | ------- 110 | 111 | All zmodem frames begin with a header which may be sent in binary or HEX 112 | form. Either form of the header contains the same raw information: 113 | 114 | - A type byte 115 | 116 | - Four bytes of data indicating flags and/or numeric quantities depending 117 | on the frame type 118 | 119 | the maximum header information length is 16 bytes 120 | the data subpackets following the header are maximum 1024 bytes long. 121 | 122 | M L 123 | FTYPE F3 F2 F1 F0 (flags frame) 124 | 125 | L M 126 | FTYPE P0 P1 P2 P3 (numeric frame) 127 | 128 | Beware of the catch; flags and numbers are indexed the other way around ! 129 | 130 | 16 BIT CRC BINARY HEADER 131 | ------------------------ 132 | 133 | A binary header is sent by the sending program to the receiving 134 | program. All bytes in a binary header are ZDLE encoded. 135 | 136 | A binary header begins with the sequence ZPAD, ZDLE, ZBIN. 137 | 138 | 0 or more binary data subpackets with 16 bit CRC will follow depending 139 | on the frame type. 140 | 141 | * ZDLE A TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 142 | 143 | 144 | 32 BIT CRC BINARY HEADER 145 | ------------------------ 146 | 147 | A "32 bit CRC" Binary header is similar to a Binary Header, except the 148 | ZBIN (A) character is replaced by a ZBIN32 (C) character, and four 149 | characters of CRC are sent. 150 | 151 | 0 or more binary data subpackets with 32 bit CRC will follow depending 152 | on the frame type. 153 | 154 | * ZDLE C TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 CRC-3 CRC-4 155 | 156 | HEX HEADER 157 | ---------- 158 | 159 | The receiver sends responses in hex headers. The sender also uses hex 160 | headers when they are not followed by binary data subpackets. 161 | 162 | Hex encoding protects the reverse channel from random control 163 | characters. The hex header receiving routine ignores parity. 164 | 165 | use of hex headers by the receiving program allows control characters 166 | to be used to interrupt the sender when errors are detected. 167 | A HEX header may be used in place of a binary header 168 | wherever convenient. 169 | If a data packet follows a HEX header, it is protected with CRC-16. 170 | 171 | A hex header begins with the sequence ZPAD, ZPAD, ZDLE, ZHEX. 172 | The extra ZPAD character allows the sending program to detect 173 | an asynchronous header (indicating an error condition) and then 174 | get the rest of the header with a non-error specific routine. 175 | 176 | The type byte, the four position/flag bytes, and the 16 bit CRC 177 | thereof are sent in hex using the character set 01234567890abcdef. 178 | Upper case hex digits are not allowed. 179 | Since this form of hex encoding detects many patterns of errors, 180 | especially missing characters, a hex header with 32 bit CRC has not 181 | been defined. 182 | 183 | A carriage return and line feed are sent with HEX headers. The 184 | receive routine expects to see at least one of these characters, two 185 | if the first is CR. 186 | 187 | An XON character is appended to all HEX packets except ZACK and ZFIN. 188 | The XON releases the sender from spurious XOFF flow control characters 189 | generated by line noise. XON is not sent after ZACK headers to protect 190 | flow control in streaming situations. XON is not sent after a ZFIN 191 | header to allow proper session cleanup. 192 | 193 | 0 or more data subpackets will follow depending on the frame type. 194 | 195 | * * ZDLE B TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 CR LF XON 196 | 197 | (TYPE, F3...F0, CRC-1, and CRC-2 are each sent as two hex digits.) 198 | 199 | BINARY DATA SUBPACKETS 200 | ---------------------- 201 | 202 | Binary data subpackets immediately follow the associated binary header 203 | packet. A binary data packet contains 0 to 1024 bytes of data. 204 | Recommended length values are 256 bytes below 2400 bps, 512 at 205 | 2400 bps, and 1024 above 4800 bps or when the data link is known to 206 | be relatively error free. 207 | 208 | No padding is used with binary data subpackets. The data bytes are 209 | ZDLE encoded and transmitted. A ZDLE and frameend are then sent, 210 | followed by two or four ZDLE encoded CRC bytes. The CRC accumulates 211 | the data bytes and frameend. 212 | 213 | PROTOCOL TRANSACTION OVERVIEW 214 | ----------------------------- 215 | 216 | zmodem timing is receiver driven. The 217 | transmitter should not time out at all, except to abort the program if no 218 | headers are received for an extended period of time, say one minute. 219 | 220 | SESSION STARTUP 221 | --------------- 222 | 223 | To start a zmodem file transfer session, the sending program is called 224 | with the names of the desired file(s) and option(s). 225 | 226 | Then the sender may send a ZRQINIT header. The ZRQINIT header causes a 227 | previously started receive program to send its ZRINIT header without 228 | delay. 229 | 230 | In an interactive or conversational mode, the receiving application 231 | may monitor the data stream for ZDLE. The following characters may be 232 | scanned for B00 indicating a ZRQINIT header, a command to download 233 | data. 234 | 235 | The sending program awaits a command from the receiving program to 236 | start file transfers. 237 | 238 | In case of garbled data, the sending program can repeat the invitation 239 | to receive a number of times until a session starts. 240 | 241 | When the zmodem receive program starts, it immediately sends a ZRINIT 242 | header to initiate zmodem file transfers, or a ZCHALLENGE header to 243 | verify the sending program. The receive program resends its header at 244 | response time (default 10 second) intervals for a suitable period of 245 | time (40 seconds total) before exitting. 246 | 247 | If the receiving program receives a ZRQINIT header, it resends the 248 | ZRINIT header. If the sending program receives the ZCHALLENGE header, 249 | it places the data in ZP0...ZP3 in an answering ZACK header. 250 | 251 | If the receiving program receives a ZRINIT header, it is an echo 252 | indicating that the sending program is not operational. 253 | 254 | Eventually the sending program correctly receives the ZRINIT header. 255 | 256 | The sender may then send an optional ZSINIT frame to define the 257 | receiving program's Attn sequence, or to specify complete control 258 | character escaping. if the receiver specifies the same or higher 259 | level of escaping the ZSINIT frame need not be sent unless an Attn 260 | sequence is needed. 261 | 262 | If the ZSINIT header specifies ESCCTL or ESC8, a HEX header is used, 263 | and the receiver activates the specified ESC modes before reading the 264 | following data subpacket. 265 | 266 | The receiver sends a ZACK header in response, containing 0. 267 | 268 | FILE TRANSMISSION 269 | ----------------- 270 | 271 | The sender then sends a ZFILE header with zmodem Conversion, 272 | Management, and Transport options (see ZFILE header type) followed 273 | by a ZCRCW data subpacket containing the file name, file length and 274 | modification date. 275 | 276 | The receiver examines the file name, length, and date information 277 | provided by the sender in the context of the specified transfer 278 | options, the current state of its file system(s), and local security 279 | requirements. The receiving program should insure the pathname and 280 | options are compatible with its operating environment and local 281 | security requirements. 282 | 283 | The receiver may respond with a ZSKIP header, which makes the sender 284 | proceed to the next file (if any) in the batch. 285 | 286 | The receiver has a file with the same name and length, may 287 | respond with a ZCRC header with a byte count, which 288 | requires the sender to perform a 32 bit CRC on the 289 | specified number of bytes in the file and transmit the 290 | complement of the CRC in an answering ZCRC header.the crc is 291 | initialised to 0xfffffff; a byte count of 0 implies the entire 292 | file the receiver uses this information to determine whether to 293 | accept the file or skip it. This sequence may be triggered 294 | by the ZMCRC Management Option. 295 | 296 | A ZRPOS header from the receiver initiates transmission of the file 297 | data starting at the offset in the file specified in the ZRPOS header. 298 | Normally the receiver specifies the data transfer to begin begin at 299 | offset 0 in the file. 300 | 301 | The receiver may start the transfer further down in the 302 | file. This allows a file transfer interrupted by a loss 303 | of carrier or system crash to be completed on the next 304 | connection without requiring the entire file to be 305 | retransmitted. If downloading a file from a timesharing 306 | system that becomes sluggish, the transfer can be 307 | interrupted and resumed later with no loss of data. 308 | 309 | The sender sends a ZDATA binary header (with file position) followed 310 | by one or more data subpackets. 311 | 312 | The receiver compares the file position in the ZDATA header with the 313 | number of characters successfully received to the file. If they do not 314 | agree, a ZRPOS error response is generated to force the sender to the 315 | right position within the file. (if the ZMSPARS option is used the 316 | receiver instead seeks to the position given in the ZDATA header) 317 | 318 | A data subpacket terminated by ZCRCG and CRC does not elicit a 319 | response unless an error is detected; more data subpacket(s) follow 320 | immediately. 321 | 322 | ZCRCQ data subpackets expect a ZACK response with the 323 | receiver's file offset if no error, otherwise a ZRPOS 324 | response with the last good file offset. Another data 325 | subpacket continues immediately. ZCRCQ subpackets are 326 | not used if the receiver does not indicate full duplex ability 327 | with the CANFDX bit. 328 | 329 | ZCRCW data subpackets expect a response before the next frame is sent. 330 | If the receiver does not indicate overlapped I/O capability with the 331 | CANOVIO bit, or sets a buffer size, the sender uses the ZCRCW to allow 332 | the receiver to write its buffer before sending more data. 333 | 334 | A zero length data frame may be used as an idle 335 | subpacket to prevent the receiver from timing out in 336 | case data is not immediately available to the sender. 337 | 338 | In the absence of fatal error, the sender eventually encounters end of 339 | file. If the end of file is encountered within a frame, the frame is 340 | closed with a ZCRCE data subpacket which does not elicit a response 341 | except in case of error. 342 | 343 | The sender sends a ZEOF header with the file ending offset equal to 344 | the number of characters in the file. The receiver compares this 345 | number with the number of characters received. If the receiver has 346 | received all of the file, it closes the file. If the file close was 347 | satisfactory, the receiver responds with ZRINIT. If the receiver has 348 | not received all the bytes of the file, the receiver ignores the ZEOF 349 | because a new ZDATA is coming. If the receiver cannot properly close 350 | the file, a ZFERR header is sent. 351 | 352 | After all files are processed, any further protocol 353 | errors should not prevent the sending program from 354 | returning with a success status. 355 | 356 | SESSION CLEANUP 357 | --------------- 358 | 359 | The sender closes the session with a ZFIN header. The receiver 360 | acknowledges this with its own ZFIN header. 361 | 362 | When the sender receives the acknowledging header, it sends two 363 | characters, "OO" (Over and Out) and exits. 364 | The receiver waits briefly for the "O" characters, then exits 365 | whether they were received or not. 366 | 367 | SESSION ABORT SEQUENCE 368 | ---------------------- 369 | 370 | If the receiver is receiving data in streaming mode, the Attn 371 | sequence is executed to interrupt data transmission before the Cancel 372 | sequence is sent. The Cancel sequence consists of eight CAN 373 | characters and ten backspace characters. zmodem only requires five 374 | Cancel characters, the other three are "insurance". 375 | 376 | The trailing backspace characters attempt to erase the effects of the 377 | CAN characters if they are received by a command interpreter. 378 | 379 | char ses_abort_seq[] = { 380 | 24,24,24,24,24,24,24,24,8,8,8,8,8,8,8,8,8,8,0 381 | }; 382 | 383 | ATTENTION SEQUENCE 384 | ------------------ 385 | 386 | The receiving program sends the Attn sequence whenever it detects an 387 | error and needs to interrupt the sending program. 388 | 389 | The default Attn string value is empty (no Attn sequence). The 390 | receiving program resets Attn to the empty default before each 391 | transfer session. 392 | 393 | The sender specifies the Attn sequence in its optional ZSINIT frame. 394 | The Attn string is terminated with a null. 395 | 396 | FRAME TYPES 397 | ----------- 398 | 399 | The numeric values are listed at the end of this file. 400 | Unused bits and unused bytes in the header (ZP0...ZP3) are set to 0. 401 | 402 | ZRQINIT 403 | ------- 404 | 405 | Sent by the sending program, to trigger the receiving program to send 406 | its ZRINIT header. 407 | The sending program may 408 | repeat the receive invitation (including ZRQINIT) if a response is 409 | not obtained at first. 410 | 411 | ZF0 contains ZCOMMAND if the program is attempting to send a command, 412 | 0 otherwise. 413 | 414 | ZRINIT 415 | ------ 416 | 417 | Sent by the receiving program. ZF0 and ZF1 contain the bitwise or 418 | of the receiver capability flags: 419 | 420 | CANCRY receiver can decrypt 421 | CANFDX receiver can send and receive true full duplex 422 | CANOVIO receiver can receive data during disk I/O 423 | CANBRK receiver can send a break signal 424 | CANCRY receiver can decrypt 425 | CANLZW receiver can uncompress 426 | CANFC32 receiver can use 32 bit Frame Check 427 | ESCCTL receiver expects ctl chars to be escaped 428 | ESC8 receiver expects 8th bit to be escaped 429 | 430 | ZP0 and ZP1 contain the size of the receiver's buffer in bytes, or 0 431 | if nonstop I/O is allowed. 432 | 433 | while all these capabilities are nice in theory most zmodem implem- 434 | tations balk at anything other than 0,0. i.e. telix starts sending 435 | 35 byte packets when CANFC32 is on. 436 | 437 | ZSINIT 438 | ------ 439 | 440 | The Sender sends flags followed by a binary data subpacket terminated 441 | with ZCRCW. 442 | 443 | TESCCTL Transmitter expects ctl chars to be escaped 444 | TESC8 Transmitter expects 8th bit to be escaped 445 | 446 | The data subpacket contains the null terminated Attn sequence, 447 | maximum length 32 bytes including the terminating null. 448 | 449 | ZACK 450 | ---- 451 | 452 | Acknowledgment to a ZSINIT frame, ZCHALLENGE header, ZCRCQ or ZCRCW 453 | data subpacket. ZP0 to ZP3 contain file offset. The response to 454 | ZCHALLENGE contains the same 32 bit number received in the ZCHALLENGE 455 | header. 456 | 457 | ZFILE 458 | ----- 459 | This frame denotes the beginning of a file transmission attempt. 460 | ZF0, ZF1, and ZF2 may contain options. A value of 0 in each of these 461 | bytes implies no special treatment. Options specified to the 462 | receiver override options specified to the sender with the exception 463 | of ZCBIN. A ZCBIN from the sender overrides any other Conversion 464 | Option given to the receiver except ZCRESUM. A ZCBIN from the 465 | receiver overrides any other Conversion Option sent by the sender. 466 | 467 | 468 | ZF0: CONVERSION OPTION 469 | ---------------------- 470 | 471 | If the receiver does not recognize the Conversion Option, an 472 | application dependent default conversion may apply. 473 | 474 | ZCBIN "Binary" transfer - inhibit conversion unconditionally 475 | 476 | ZCNL Convert received end of line to local end of line 477 | convention. The supported end of line conventions are 478 | CR/LF (most ASCII based operating systems except Unix 479 | and Macintosh), and NL (Unix). Either of these two end 480 | of line conventions meet the permissible ASCII 481 | definitions for Carriage Return and Line Feed/New Line. 482 | Neither the ASCII code nor zmodem ZCNL encompass lines 483 | separated only by carriage returns. Other processing 484 | appropriate to ASCII text files and the local operating 485 | system may also be applied by the receiver. (filtering 486 | RUBOUT NULL Ctrl-Z etc) 487 | 488 | ZCRECOV Recover/Resume interrupted file transfer. ZCREVOV is 489 | also useful for updating a remote copy of a file that 490 | grows without resending of old data. If the destination 491 | file exists and is no longer than the source, append to 492 | the destination file and start transfer at the offset 493 | corresponding to the receiver's end of file. This 494 | option does not apply if the source file is shorter. 495 | Files that have been converted (e.g., ZCNL) or subject 496 | to a single ended Transport Option cannot have their 497 | transfers recovered. 498 | 499 | ZF1: Management Option 500 | ---------------------- 501 | 502 | If the receiver does not recognize the Management Option, the 503 | file should be transferred normally. 504 | 505 | The ZMSKNOLOC bit instructs the receiver to bypass the 506 | current file if the receiver does not have a file with the 507 | same name. 508 | 509 | Five bits (defined by ZMMASK) define the following set of 510 | mutually exclusive management options. 511 | 512 | ZMNEWL Transfer file if destination file absent. Otherwise, 513 | transfer file overwriting destination if the source file 514 | is newer or longer. 515 | 516 | ZMCRC Compare the source and destination files. Transfer if 517 | file lengths or file polynomials differ. 518 | 519 | ZMAPND Append source file contents to the end of the existing 520 | destination file (if any). 521 | 522 | ZMCLOB Replace existing destination file (if any). 523 | 524 | ZMDIFF Transfer file if destination file absent. Otherwise, 525 | transfer file overwriting destination if files have 526 | different lengths or dates. 527 | 528 | ZMPROT Protect destination file by transferring file only if 529 | the destination file is absent. 530 | 531 | ZMNEW Transfer file if destination file absent. Otherwise, 532 | transfer file overwriting destination if the source file 533 | is newer. 534 | 535 | ZF2: TRANSPORT OPTION 536 | --------------------- 537 | 538 | If the receiver does not implement the particular transport 539 | option, the file is copied without conversion for later 540 | processing. better not to use these; see readme 541 | 542 | ZTLZW Lempel-Ziv compression. Transmitted data will be 543 | identical to that produced by compress 4.0 operating on 544 | a computer with VAX byte ordering, using 12 bit 545 | encoding. 546 | 547 | ZTCRYPT Encryption. An initial null terminated string 548 | identifies the key. Details to be determined. 549 | 550 | ZTRLE Run Length encoding, Details to be determined. 551 | 552 | A ZCRCW data subpacket follows with file name, file length, 553 | modification date, and other information described in a later 554 | chapter. 555 | 556 | ZF3: EXTENDED OPTIONS 557 | --------------------- 558 | 559 | The Extended Options are bit encoded. 560 | 561 | ZTSPARS Special processing for sparse files, or sender managed 562 | selective retransmission. Each file segment is transmitted as 563 | a separate frame, where the frames are not necessarily 564 | contiguous. The sender should end each segment with a ZCRCW 565 | data subpacket and process the expected ZACK to insure no data 566 | is lost. ZTSPARS cannot be used with ZCNL. 567 | 568 | ZSKIP 569 | ----- 570 | 571 | Sent by the receiver in response to ZFILE, makes the sender skip to 572 | the next file. 573 | 574 | ZNAK 575 | ---- 576 | 577 | Indicates last header was garbled. (See also ZRPOS). 578 | 579 | ZABORT 580 | ------ 581 | 582 | Sent by receiver to terminate batch file transfers when requested by 583 | the user. Sender responds with a ZFIN sequence. (or ZCOMPL in case of 584 | server mode). 585 | 586 | ZFIN 587 | ---- 588 | 589 | Sent by sending program to terminate a zmodem session. Receiver 590 | responds with its own ZFIN. 591 | 592 | ZRPOS 593 | ----- 594 | 595 | Sent by receiver to force file transfer to resume at file offset 596 | given in ZP0...ZP3. 597 | 598 | ZDATA 599 | ----- 600 | 601 | ZP0...ZP3 contain file offset. One or more data subpackets follow. 602 | 603 | ZEOF 604 | ---- 605 | 606 | Sender reports End of File. ZP0...ZP3 contain the ending file 607 | offset. 608 | 609 | ZFERR 610 | ----- 611 | 612 | Error in reading or writing file, protocol equivalent to ZABORT. 613 | 614 | ZCRC 615 | ---- 616 | 617 | Request (receiver) and response (sender) for file polynomial. 618 | ZP0...ZP3 contain file polynomial. 619 | 620 | ZCHALLENGE 621 | ---------- 622 | 623 | Request sender to echo a random number in ZP0...ZP3 in a ZACK frame. 624 | Sent by the receiving program to the sending program to verify that 625 | it is connected to an operating program, and was not activated by 626 | spurious data or a Trojan Horse message. this is the most simply 627 | defeated security system ever invented. don't rely on it and better 628 | still don't use or implement it. build your security measures around 629 | starting the download at all and disallow explicit path names. 630 | 631 | ZCOMPL 632 | ------ 633 | 634 | Request now completed. 635 | 636 | ZCAN 637 | ---- 638 | 639 | This is a pseudo frame type in response to a 640 | Session Abort sequence. 641 | 642 | ZFREECNT 643 | -------- 644 | 645 | Sending program requests a ZACK frame with ZP0...ZP3 containing the 646 | number of free bytes on the current file system. A value of 0 647 | represents an indefinite amount of free space. 648 | 649 | ZCOMMAND 650 | -------- 651 | 652 | ZCOMMAND is sent in a binary frame. ZF0 contains 0 or ZCACK1 (see 653 | below). 654 | 655 | A ZCRCW data subpacket follows, with the ASCII text command string 656 | terminated with a NULL character. If the command is intended to be 657 | executed by the operating system hosting the receiving program 658 | (e.g., "shell escape"), it must have "!" as the first character. 659 | Otherwise the command is meant to be executed by the application 660 | program which receives the command. 661 | 662 | If the receiver detects an illegal or badly formed command, the 663 | receiver immediately responds with a ZCOMPL header with an error 664 | code in ZP0...ZP3. 665 | 666 | If ZF0 contained ZCACK1, the receiver immediately responds with a 667 | ZCOMPL header with 0 status. 668 | 669 | Otherwise, the receiver responds with a ZCOMPL header when the 670 | operation is completed. The exit status of the completed command is 671 | stored in ZP0...ZP3. A 0 exit status implies nominal completion of 672 | the command. 673 | 674 | If the command causes a file to be transmitted, the command sender 675 | will see a ZRQINIT frame from the other computer attempting to send 676 | data. 677 | 678 | The sender examines ZF0 of the received ZRQINIT header to verify it 679 | is not an echo of its own ZRQINIT header. It is illegal for the 680 | sending program to command the receiving program to send a command. 681 | 682 | If the receiver program does not implement command downloading, it 683 | may display the command to the standard error output, then return a 684 | ZCOMPL header. 685 | 686 | ZFILE FRAME FILE INFORMATION SUBPACKET 687 | -------------------------------------- 688 | 689 | zmodem sends the same file information with the ZFILE frame data 690 | 691 | The pathname (file name) field is mandatory. each field after 692 | pathname is optional and separated from the previous one by 693 | a space. fields may not be skipped. the use of the optional 694 | fields is (by definition) optional to the receiver. 695 | 696 | PATHNAME 697 | -------- 698 | 699 | The pathname (conventionally, the file name) is sent as a 700 | null terminated ASCII string. 701 | No spaces are included in the pathname. 702 | 703 | Filename Considerations 704 | 705 | - File names should be translated to lower case unless the 706 | sending system supports upper/lower case file names. This 707 | is a convenience for users of systems (such as Unix) which 708 | store filenames in upper and lower case. 709 | 710 | - The receiver should accommodate file names in lower and 711 | upper case. 712 | 713 | - When transmitting files between different operating 714 | systems, file names must be acceptable to both the sender 715 | and receiving operating systems. If not, transformations 716 | should be applied to make the file names acceptable. If 717 | the transformations are unsuccessful, a new file name may 718 | be invented be the receiving program. 719 | 720 | - If directories are included, they are delimited by /; i.e., 721 | "subdir/foo" is acceptable, "subdir\foo" is not. 722 | 723 | LENGTH 724 | ------ 725 | 726 | The length field is stored as a decimal string 727 | counting the number of data bytes in the file. 728 | 729 | The zmodem receiver uses the file length as an estimate only. 730 | It may be used to display an estimate of the transmission time, 731 | and may be compared with the amount of free disk space. The 732 | actual length of the received file is determined by the data 733 | transfer. A file may grow after transmission commences, and 734 | all the data will be sent. 735 | 736 | MODIFICATION DATE 737 | ----------------- 738 | 739 | The mod date is sent as an octal number giving the time the 740 | contents of the file were last changed measured in seconds from 741 | Jan 1 1970 Universal Coordinated Time (GMT). A date of 0 742 | implies the modification date is unknown and should be left as 743 | the date the file is received. 744 | 745 | This standard format was chosen to eliminate ambiguities 746 | arising from transfers between different time zones. 747 | 748 | FILE MODE 749 | --------- 750 | 751 | The file mode is stored as an octal string. 752 | Unless the file originated from a Unix system, the file mode is 753 | set to 0. 754 | 755 | SERIAL NUMBER 756 | ------------- 757 | 758 | set this field to 0. 759 | 760 | NUMBER OF FILES REMAINING 761 | ------------------------- 762 | 763 | This field is coded as a decimal number, and includes the 764 | current file. This field is an estimate, and incorrect values 765 | must not be allowed to cause loss of data. 766 | 767 | NUMBER OF BYTES REMAINING 768 | ------------------------- 769 | 770 | This field is coded as a decimal number, and includes the 771 | current file. This field is an estimate, and incorrect values 772 | must not be allowed to cause loss of data. 773 | 774 | FILE TYPE 775 | --------- 776 | 777 | set this field to 0. 778 | 779 | The file information is terminated by a null. If only the pathname 780 | is sent, the pathname is terminated with two nulls. The length of 781 | the file information subpacket, including the trailing null, must 782 | not exceed 1024 bytes; a typical length is less than 64 bytes. 783 | 784 | STREAMING TECHNIQUES / ERROR RECOVERY 785 | ------------------------------------- 786 | 787 | zmodem provides several data streaming methods 788 | selected according to the limitations of the sending environment, 789 | receiving environment, and transmission channel(s). 790 | 791 | WINDOW MANAGEMENT 792 | ----------------- 793 | 794 | When sending data through a network, some nodes of the network store 795 | data while it is transferred to the receiver. 7000 bytes and more of 796 | transient storage have been observed. Such a large amount of storage 797 | causes the transmitter to "get ahead" of the receiver. 798 | This condition is not fatal but it does slow error recovery. 799 | 800 | To manage the window size, the sending program uses ZCRCQ data 801 | subpackets to trigger ZACK headers from the receiver. The returning 802 | ZACK headers inform the sender of the receiver's progress. When the 803 | window size (current transmitter file offset - last reported receiver 804 | file offset) exceeds a specified value, the sender waits for a 805 | ZACK packet with a receiver file offset that reduces the window 806 | size. ZRPOS and other error packets are handled normally. 807 | 808 | FULL STREAMING WITH SAMPLING 809 | ---------------------------- 810 | 811 | If the receiver can overlap serial I/O with disk I/O, and if the 812 | sender can sample the reverse channel for the presence of data 813 | without having to wait, full streaming can be used with no Attn 814 | sequence required. The sender begins data transmission with a ZDATA 815 | header and continuous ZCRCG data subpackets. When the receiver 816 | detects an error, it executes the Attn sequence and then sends a 817 | ZRPOS header with the correct position within the file. 818 | 819 | At the end of each transmitted data subpacket, the sender checks for 820 | the presence of an error header from the receiver. To do this, the 821 | sender samples the reverse data stream for the presence of either a 822 | ZPAD or CAN character (using rdchk() or a similar mechanism) 823 | . Flow control characters (if present) are acted upon. 824 | 825 | Other characters (indicating line noise) increment a counter which is 826 | reset whenever the sender waits for a header from the receiver. If 827 | the counter overflows, the sender sends the next data subpacket as 828 | ZCRCW, and waits for a response. 829 | 830 | ZPAD indicates some sort of error header from the receiver. A CAN 831 | suggests the user is attempting to "stop the bubble machine" by 832 | keyboarding CAN characters. If one of these characters is seen, an 833 | empty ZCRCE data subpacket is sent. Normally, the receiver will have 834 | sent an ZRPOS or other error header, which will force the sender to 835 | resume transmission at a different address, or take other action. In 836 | the unlikely event the ZPAD or CAN character was spurious, the 837 | receiver will time out and send a ZRPOS header. 838 | The obvious choice of ZCRCW packet, which would trigger an ZACK from 839 | the receiver, is not used because multiple in transit frames could 840 | result if the channel has a long propagation delay. 841 | 842 | Then the receiver's response header is read and acted upon; starting 843 | with a resinchronize. 844 | 845 | A ZRPOS header resets the sender's file offset to the correct 846 | position. If possible, the sender should purge its output buffers 847 | and/or networks of all unprocessed output data, to minimize the 848 | amount of unwanted data the receiver must discard before receiving 849 | data starting at the correct file offset. The next transmitted data 850 | frame should be a ZCRCW frame followed by a wait to guarantee 851 | complete flushing of the network's memory. 852 | 853 | If the receiver gets a ZACK header with an address that disagrees 854 | with the sender address, it is ignored, and the sender waits for 855 | another header. A ZFIN, ZABORT, or TIMEOUT terminates the session; a 856 | ZSKIP terminates the processing of this file. 857 | 858 | The reverse channel is then sampled for the presence of another 859 | header from the receiver (if sampling is possible). if one is detected 860 | another error header is read. Otherwise, 861 | transmission resumes at the (possibly reset) file offset with a ZDATA 862 | header followed by data subpackets. 863 | 864 | FULL STREAMING WITH REVERSE INTERRUPT 865 | ------------------------------------- 866 | 867 | The above method cannot be used if the reverse data stream cannot be 868 | sampled without entering an I/O wait. An alternate method is to 869 | instruct the receiver to interrupt the sending program when an error 870 | is detected. 871 | 872 | The receiver can interrupt the sender with a control character, break 873 | signal, or combination thereof, as specified in the Attn sequence. 874 | After executing the Attn sequence, the receiver sends a hex ZRPOS 875 | header to force the sender to resend the lost data. 876 | 877 | When the sending program responds to this interrupt, it reads a HEX 878 | header (normally ZRPOS) from the receiver and takes the action 879 | described in the previous section. 880 | 881 | FULL STREAMING WITH SLIDING WINDOW 882 | ---------------------------------- 883 | 884 | If none of the above methods is applicable, hope is not yet lost. If 885 | the sender can buffer responses from the receiver, the sender can use 886 | ZCRCQ data subpackets to get ACKs from the receiver without 887 | interrupting the transmission of data. After a sufficient number of 888 | ZCRCQ data subpackets have been sent, the sender can read one of the 889 | headers that should have arrived in its receive interrupt buffer. 890 | 891 | A problem with this method is the possibility of wasting an excessive 892 | amount of time responding to the receiver's error header. It may be 893 | possible to program the receiver's Attn sequence to flush the 894 | sender's interrupt buffer before sending the ZRPOS header. 895 | 896 | SEGMENTED STREAMING 897 | ------------------- 898 | 899 | If the receiver cannot overlap serial and disk I/O, it uses the 900 | ZRINIT frame to specify a buffer length which the sender will not 901 | overflow. The sending program sends a ZCRCW data subpacket and waits 902 | for a ZACK header before sending the next segment of the file. 903 | 904 | A sufficiently large receiving buffer allows throughput to closely 905 | approach that of full streaming. For example, 16kb segmented 906 | streaming adds about 3 per cent to full streaming zmodem file 907 | transfer times when the round trip delay is five seconds. 908 | 909 | CONSTANTS 910 | --------- 911 | 912 | ASCII 913 | ----- 914 | 915 | SOH 0x01 916 | STX 0x02 917 | EOT 0x04 918 | ENQ 0x05 919 | ACK 0x06 920 | LF 0x0a 921 | CR 0x0d 922 | XON 0x11 923 | XOFF 0x13 924 | NAK 0x15 925 | CAN 0x18 926 | 927 | ZMODEM 928 | ------ 929 | 930 | ZPAD 0x2a /* pad character; begins frames */ 931 | ZDLE 0x18 /* ctrl-x zmodem escape */ 932 | ZDLEE 0x58 /* escaped ZDLE */ 933 | 934 | ZBIN 0x41 /* binary frame indicator (CRC16) */ 935 | ZHEX 0x42 /* hex frame indicator */ 936 | ZBIN32 0x43 /* binary frame indicator (CRC32) */ 937 | ZBINR32 0x44 /* run length encoded binary frame (CRC32) */ 938 | 939 | ZVBIN 0x61 /* binary frame indicator (CRC16) */ 940 | ZVHEX 0x62 /* hex frame indicator */ 941 | ZVBIN32 0x63 /* binary frame indicator (CRC32) */ 942 | ZVBINR32 0x64 /* run length encoded binary frame (CRC32) */ 943 | 944 | ZRESC 0x7e /* run length encoding flag / escape character */ 945 | 946 | FRAME TYPES 947 | ----------- 948 | 949 | ZRQINIT 0x00 /* request receive init (s->r) */ 950 | ZRINIT 0x01 /* receive init (r->s) */ 951 | ZSINIT 0x02 /* send init sequence (optional) (s->r) */ 952 | ZACK 0x03 /* ack to ZRQINIT ZRINIT or ZSINIT (s<->r) */ 953 | ZFILE 0x04 /* file name (s->r) */ 954 | ZSKIP 0x05 /* skip this file (r->s) */ 955 | ZNAK 0x06 /* last packet was corrupted (?) */ 956 | ZABORT 0x07 /* abort batch transfers (?) */ 957 | ZFIN 0x08 /* finish session (s<->r) */ 958 | ZRPOS 0x09 /* resume data transmission here (r->s) */ 959 | ZDATA 0x0a /* data packet(s) follow (s->r) */ 960 | ZEOF 0x0b /* end of file reached (s->r) */ 961 | ZFERR 0x0c /* fatal read or write error detected (?) */ 962 | ZCRC 0x0d /* request for file CRC and response (?) */ 963 | ZCHALLENGE 0x0e /* security challenge (r->s) */ 964 | ZCOMPL 0x0f /* request is complete (?) */ 965 | ZCAN 0x10 /* pseudo frame; 966 | other end cancelled session with 5* CAN */ 967 | ZFREECNT 0x11 /* request free bytes on file system (s->r) */ 968 | ZCOMMAND 0x12 /* issue command (s->r) */ 969 | ZSTDERR 0x13 /* output data to stderr (??) */ 970 | 971 | ZDLE SEQUENCES 972 | -------------- 973 | 974 | ZCRCE 0x68 /* CRC next, frame ends, header packet follows */ 975 | ZCRCG 0x69 /* CRC next, frame continues nonstop */ 976 | ZCRCQ 0x6a /* CRC next, frame continuous, ZACK expected */ 977 | ZCRCW 0x6b /* CRC next, ZACK expected, end of frame */ 978 | ZRUB0 0x6c /* translate to rubout 0x7f */ 979 | ZRUB1 0x6d /* translate to rubout 0xff */ 980 | 981 | RECEIVER CAPABILITY FLAGS 982 | ------------------------- 983 | 984 | CANFDX 0x01 /* Rx can send and receive true full duplex */ 985 | CANOVIO 0x02 /* Rx can receive data during disk I/O */ 986 | CANBRK 0x04 /* Rx can send a break signal */ 987 | CANCRY 0x08 /* Receiver can decrypt */ 988 | CANLZW 0x10 /* Receiver can uncompress */ 989 | CANFC32 0x20 /* Receiver can use 32 bit Frame Check */ 990 | ESCCTL 0x40 /* Receiver expects ctl chars to be escaped 991 | ESC8 0x80 /* Receiver expects 8th bit to be escaped */ 992 | 993 | 994 | -------------------------------------------------------------------------------- /doc/zmodem.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | The ZMODEM Inter Application File Transfer Protocol 5 | 6 | Chuck Forsberg 7 | 8 | Omen Technology Inc 9 | 10 | 11 | A overview of this document is available as ZMODEM.OV 12 | (in ZMDMOV.ARC) 13 | 14 | 15 | 16 | 17 | 18 | This file may be redistributed without restriction provided the text is 19 | not altered. 20 | 21 | Please distribute as widely as possible. 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | Omen Technology Incorporated 30 | The High Reliability Software 31 | 32 | 17505-V Northwest Sauvie Island Road 33 | Portland Oregon 97231 34 | VOICE: 503-621-3406 :VOICE 35 | Modem: 503-621-3746 Speed 1200,2400,19200(Telebit PEP) 36 | Compuserve:70007,2304 GEnie:CAF 37 | UUCP: ...!tektronix!reed!omen!caf 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | Chapter 0 Rev Oct-14-88 Typeset 10-14-88 1 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | Chapter 0 ZMODEM Protocol 2 71 | 72 | 73 | 74 | 1. INTENDED AUDIENCE 75 | 76 | This document is intended for telecommunications managers, systems 77 | programmers, and others who choose and implement asynchronous file 78 | transfer protocols over dial-up networks and related environments. 79 | 80 | 81 | 2. WHY DEVELOP ZMODEM? 82 | 83 | Since its development half a decade ago, the Ward Christensen MODEM 84 | protocol has enabled a wide variety of computer systems to interchange 85 | data. There is hardly a communications program that doesn't at least 86 | claim to support this protocol, now called XMODEM. 87 | 88 | Advances in computing, modems and networking have spread the XMODEM 89 | protocol far beyond the micro to micro environment for which it was 90 | designed. These application have exposed some weaknesses: 91 | 92 | + The awkward user interface is suitable for computer hobbyists. 93 | Multiple commands must be keyboarded to transfer each file. 94 | 95 | + Since commands must be given to both programs, simple menu selections 96 | are not possible. 97 | 98 | + The short block length causes throughput to suffer when used with 99 | timesharing systems, packet switched networks, satellite circuits, 100 | and buffered (error correcting) modems. 101 | 102 | + The 8 bit checksum and unprotected supervison allow undetected errors 103 | and disrupted file transfers. 104 | 105 | + Only one file can be sent per command. The file name has to be given 106 | twice, first to the sending program and then again to the receiving 107 | program. 108 | 109 | + The transmitted file accumulates as many as 127 bytes of garbage. 110 | 111 | + The modification date and other file attributes are lost. 112 | 113 | + XMODEM requires complete 8 bit transparency, all 256 codes. XMODEM 114 | will not operate over some networks that use ASCII flow control or 115 | escape codes. Setting network transparency disables important 116 | control functions for the duration of the call. 117 | 118 | A number of other protocols have been developed over the years, but none 119 | have proven satisfactory. 120 | 121 | + Lack of public domain documentation and example programs have kept 122 | proprietary protocols such as Relay, Blast, DART, and others tightly 123 | bound to the fortunes of their suppliers. These protocols have not 124 | benefited from public scrutiny of their design features. 125 | 126 | 127 | 128 | Chapter 2 Rev Oct-14-88 Typeset 10-14-88 2 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | Chapter 2 ZMODEM Protocol 3 137 | 138 | 139 | 140 | + Link level protocols such as X.25, X.PC, and MNP do not manage 141 | application to application file transfers. 142 | 143 | + Link Level protocols do not eliminate end-to-end errors. Interfaces 144 | between error-free networks are not necessarily error-free. 145 | Sometimes, error-free networks aren't. 146 | 147 | + The Kermit protocol was developed to allow file transfers in 148 | environments hostile to XMODEM. The performance compromises 149 | necessary to accommodate traditional mainframe environments limit 150 | Kermit's efficiency. Even with completely transparent channels, 151 | Kermit control character quoting limits the efficiency of binary file 152 | transfers to about 75 per cent.[1] 153 | 154 | A number of submodes are used in various Kermit programs, including 155 | different methods of transferring binary files. Two Kermit programs 156 | will mysteriously fail to operate with each other if the user has not 157 | correctly specified these submodes. 158 | 159 | Kermit Sliding Windows ("SuperKermit") improves throughput over 160 | networks at the cost of increased complexity. SuperKermit requires 161 | full duplex communications and the ability to check for the presence 162 | of characters in the input queue, precluding its implementation on 163 | some operating systems. 164 | 165 | SuperKermit state transitions are encoded in a special language 166 | "wart" which requires a C compiler. 167 | 168 | SuperKermit sends an ACK packet for each data packet of 96 bytes 169 | (fewer if control characters are present). This reduces throughput 170 | on high speed modems, from 1350 to 177 characters per second in one 171 | test. 172 | 173 | A number of extensions to the XMODEM protocol have been made to improve 174 | performance and (in some cases) the user interface. They provide useful 175 | improvements in some applications but not in others. XMODEM's unprotected 176 | control messages compromise their reliability. Complex proprietary 177 | techniques such as Cybernetic Data Recovery(TM)[2] improve reliability, 178 | but are not universally available. Some of the XMODEM mutant protocols 179 | have significant design flaws of their own. 180 | 181 | + XMODEM-k uses 1024 byte blocks to reduce the overhead from transmission 182 | delays by 87 per cent compared to XMODEM, but network delays still 183 | 184 | 185 | __________ 186 | 187 | 1. Some Kermit programs support run length encoding. 188 | 189 | 2. Unique to DSZ, ZCOMM, Professional-YAM and PowerCom 190 | 191 | 192 | 193 | 194 | Chapter 2 Rev Oct-14-88 Typeset 10-14-88 3 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | Chapter 2 ZMODEM Protocol 4 203 | 204 | 205 | 206 | degrade performance. Some networks cannot transmit 1024 byte packets 207 | without flow control, which is difficult to apply without impairing the 208 | perfect transparency required by XMODEM. XMODEM-k adds garbage to 209 | received files. 210 | 211 | + YMODEM sends the file name, file length, and creation date at the 212 | beginning of each file, and allows optional 1024 byte blocks for 213 | improved throughput. The handling of files that are not a multiple of 214 | 1024 or 128 bytes is awkward, especially if the file length is not 215 | known in advance, or changes during transmission. The large number of 216 | non conforming and substandard programs claiming to support YMODEM 217 | further complicates its use. 218 | 219 | + YMODEM-g provides efficient batch file transfers, preserving exact file 220 | length and file modification date. YMODEM-g is a modification to 221 | YMODEM wherein ACKs for data blocks are not used. YMODEM-g is 222 | essentially insensitive to network delays. Because it does not support 223 | error recovery, YMODEM-g must be used hard wired or with a reliable 224 | link level protocol. Successful application at high speed requires 225 | cafeful attention to transparent flow control. When YMODEM-g detects a 226 | CRC error, data transfers are aborted. YMODEM-g is easy to implement 227 | because it closely resembles standard YMODEM-1k. 228 | 229 | + WXMODEM, SEAlink, and MEGAlink have applied a subset of ZMODEM's 230 | techniques to "Classic XMODEM" to improve upon their suppliers' 231 | previous offerings. They provide good performance under ideal 232 | conditions. 233 | 234 | Another XMODEM "extension" is protocol cheating, such as Omen Technology's 235 | OverThruster(TM) and OverThruster II(TM). These improve XMODEM throughput 236 | under some conditions by compromising error recovery. 237 | 238 | The ZMODEM Protocol corrects the weaknesses described above while 239 | maintaining as much of XMODEM/CRC's simplicity and prior art as possible. 240 | 241 | 242 | 243 | 3. ZMODEM Protocol Design Criteria 244 | 245 | The design of a file transfer protocol is an engineering compromise 246 | between conflicting requirements: 247 | 248 | 3.1 Ease of Use 249 | 250 | + ZMODEM allows either program to initiate file transfers. 251 | 252 | + The sender can pass commands and/or modifiers to the receiving program. 253 | 254 | + File names need be entered only once. 255 | 256 | 257 | 258 | 259 | 260 | Chapter 3 Rev Oct-14-88 Typeset 10-14-88 4 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | Chapter 3 ZMODEM Protocol 5 269 | 270 | 271 | 272 | + Menu selections are supported. 273 | 274 | + Wild Card names may be used with batch transfers. 275 | 276 | + Minimum keystrokes required to initiate transfers. 277 | 278 | + ZRQINIT frame sent by sending program can trigger automatic downloads. 279 | 280 | + ZMODEM can optionally step down to YMODEM if the other end does not 281 | support ZMODEM.[1] 282 | 283 | 3.2 Throughput 284 | 285 | All file transfer protocols make tradeoffs between throughput, 286 | reliability, universality, and complexity according to the technology and 287 | knowledge base available to their designers. 288 | 289 | In the design of ZMODEM, three applications deserve special attention. 290 | 291 | + Network applications with significant delays (relative to character 292 | transmission time) and low error rate 293 | 294 | + Timesharing and buffered modem applications with significant delays 295 | and throughput that is quickly degraded by reverse channel traffic. 296 | ZMODEM's economy of reverse channel bandwidth allows modems that 297 | dynamically partition bandwidth between the two directions to operate 298 | at optimal speeds. Special ZMODEM features allow simple, efficient 299 | implementation on a wide variety of timesharing hosts. 300 | 301 | + Traditional direct modem to modem communications with high error rate 302 | 303 | Unlike Sliding Windows Kermit, ZMODEM is not optimized for optimum 304 | throughput when error rate and delays are both high. This tradeoff 305 | markedly reduces code complexity and memory requirements. ZMODEM 306 | generally provides faster error recovery than network compatible XMODEM 307 | implementations. 308 | 309 | In the absence of network delays, rapid error recovery is possible, much 310 | faster than MEGAlink and network compatible versions of YMODEM and XMODEM. 311 | 312 | File transfers begin immediately regardless of which program is started 313 | first, without the 10 second delay associated with XMODEM. 314 | 315 | 316 | 317 | 318 | 319 | __________ 320 | 321 | 1. Provided the transmission medium accommodates X/YMODEM. 322 | 323 | 324 | 325 | 326 | Chapter 3 Rev Oct-14-88 Typeset 10-14-88 5 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | Chapter 3 ZMODEM Protocol 6 335 | 336 | 337 | 338 | 3.3 Integrity and Robustness 339 | 340 | Once a ZMODEM session is begun, all transactions are protected with 16 or 341 | 32 bit CRC.[2] Complex proprietary techniques such as Omen Technology's 342 | Cybernetic Data Recovery(TM)[3] are not needed for reliable transfers. 343 | This complete protection of data and supervisory information accounts for 344 | most of ZMODEM's high reliability compared to XMODEM derived protocols 345 | including WXMODEM, SEAlink, MEGAlink, etc. 346 | 347 | An optional 32-bit CRC used as the frame check sequence in ADCCP (ANSI 348 | X3.66, also known as FIPS PUB 71 and FED-STD-1003, the U.S. versions of 349 | CCITT's X.25) is available. The 32 bit CRC reduces undetected errors by 350 | at least five orders of magnitude when properly applied (-1 preset, 351 | inversion). 352 | 353 | A security challenge mechanism guards against "Trojan Horse" messages 354 | written to mimic legitimate command or file downloads. 355 | 356 | 3.4 Ease of Implementation 357 | 358 | ZMODEM accommodates a wide variety of systems: 359 | 360 | + Microcomputers that cannot overlap disk and serial i/o 361 | 362 | + Microcomputers that cannot overlap serial send and receive 363 | 364 | + Computers and/or networks requiring XON/XOFF flow control 365 | 366 | + Computers that cannot check the serial input queue for the presence of 367 | data without having to wait for the data to arrive. 368 | 369 | Although ZMODEM provides "hooks" for multiple "threads", ZMODEM is not 370 | intended to replace link level protocols such as X.25. 371 | 372 | ZMODEM accommodates network and timesharing system delays by continuously 373 | transmitting data unless the receiver interrupts the sender to request 374 | retransmission of garbled data. ZMODEM in effect uses the entire file as 375 | a window.[4] Using the entire file as a window simplifies buffer 376 | management, avoiding the window overrun failure modes that affect 377 | MEGAlink, SuperKermit, and others. 378 | 379 | 380 | __________ 381 | 382 | 2. Except for the CAN-CAN-CAN-CAN-CAN abort sequence which requires five 383 | successive CAN characters. 384 | 385 | 3. Unique to Professional-YAM, ZCOMM, and PowerCom 386 | 387 | 4. Streaming strategies are discussed in coming chapters. 388 | 389 | 390 | 391 | 392 | Chapter 3 Rev Oct-14-88 Typeset 10-14-88 6 393 | 394 | 395 | 396 | 397 | 398 | 399 | 400 | Chapter 3 ZMODEM Protocol 7 401 | 402 | 403 | 404 | ZMODEM provides a general purpose application to application file transfer 405 | protocol which may be used directly or with with reliable link level 406 | protocols such as X.25, MNP, Fastlink, etc. When used with X.25, MNP, 407 | Fastlink, etc., ZMODEM detects and corrects errors in the interfaces 408 | between error controlled media and the remainder of the communications 409 | link. 410 | 411 | ZMODEM was developed for the public domain under a Telenet contract. The 412 | ZMODEM protocol descriptions and the Unix rz/sz program source code are 413 | public domain. No licensing, trademark, or copyright restrictions apply 414 | to the use of the protocol, the Unix rz/sz source code and the ZMODEM 415 | name. 416 | 417 | 418 | 4. EVOLUTION OF ZMODEM 419 | 420 | In early 1986, Telenet funded a project to develop an improved public 421 | domain application to application file transfer protocol. This protocol 422 | would alleviate the throughput problems network customers were 423 | experiencing with XMODEM and Kermit file transfers. 424 | 425 | In the beginning, we thought a few modifications to XMODEM would allow 426 | high performance over packet switched networks while preserving XMODEM's 427 | simplicity. 428 | 429 | The initial concept would add a block number to the ACK and NAK characters 430 | used by XMODEM. The resultant protocol would allow the sender to send 431 | more than one block before waiting for a response. 432 | 433 | But how to add the block number to XMODEM's ACK and NAK? WXMODEM, 434 | SEAlink, MEGAlink and some other protocols add binary byte(s) to indicate 435 | the block number. 436 | 437 | Pure binary was unsuitable for ZMODEM because binary code combinations 438 | won't pass bidirectionally through some modems, networks and operating 439 | systems. Other operating systems may not be able to recognize something 440 | coming back[1] unless a break signal or a system dependent code or 441 | sequence is present. By the time all this and other problems with the 442 | simple ACK/NAK sequences mentioned above were corrected, XMODEM's simple 443 | ACK and NACK characters had evolved into a real packet. The Frog was 444 | riveting. 445 | 446 | Managing the window[2] was another problem. Experience gained in 447 | 448 | 449 | __________ 450 | 451 | 1. Without stopping for a response 452 | 453 | 2. The WINDOW is the data in transit between sender and receiver. 454 | 455 | 456 | 457 | 458 | Chapter 4 Rev Oct-14-88 Typeset 10-14-88 7 459 | 460 | 461 | 462 | 463 | 464 | 465 | 466 | Chapter 4 ZMODEM Protocol 8 467 | 468 | 469 | 470 | debugging The Source's SuperKermit protocol indicated a window size of 471 | about 1000 characters was needed at 1200 bps. High speed modems require a 472 | window of 20000 or more characters for full throughput. Much of the 473 | SuperKermit's inefficiency, complexity and debugging time centered around 474 | its ring buffering and window management. There had to be a better way to 475 | get the job done. 476 | 477 | A sore point with XMODEM and its progeny is error recovery. More to the 478 | point, how can the receiver determine whether the sender has responded, or 479 | is ready to respond, to a retransmission request? XMODEM attacks the 480 | problem by throwing away characters until a certain period of silence. 481 | Too short a time allows a spurious pause in output (network or timesharing 482 | congestion) to masquerade as error recovery. Too long a timeout 483 | devastates throughput, and allows a noisy line to lock up the protocol. 484 | SuperKermit solves the problem with a distinct start of packet character 485 | (SOH). WXMODEM and ZMODEM use unique character sequences to delineate the 486 | start of frames. SEAlink and MEGAlink do not address this problem. 487 | 488 | A further error recovery problem arises in streaming protocols. How does 489 | the receiver know when (or if) the sender has recognized its error signal? 490 | Is the next packet the correct response to the error signal? Is it 491 | something left over "in the queue"? Or is this new subpacket one of many 492 | that will have to be discarded because the sender did not receive the 493 | error signal? How long should this continue before sending another error 494 | signal? How can the protocol prevent this from degenerating into an 495 | argument about mixed signals? 496 | 497 | SuperKermit uses selective retransmission, so it can accept any good 498 | packet it receives. Each time the SuperKermit receiver gets a data 499 | packet, it must decide which outstanding packet (if any) it "wants most" 500 | to receive, and asks for that one. In practice, complex software "hacks" 501 | are needed to attain acceptable robustness.[3] 502 | 503 | For ZMODEM, we decided to forgo the complexity of SuperKermit's packet 504 | assembly scheme and its associated buffer management logic and memory 505 | requirements. 506 | 507 | Another sore point with XMODEM and WXMODEM is the garbage added to files. 508 | This was acceptable with the old CP/M files which had no exact length, but 509 | not with newer systems such as PC-DOS and Unix. YMODEM uses file length 510 | information transmitted in the header block to trim the output file, but 511 | this causes data loss when transferring files that grow during a transfer. 512 | 513 | 514 | __________ 515 | 516 | 3. For example, when SuperKermit encounters certain errors, the wndesr 517 | function is called to determine the next block to request. A burst of 518 | errors generates several wasteful requests to retransmit the same 519 | block. 520 | 521 | 522 | 523 | 524 | Chapter 4 Rev Oct-14-88 Typeset 10-14-88 8 525 | 526 | 527 | 528 | 529 | 530 | 531 | 532 | Chapter 4 ZMODEM Protocol 9 533 | 534 | 535 | 536 | In some cases, the file length may be unknown, as when data is obtained 537 | from a process. Variable length data subpackets solve both of these 538 | problems. 539 | 540 | Since some characters had to be escaped anyway, there wasn't any point 541 | wasting bytes to fill out a fixed packet length or to specify a variable 542 | packet length. In ZMODEM, the length of data subpackets is denoted by 543 | ending each subpacket with an escape sequence similar to BISYNC and HDLC. 544 | 545 | The end result is a ZMOEM header containing a "frame type", four bytes of 546 | supervisory information, and its own CRC. Data frames consist of a header 547 | followed by 1 or more data subpackets. In the absence of transmission 548 | errors, an entire file can be sent in one data frame. 549 | 550 | Since the sending system may be sensitive to numerous control characters 551 | or strip parity in the reverse data path, all of the headers sent by the 552 | receiver are sent in hex. A common lower level routine receives all 553 | headers, allowing the main program logic to deal with headers and data 554 | subpackets as objects. 555 | 556 | With equivalent binary (efficient) and hex (application friendly) frames, 557 | the sending program can send an "invitation to receive" sequence to 558 | activate the receiver without crashing the remote application with 559 | unexpected control characters. 560 | 561 | Going "back to scratch" in the protocol design presents an opportunity to 562 | steal good ideas from many sources and to add a few new ones. 563 | 564 | From Kermit and UUCP comes the concept of an initial dialog to exchange 565 | system parameters. 566 | 567 | ZMODEM generalizes Compuserve B Protocol's host controlled transfers to 568 | single command AutoDownload and command downloading. A Security Challenge 569 | discourages password hackers and Trojan Horse authors from abusing 570 | ZMODEM's power. 571 | 572 | We were also keen to the pain and $uffering of legions of 573 | telecommunicators whose file transfers have been ruined by communications 574 | and timesharing faults. ZMODEM's file transfer recovery and advanced file 575 | management are dedicated to these kindred comrades. 576 | 577 | After ZMODEM had been operational a short time, Earl Hall pointed out the 578 | obvious: ZMODEM's user friendly AutoDownload was almost useless if the 579 | user must assign transfer options to each of the sending and receiving 580 | programs. Now, transfer options may be specified to/by the sending 581 | program, which passes them to the receiving program in the ZFILE header. 582 | 583 | 584 | 585 | 586 | 587 | 588 | 589 | 590 | Chapter 5 Rev Oct-14-88 Typeset 10-14-88 9 591 | 592 | 593 | 594 | 595 | 596 | 597 | 598 | Chapter 5 ZMODEM Protocol 10 599 | 600 | 601 | 602 | 5. ROSETTA STONE 603 | 604 | Here are some definitions which reflect current vernacular in the computer 605 | media. The attempt here is identify the file transfer protocol rather 606 | than specific programs. 607 | 608 | FRAME A ZMODEM frame consists of a header and 0 or more data subpackets. 609 | 610 | XMODEM refers to the original 1977 file transfer etiquette introduced by 611 | Ward Christensen's MODEM2 program. It's also called the MODEM or 612 | MODEM2 protocol. Some who are unaware of MODEM7's unusual batch 613 | file mode call it MODEM7. Other aliases include "CP/M Users's 614 | Group" and "TERM II FTP 3". This protocol is supported by most 615 | communications programs because it is easy to implement. 616 | 617 | XMODEM/CRC replaces XMODEM's 1 byte checksum with a two byte Cyclical 618 | Redundancy Check (CRC-16), improving error detection. 619 | 620 | XMODEM-1k Refers to XMODEM-CRC with optional 1024 byte blocks. 621 | 622 | YMODEM refers to the XMODEM/CRC protocol with batch transmission and 623 | optional 1024 byte blocks as described in YMODEM.DOC.[1] 624 | 625 | 626 | 6. ZMODEM REQUIREMENTS 627 | 628 | ZMODEM requires an 8 bit transfer medium.[1] ZMODEM escapes network 629 | control characters to allow operation with packet switched networks. In 630 | general, ZMODEM operates over any path that supports XMODEM, and over many 631 | that don't. 632 | 633 | To support full streaming,[2] the transmission path should either assert 634 | flow control or pass full speed transmission without loss of data. 635 | Otherwise the ZMODEM sender must manage the window size. 636 | 637 | 6.1 File Contents 638 | 639 | 6.1.1 Binary Files 640 | ZMODEM places no constraints on the information content of binary files, 641 | except that the number of bits in the file must be a multiple of 8. 642 | 643 | 644 | 645 | __________ 646 | 647 | 1. Available on TeleGodzilla as part of YZMODEM.ZOO 648 | 649 | 1. The ZMODEM design allows encoded packets for less transparent media. 650 | 651 | 2. With XOFF and XON, or out of band flow control such as X.25 or CTS 652 | 653 | 654 | 655 | 656 | Chapter 6 Rev Oct-14-88 Typeset 10-14-88 10 657 | 658 | 659 | 660 | 661 | 662 | 663 | 664 | Chapter 6 ZMODEM Protocol 11 665 | 666 | 667 | 668 | 6.1.2 Text Files 669 | Since ZMODEM is used to transfer files between different types of computer 670 | systems, text files must meet minimum requirements if they are to be 671 | readable on a wide variety of systems and environments. 672 | 673 | Text lines consist of printing ASCII characters, spaces, tabs, and 674 | backspaces. 675 | 676 | 6.1.2.1 ASCII End of Line 677 | The ASCII code definition allows text lines terminated by a CR/LF (015, 678 | 012) sequence, or by a NL (012) character. Lines logically terminated by 679 | a lone CR (013) are not ASCII text. 680 | 681 | A CR (013) without a linefeed implies overprinting, and is not acceptable 682 | as a logical line separator. Overprinted lines should print all important 683 | characters in the last pass to allow CRT displays to display meaningful 684 | text. Overstruck characters may be generated by backspacing or by 685 | overprinting the line with CR (015) not followed by LF. 686 | 687 | Overstruck characters generated with backspaces should be sent with the 688 | most important character last to accommodate CRT displays that cannot 689 | overstrike. The sending program may use the ZCNL bit to force the 690 | receiving program to convert the received end of line to its local end of 691 | line convention.[3] 692 | 693 | 694 | 695 | 696 | 697 | 698 | 699 | 700 | 701 | 702 | 703 | 704 | 705 | 706 | 707 | 708 | 709 | 710 | 711 | 712 | 713 | 714 | __________ 715 | 716 | 3. Files that have been translated in such a way as to modify their 717 | length cannot be updated with the ZCRECOV Conversion Option. 718 | 719 | 720 | 721 | 722 | Chapter 6 Rev Oct-14-88 Typeset 10-14-88 11 723 | 724 | 725 | 726 | 727 | 728 | 729 | 730 | Chapter 6 ZMODEM Protocol 12 731 | 732 | 733 | 734 | 7. ZMODEM BASICS 735 | 736 | 7.1 Packetization 737 | 738 | ZMODEM frames differ somewhat from XMODEM blocks. XMODEM blocks are not 739 | used for the following reasons: 740 | 741 | + Block numbers are limited to 256 742 | 743 | + No provision for variable length blocks 744 | 745 | + Line hits corrupt protocol signals, causing failed file transfers. In 746 | particular, modem errors sometimes generate false block numbers, false 747 | EOTs and false ACKs. False ACKs are the most troublesome as they cause 748 | the sender to lose synchronization with the receiver. 749 | 750 | State of the art programs such as Professional-YAM and ZCOMM overcome 751 | some of these weaknesses with clever proprietary code, but a stronger 752 | protocol is desired. 753 | 754 | + It is difficult to determine the beginning and ends of XMODEM blocks 755 | when line hits cause a loss of synchronization. This precludes rapid 756 | error recovery. 757 | 758 | 7.2 Link Escape Encoding 759 | 760 | ZMODEM achieves data transparency by extending the 8 bit character set 761 | (256 codes) with escape sequences based on the ZMODEM data link escape 762 | character ZDLE.[1] 763 | 764 | Link Escape coding permits variable length data subpackets without the 765 | overhead of a separate byte count. It allows the beginning of frames to 766 | be detected without special timing techniques, facilitating rapid error 767 | recovery. 768 | 769 | Link Escape coding does add some overhead. The worst case, a file 770 | consisting entirely of escaped characters, would incur a 50% overhead. 771 | 772 | The ZDLE character is special. ZDLE represents a control sequence of some 773 | sort. If a ZDLE character appears in binary data, it is prefixed with 774 | ZDLE, then sent as ZDLEE. 775 | 776 | The value for ZDLE is octal 030 (ASCII CAN). This particular value was 777 | chosen to allow a string of 5 consecutive CAN characters to abort a ZMODEM 778 | 779 | 780 | __________ 781 | 782 | 1. This and other constants are defined in the zmodem.h include file. 783 | Please note that constants with a leading 0 are octal constants in C. 784 | 785 | 786 | 787 | 788 | Chapter 7 Rev Oct-14-88 Typeset 10-14-88 12 789 | 790 | 791 | 792 | 793 | 794 | 795 | 796 | Chapter 7 ZMODEM Protocol 13 797 | 798 | 799 | 800 | session, compatible with YMODEM session abort. 801 | 802 | Since CAN is not used in normal terminal operations, interactive 803 | applications and communications programs can monitor the data flow for 804 | ZDLE. The following characters can be scanned to detect the ZRQINIT 805 | header, the invitation to automatically download commands or files. 806 | 807 | Receipt of five successive CAN characters will abort a ZMODEM session. 808 | Eight CAN characters are sent. 809 | 810 | The receiving program decodes any sequence of ZDLE followed by a byte with 811 | bit 6 set and bit 5 reset (upper case letter, either parity) to the 812 | equivalent control character by inverting bit 6. This allows the 813 | transmitter to escape any control character that cannot be sent by the 814 | communications medium. In addition, the receiver recognizes escapes for 815 | 0177 and 0377 should these characters need to be escaped. 816 | 817 | ZMODEM software escapes ZDLE, 020, 0220, 021, 0221, 023, and 0223. If 818 | preceded by 0100 or 0300 (@), 015 and 0215 are also escaped to protect the 819 | Telenet command escape CR-@-CR. The receiver ignores 021, 0221, 023, and 820 | 0223 characters in the data stream. 821 | 822 | The ZMODEM routines in zm.c accept an option to escape all control 823 | characters, to allow operation with less transparent networks. This 824 | option can be given to either the sending or receiving program. 825 | 826 | 7.3 Header 827 | 828 | All ZMODEM frames begin with a header which may be sent in binary or HEX 829 | form. ZMODEM uses a single routine to recognize binary and hex headers. 830 | Either form of the header contains the same raw information: 831 | 832 | + A type byte[2] [3] 833 | 834 | + Four bytes of data indicating flags and/or numeric quantities depending 835 | on the frame type 836 | 837 | 838 | 839 | 840 | 841 | 842 | 843 | __________ 844 | 845 | 2. The frame types are cardinal numbers beginning with 0 to minimize 846 | state transition table memory requirements. 847 | 848 | 3. Future extensions to ZMODEM may use the high order bits of the type 849 | byte to indicate thread selection. 850 | 851 | 852 | 853 | 854 | Chapter 7 Rev Oct-14-88 Typeset 10-14-88 13 855 | 856 | 857 | 858 | 859 | 860 | 861 | 862 | Chapter 7 ZMODEM Protocol 14 863 | 864 | 865 | 866 | Figure 1. Order of Bytes in Header 867 | 868 | TYPE: frame type 869 | F0: Flags least significant byte 870 | P0: file Position least significant 871 | P3: file Position most significant 872 | 873 | TYPE F3 F2 F1 F0 874 | ------------------- 875 | TYPE P0 P1 P2 P3 876 | 877 | 7.3.1 16 Bit CRC Binary Header 878 | A binary header is sent by the sending program to the receiving program. 879 | ZDLE encoding accommodates XON/XOFF flow control. 880 | 881 | A binary header begins with the sequence ZPAD, ZDLE, ZBIN. 882 | 883 | The frame type byte is ZDLE encoded. 884 | 885 | The four position/flags bytes are ZDLE encoded. 886 | 887 | A two byte CRC of the frame type and position/flag bytes is ZDLE encoded. 888 | 889 | 0 or more binary data subpackets with 16 bit CRC will follow depending on 890 | the frame type. 891 | 892 | The function zsbhdr transmits a binary header. The function zgethdr 893 | receives a binary or hex header. 894 | 895 | Figure 2. 16 Bit CRC Binary Header 896 | * ZDLE A TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 897 | 898 | 899 | 7.3.2 32 Bit CRC Binary Header 900 | A "32 bit CRC" Binary header is similar to a Binary Header, except the 901 | ZBIN (A) character is replaced by a ZBIN32 (C) character, and four 902 | characters of CRC are sent. 0 or more binary data subpackets with 32 bit 903 | CRC will follow depending on the frame type. 904 | 905 | The common variable Txfcs32 may be set TRUE for 32 bit CRC iff the 906 | receiver indicates the capability with the CANFC32 bit. The zgethdr, 907 | zsdata and zrdata functions automatically adjust to the type of Frame 908 | Check Sequence being used. 909 | Figure 3. 32 Bit CRC Binary Header 910 | * ZDLE C TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 CRC-3 CRC-4 911 | 912 | 913 | 7.3.3 HEX Header 914 | The receiver sends responses in hex headers. The sender also uses hex 915 | headers when they are not followed by binary data subpackets. 916 | 917 | 918 | 919 | 920 | Chapter 7 Rev Oct-14-88 Typeset 10-14-88 14 921 | 922 | 923 | 924 | 925 | 926 | 927 | 928 | Chapter 7 ZMODEM Protocol 15 929 | 930 | 931 | 932 | Hex encoding protects the reverse channel from random control characters. 933 | The hex header receiving routine ignores parity. 934 | 935 | Use of Kermit style encoding for control and paritied characters was 936 | considered and rejected because of increased possibility of interacting 937 | with some timesharing systems' line edit functions. Use of HEX headers 938 | from the receiving program allows control characters to be used to 939 | interrupt the sender when errors are detected. A HEX header may be used 940 | in place of a binary header wherever convenient. If a data packet follows 941 | a HEX header, it is protected with CRC-16. 942 | 943 | A hex header begins with the sequence ZPAD, ZPAD, ZDLE, ZHEX. The zgethdr 944 | routine synchronizes with the ZPAD-ZDLE sequence. The extra ZPAD 945 | character allows the sending program to detect an asynchronous header 946 | (indicating an error condition) and then call zgethdr to receive the 947 | header. 948 | 949 | The type byte, the four position/flag bytes, and the 16 bit CRC thereof 950 | are sent in hex using the character set 01234567890abcdef. Upper case hex 951 | digits are not allowed; they false trigger XMODEM and YMODEM programs. 952 | Since this form of hex encoding detects many patterns of errors, 953 | especially missing characters, a hex header with 32 bit CRC has not been 954 | defined. 955 | 956 | A carriage return and line feed are sent with HEX headers. The receive 957 | routine expects to see at least one of these characters, two if the first 958 | is CR. The CR/LF aids debugging from printouts, and helps overcome 959 | certain operating system related problems. 960 | 961 | An XON character is appended to all HEX packets except ZACK and ZFIN. The 962 | XON releases the sender from spurious XOFF flow control characters 963 | generated by line noise, a common occurrence. XON is not sent after ZACK 964 | headers to protect flow control in streaming situations. XON is not sent 965 | after a ZFIN header to allow clean session cleanup. 966 | 967 | 0 or more data subpackets will follow depending on the frame type. 968 | 969 | The function zshhdr sends a hex header. 970 | 971 | Figure 4. HEX Header 972 | 973 | * * ZDLE B TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 CR LF XON 974 | 975 | (TYPE, F3...F0, CRC-1, and CRC-2 are each sent as two hex digits.) 976 | 977 | 978 | 979 | 980 | 981 | 982 | 983 | 984 | 985 | 986 | Chapter 7 Rev Oct-14-88 Typeset 10-14-88 15 987 | 988 | 989 | 990 | 991 | 992 | 993 | 994 | Chapter 7 ZMODEM Protocol 16 995 | 996 | 997 | 998 | 7.4 Binary Data Subpackets 999 | 1000 | Binary data subpackets immediately follow the associated binary header 1001 | packet. A binary data packet contains 0 to 1024 bytes of data. 1002 | Recommended length values are 256 bytes below 2400 bps, 512 at 2400 bps, 1003 | and 1024 above 4800 bps or when the data link is known to be relatively 1004 | error free.[4] 1005 | 1006 | No padding is used with binary data subpackets. The data bytes are ZDLE 1007 | encoded and transmitted. A ZDLE and frameend are then sent, followed by 1008 | two or four ZDLE encoded CRC bytes. The CRC accumulates the data bytes 1009 | and frameend. 1010 | 1011 | The function zsdata sends a data subpacket. The function zrdata receives 1012 | a data subpacket. 1013 | 1014 | 7.5 ASCII Encoded Data Subpacket 1015 | 1016 | The format of ASCII Encoded data subpackets is not currently specified. 1017 | These could be used for server commands, or main transfers in 7 bit 1018 | environments. 1019 | 1020 | 1021 | 8. PROTOCOL TRANSACTION OVERVIEW 1022 | 1023 | As with the XMODEM recommendation, ZMODEM timing is receiver driven. The 1024 | transmitter should not time out at all, except to abort the program if no 1025 | headers are received for an extended period of time, say one minute.[1] 1026 | 1027 | 1028 | 8.1 Session Startup 1029 | 1030 | To start a ZMODEM file transfer session, the sending program is called 1031 | with the names of the desired file(s) and option(s). 1032 | 1033 | The sending program may send the string "rz\r" to invoke the receiving 1034 | program from a possible command mode. The "rz" followed by carriage 1035 | return activates a ZMODEM receive program or command if it were not 1036 | already active. 1037 | 1038 | The sender may then display a message intended for human consumption, such 1039 | 1040 | 1041 | __________ 1042 | 1043 | 4. Strategies for adjusting the subpacket length for optimal results 1044 | based on real time error rates are still evolving. Shorter subpackets 1045 | speed error detection but increase protocol overhead slightly. 1046 | 1047 | 1. Special considerations apply when sending commands. 1048 | 1049 | 1050 | 1051 | 1052 | Chapter 8 Rev Oct-14-88 Typeset 10-14-88 16 1053 | 1054 | 1055 | 1056 | 1057 | 1058 | 1059 | 1060 | Chapter 8 ZMODEM Protocol 17 1061 | 1062 | 1063 | 1064 | as a list of the files requested, etc. 1065 | 1066 | Then the sender may send a ZRQINIT header. The ZRQINIT header causes a 1067 | previously started receive program to send its ZRINIT header without 1068 | delay. 1069 | 1070 | In an interactive or conversational mode, the receiving application may 1071 | monitor the data stream for ZDLE. The following characters may be scanned 1072 | for B00 indicating a ZRQINIT header, a command to download a command or 1073 | data. 1074 | 1075 | The sending program awaits a command from the receiving program to start 1076 | file transfers. If a "C", "G", or NAK is received, an XMODEM or YMODEM 1077 | file transfer is indicated, and file transfer(s) use the YMODEM protocol. 1078 | Note: With ZMODEM and YMODEM, the sending program provides the file name, 1079 | but not with XMODEM. 1080 | 1081 | In case of garbled data, the sending program can repeat the invitation to 1082 | receive a number of times until a session starts. 1083 | 1084 | When the ZMODEM receive program starts, it immediately sends a ZRINIT 1085 | header to initiate ZMODEM file transfers, or a ZCHALLENGE header to verify 1086 | the sending program. The receive program resends its header at response 1087 | time (default 10 second) intervals for a suitable period of time (40 1088 | seconds total) before falling back to YMODEM protocol. 1089 | 1090 | If the receiving program receives a ZRQINIT header, it resends the ZRINIT 1091 | header. If the sending program receives the ZCHALLENGE header, it places 1092 | the data in ZP0...ZP3 in an answering ZACK header. 1093 | 1094 | If the receiving program receives a ZRINIT header, it is an echo 1095 | indicating that the sending program is not operational. 1096 | 1097 | Eventually the sending program correctly receives the ZRINIT header. 1098 | 1099 | The sender may then send an optional ZSINIT frame to define the receiving 1100 | program's Attn sequence, or to specify complete control character 1101 | escaping.[2] 1102 | 1103 | If the ZSINIT header specifies ESCCTL or ESC8, a HEX header is used, and 1104 | the receiver activates the specified ESC modes before reading the 1105 | following data subpacket. 1106 | 1107 | The receiver sends a ZACK header in response, containing either the serial 1108 | 1109 | 1110 | __________ 1111 | 1112 | 2. If the receiver specifies the same or higher level of escaping, the 1113 | ZSINIT frame need not be sent unless an Attn sequence is needed. 1114 | 1115 | 1116 | 1117 | 1118 | Chapter 8 Rev Oct-14-88 Typeset 10-14-88 17 1119 | 1120 | 1121 | 1122 | 1123 | 1124 | 1125 | 1126 | Chapter 8 ZMODEM Protocol 18 1127 | 1128 | 1129 | 1130 | number of the receiving program, or 0. 1131 | 1132 | 8.2 File Transmission 1133 | 1134 | The sender then sends a ZFILE header with ZMODEM Conversion, Management, 1135 | and Transport options[3] followed by a ZCRCW data subpacket containing the 1136 | file name, file length, modification date, and other information identical 1137 | to that used by YMODEM Batch. 1138 | 1139 | The receiver examines the file name, length, and date information provided 1140 | by the sender in the context of the specified transfer options, the 1141 | current state of its file system(s), and local security requirements. The 1142 | receiving program should insure the pathname and options are compatible 1143 | with its operating environment and local security requirements. 1144 | 1145 | The receiver may respond with a ZSKIP header, which makes the sender 1146 | proceed to the next file (if any) in the batch. 1147 | 1148 | The receiver has a file with the same name and length, may 1149 | respond with a ZCRC header with a byte count, which 1150 | requires the sender to perform a 32 bit CRC on the 1151 | specified number of bytes in the file and transmit the 1152 | complement of the CRC in an answering ZCRC header.[4] The 1153 | receiver uses this information to determine whether to 1154 | accept the file or skip it. This sequence may be triggered 1155 | by the ZMCRC Management Option. 1156 | 1157 | A ZRPOS header from the receiver initiates transmission of the file data 1158 | starting at the offset in the file specified in the ZRPOS header. 1159 | Normally the receiver specifies the data transfer to begin begin at 1160 | offset 0 in the file. 1161 | The receiver may start the transfer further down in the 1162 | file. This allows a file transfer interrupted by a loss 1163 | or carrier or system crash to be completed on the next 1164 | connection without requiring the entire file to be 1165 | retransmitted.[5] If downloading a file from a timesharing 1166 | system that becomes sluggish, the transfer can be 1167 | interrupted and resumed later with no loss of data. 1168 | 1169 | The sender sends a ZDATA binary header (with file position) followed by 1170 | 1171 | 1172 | __________ 1173 | 1174 | 3. See below, under ZFILE header type. 1175 | 1176 | 4. The crc is initialized to 0xFFFFFFFF. A byte count of 0 implies the 1177 | entire file. 1178 | 1179 | 5. This does not apply to files that have been translated. 1180 | 1181 | 1182 | 1183 | 1184 | Chapter 8 Rev Oct-14-88 Typeset 10-14-88 18 1185 | 1186 | 1187 | 1188 | 1189 | 1190 | 1191 | 1192 | Chapter 8 ZMODEM Protocol 19 1193 | 1194 | 1195 | 1196 | one or more data subpackets. 1197 | 1198 | The receiver compares the file position in the ZDATA header with the 1199 | number of characters successfully received to the file. If they do not 1200 | agree, a ZRPOS error response is generated to force the sender to the 1201 | right position within the file.[6] 1202 | 1203 | A data subpacket terminated by ZCRCG and CRC does not elicit a response 1204 | unless an error is detected; more data subpacket(s) follow immediately. 1205 | 1206 | ZCRCQ data subpackets expect a ZACK response with the 1207 | receiver's file offset if no error, otherwise a ZRPOS 1208 | response with the last good file offset. Another data 1209 | subpacket continues immediately. ZCRCQ subpackets are 1210 | not used if the receiver does not indicate FDX ability 1211 | with the CANFDX bit. 1212 | 1213 | ZCRCW data subpackets expect a response before the next frame is sent. 1214 | If the receiver does not indicate overlapped I/O capability with the 1215 | CANOVIO bit, or sets a buffer size, the sender uses the ZCRCW to allow 1216 | the receiver to write its buffer before sending more data. 1217 | 1218 | A zero length data frame may be used as an idle 1219 | subpacket to prevent the receiver from timing out in 1220 | case data is not immediately available to the sender. 1221 | 1222 | In the absence of fatal error, the sender eventually encounters end of 1223 | file. If the end of file is encountered within a frame, the frame is 1224 | closed with a ZCRCE data subpacket which does not elicit a response 1225 | except in case of error. 1226 | 1227 | The sender sends a ZEOF header with the file ending offset equal to 1228 | the number of characters in the file. The receiver compares this 1229 | number with the number of characters received. If the receiver has 1230 | received all of the file, it closes the file. If the file close was 1231 | satisfactory, the receiver responds with ZRINIT. If the receiver has 1232 | not received all the bytes of the file, the receiver ignores the ZEOF 1233 | because a new ZDATA is coming. If the receiver cannot properly close 1234 | the file, a ZFERR header is sent. 1235 | 1236 | 1237 | 1238 | 1239 | 1240 | 1241 | 1242 | __________ 1243 | 1244 | 6. If the ZMSPARS option is used, the receiver instead seeks to the 1245 | position given in the ZDATA header. 1246 | 1247 | 1248 | 1249 | 1250 | Chapter 8 Rev Oct-14-88 Typeset 10-14-88 19 1251 | 1252 | 1253 | 1254 | 1255 | 1256 | 1257 | 1258 | Chapter 8 ZMODEM Protocol 20 1259 | 1260 | 1261 | 1262 | After all files are processed, any further protocol 1263 | errors should not prevent the sending program from 1264 | returning with a success status. 1265 | 1266 | 1267 | 8.3 Session Cleanup 1268 | 1269 | The sender closes the session with a ZFIN header. The receiver 1270 | acknowledges this with its own ZFIN header. 1271 | 1272 | When the sender receives the acknowledging header, it sends two 1273 | characters, "OO" (Over and Out) and exits to the operating system or 1274 | application that invoked it. The receiver waits briefly for the "O" 1275 | characters, then exits whether they were received or not. 1276 | 1277 | 8.4 Session Abort Sequence 1278 | 1279 | If the receiver is receiving data in streaming mode, the Attn 1280 | sequence is executed to interrupt data transmission before the Cancel 1281 | sequence is sent. The Cancel sequence consists of eight CAN 1282 | characters and ten backspace characters. ZMODEM only requires five 1283 | Cancel characters, the other three are "insurance". 1284 | 1285 | The trailing backspace characters attempt to erase the effects of the 1286 | CAN characters if they are received by a command interpreter. 1287 | 1288 | static char canistr[] = { 1289 | 24,24,24,24,24,24,24,24,8,8,8,8,8,8,8,8,8,8,0 1290 | }; 1291 | 1292 | 1293 | 1294 | 1295 | 1296 | 1297 | 1298 | 1299 | 1300 | 1301 | 1302 | 1303 | 1304 | 1305 | 1306 | 1307 | 1308 | 1309 | 1310 | 1311 | 1312 | 1313 | 1314 | 1315 | 1316 | Chapter 8 Rev Oct-14-88 Typeset 10-14-88 20 1317 | 1318 | 1319 | 1320 | 1321 | 1322 | 1323 | 1324 | Chapter 8 ZMODEM Protocol 21 1325 | 1326 | 1327 | 1328 | 9. STREAMING TECHNIQUES / ERROR RECOVERY 1329 | 1330 | It is a fact of life that no single method of streaming is applicable 1331 | to a majority of today's computing and telecommunications 1332 | environments. ZMODEM provides several data streaming methods 1333 | selected according to the limitations of the sending environment, 1334 | receiving environment, and transmission channel(s). 1335 | 1336 | 1337 | 9.1 Full Streaming with Sampling 1338 | 1339 | If the receiver can overlap serial I/O with disk I/O, and if the 1340 | sender can sample the reverse channel for the presence of data 1341 | without having to wait, full streaming can be used with no Attn 1342 | sequence required. The sender begins data transmission with a ZDATA 1343 | header and continuous ZCRCG data subpackets. When the receiver 1344 | detects an error, it executes the Attn sequence and then sends a 1345 | ZRPOS header with the correct position within the file. 1346 | 1347 | At the end of each transmitted data subpacket, the sender checks for 1348 | the presence of an error header from the receiver. To do this, the 1349 | sender samples the reverse data stream for the presence of either a 1350 | ZPAD or CAN character.[1] Flow control characters (if present) are 1351 | acted upon. 1352 | 1353 | Other characters (indicating line noise) increment a counter which is 1354 | reset whenever the sender waits for a header from the receiver. If 1355 | the counter overflows, the sender sends the next data subpacket as 1356 | ZCRCW, and waits for a response. 1357 | 1358 | ZPAD indicates some sort of error header from the receiver. A CAN 1359 | suggests the user is attempting to "stop the bubble machine" by 1360 | keyboarding CAN characters. If one of these characters is seen, an 1361 | empty ZCRCE data subpacket is sent. Normally, the receiver will have 1362 | sent an ZRPOS or other error header, which will force the sender to 1363 | resume transmission at a different address, or take other action. In 1364 | the unlikely event the ZPAD or CAN character was spurious, the 1365 | receiver will time out and send a ZRPOS header.[2] 1366 | 1367 | Then the receiver's response header is read and acted upon.[3] 1368 | 1369 | 1370 | __________ 1371 | 1372 | 1. The call to rdchk() in sz.c performs this function. 1373 | 1374 | 2. The obvious choice of ZCRCW packet, which would trigger an ZACK from 1375 | the receiver, is not used because multiple in transit frames could 1376 | result if the channel has a long propagation delay. 1377 | 1378 | 3. The call to getinsync() in sz.c performs this function. 1379 | 1380 | 1381 | 1382 | Chapter 9 Rev Oct-14-88 Typeset 10-14-88 21 1383 | 1384 | 1385 | 1386 | 1387 | 1388 | 1389 | 1390 | Chapter 9 ZMODEM Protocol 22 1391 | 1392 | 1393 | 1394 | A ZRPOS header resets the sender's file offset to the correct 1395 | position. If possible, the sender should purge its output buffers 1396 | and/or networks of all unprocessed output data, to minimize the 1397 | amount of unwanted data the receiver must discard before receiving 1398 | data starting at the correct file offset. The next transmitted data 1399 | frame should be a ZCRCW frame followed by a wait to guarantee 1400 | complete flushing of the network's memory. 1401 | 1402 | If the receiver gets a ZACK header with an address that disagrees 1403 | with the sender address, it is ignored, and the sender waits for 1404 | another header. A ZFIN, ZABORT, or TIMEOUT terminates the session; a 1405 | ZSKIP terminates the processing of this file. 1406 | 1407 | The reverse channel is then sampled for the presence of another 1408 | header from the receiver.[4] if one is detected, the getinsync() 1409 | function is again called to read another error header. Otherwise, 1410 | transmission resumes at the (possibly reset) file offset with a ZDATA 1411 | header followed by data subpackets. 1412 | 1413 | 1414 | 9.1.1 Window Management 1415 | When sending data through a network, some nodes of the network store 1416 | data while it is transferred to the receiver. 7000 bytes and more of 1417 | transient storage have been observed. Such a large amount of storage 1418 | causes the transmitter to "get ahead" of the reciever. This can be 1419 | fatal with MEGAlink and other protocols that depend on timely 1420 | notification of errors from the receiver. This condition is not 1421 | fatal with ZMODEM, but it does slow error recovery. 1422 | 1423 | To manage the window size, the sending program uses ZCRCQ data 1424 | subpackets to trigger ZACK headers from the receiver. The returning 1425 | ZACK headers inform the sender of the receiver's progress. When the 1426 | window size (current transmitter file offset - last reported receiver 1427 | file offset) exceeds a specified value, the sender waits for a 1428 | ZACK[5] packet with a receiver file offset that reduces the window 1429 | size. 1430 | 1431 | Unix sz versions beginning with May 9 1987 control the window size 1432 | with the "-w N" option, where N is the maximum window size. Pro-YAM, 1433 | ZCOMM and DSZ versions beginning with May 9 1987 control the window 1434 | size with "zmodem pwN". This is compatible with previous versions of 1435 | these programs.[6] 1436 | 1437 | 1438 | __________ 1439 | 1440 | 4. If sampling is possible. 1441 | 1442 | 5. ZRPOS and other error packets are handled normally. 1443 | 1444 | 6. When used with modems or networks that simultaneously assert flow 1445 | 1446 | 1447 | 1448 | Chapter 9 Rev Oct-14-88 Typeset 10-14-88 22 1449 | 1450 | 1451 | 1452 | 1453 | 1454 | 1455 | 1456 | Chapter 9 ZMODEM Protocol 23 1457 | 1458 | 1459 | 1460 | 9.2 Full Streaming with Reverse Interrupt 1461 | 1462 | The above method cannot be used if the reverse data stream cannot be 1463 | sampled without entering an I/O wait. An alternate method is to 1464 | instruct the receiver to interrupt the sending program when an error 1465 | is detected. 1466 | 1467 | The receiver can interrupt the sender with a control character, break 1468 | signal, or combination thereof, as specified in the Attn sequence. 1469 | After executing the Attn sequence, the receiver sends a hex ZRPOS 1470 | header to force the sender to resend the lost data. 1471 | 1472 | When the sending program responds to this interrupt, it reads a HEX 1473 | header (normally ZRPOS) from the receiver and takes the action 1474 | described in the previous section. The Unix sz.c program uses a 1475 | setjmp/longjmp call to catch the interrupt generated by the Attn 1476 | sequence. Catching the interrupt activates the getinsync() function 1477 | to read the receiver's error header and take appropriate action. 1478 | 1479 | When compiled for standard SYSTEM III/V Unix, sz.c uses an Attn 1480 | sequence of Ctrl-C followed by a 1 second pause to interrupt the 1481 | sender, then give the sender (Unix) time to prepare for the 1482 | receiver's error header. 1483 | 1484 | 1485 | 9.3 Full Streaming with Sliding Window 1486 | 1487 | If none of the above methods is applicable, hope is not yet lost. If 1488 | the sender can buffer responses from the receiver, the sender can use 1489 | ZCRCQ data subpackets to get ACKs from the receiver without 1490 | interrupting the transmission of data. After a sufficient number of 1491 | ZCRCQ data subpackets have been sent, the sender can read one of the 1492 | headers that should have arrived in its receive interrupt buffer. 1493 | 1494 | A problem with this method is the possibility of wasting an excessive 1495 | amount of time responding to the receiver's error header. It may be 1496 | possible to program the receiver's Attn sequence to flush the 1497 | sender's interrupt buffer before sending the ZRPOS header. 1498 | 1499 | 1500 | 1501 | 1502 | 1503 | 1504 | 1505 | __________________________________________________________________________ 1506 | 1507 | control with XON and XOFF characters and pass XON characters that 1508 | violate flow control, the receiving program should have a revision 1509 | date of May 9 or later. 1510 | 1511 | 1512 | 1513 | 1514 | Chapter 9 Rev Oct-14-88 Typeset 10-14-88 23 1515 | 1516 | 1517 | 1518 | 1519 | 1520 | 1521 | 1522 | Chapter 9 ZMODEM Protocol 24 1523 | 1524 | 1525 | 1526 | 9.4 Full Streaming over Error Free Channels 1527 | 1528 | File transfer protocols predicated on the existence of an error free 1529 | end to end communications channel have been proposed from time to 1530 | time. Such channels have proven to be more readily available in 1531 | theory than in actuality. The frequency of undetected errors 1532 | increases when modem scramblers have more bits than the error 1533 | detecting CRC. 1534 | 1535 | A ZMODEM sender assuming an error free channel with end to end flow 1536 | control can send the entire file in one frame without any checking of 1537 | the reverse stream. If this channel is completely transparent, only 1538 | ZDLE need be escaped. The resulting protocol overhead for average 1539 | long files is less than one per cent.[7] 1540 | 1541 | 9.5 Segmented Streaming 1542 | 1543 | If the receiver cannot overlap serial and disk I/O, it uses the 1544 | ZRINIT frame to specify a buffer length which the sender will not 1545 | overflow. The sending program sends a ZCRCW data subpacket and waits 1546 | for a ZACK header before sending the next segment of the file. 1547 | 1548 | If the sending program supports reverse data stream sampling or 1549 | interrupt, error recovery will be faster (on average) than a protocol 1550 | (such as YMODEM) that sends large blocks. 1551 | 1552 | A sufficiently large receiving buffer allows throughput to closely 1553 | approach that of full streaming. For example, 16kb segmented 1554 | streaming adds about 3 per cent to full streaming ZMODEM file 1555 | transfer times when the round trip delay is five seconds. 1556 | 1557 | 1558 | 10. ATTENTION SEQUENCE 1559 | 1560 | The receiving program sends the Attn sequence whenever it detects an 1561 | error and needs to interrupt the sending program. 1562 | 1563 | The default Attn string value is empty (no Attn sequence). The 1564 | receiving program resets Attn to the empty default before each 1565 | transfer session. 1566 | 1567 | The sender specifies the Attn sequence in its optional ZSINIT frame. 1568 | The Attn string is terminated with a null. 1569 | 1570 | 1571 | 1572 | __________ 1573 | 1574 | 7. One in 256 for escaping ZDLE, about two (four if 32 bit CRC is used) 1575 | in 1024 for data subpacket CRC's 1576 | 1577 | 1578 | 1579 | 1580 | Chapter 10 Rev Oct-14-88 Typeset 10-14-88 24 1581 | 1582 | 1583 | 1584 | 1585 | 1586 | 1587 | 1588 | Chapter 10 ZMODEM Protocol 25 1589 | 1590 | 1591 | 1592 | Two meta-characters perform special functions: 1593 | 1594 | + \335 (octal) Send a break signal 1595 | 1596 | + \336 (octal) Pause one second 1597 | 1598 | 1599 | 11. FRAME TYPES 1600 | 1601 | The numeric values for the values shown in boldface are given in 1602 | zmodem.h. Unused bits and unused bytes in the header (ZP0...ZP3) are 1603 | set to 0. 1604 | 1605 | 11.1 ZRQINIT 1606 | 1607 | Sent by the sending program, to trigger the receiving program to send 1608 | its ZRINIT header. This avoids the aggravating startup delay 1609 | associated with XMODEM and Kermit transfers. The sending program may 1610 | repeat the receive invitation (including ZRQINIT) if a response is 1611 | not obtained at first. 1612 | 1613 | ZF0 contains ZCOMMAND if the program is attempting to send a command, 1614 | 0 otherwise. 1615 | 1616 | 11.2 ZRINIT 1617 | 1618 | Sent by the receiving program. ZF0 and ZF1 contain the bitwise or 1619 | of the receiver capability flags: 1620 | #define CANCRY 8 /* Receiver can decrypt */ 1621 | #define CANFDX 01 /* Rx can send and receive true FDX */ 1622 | #define CANOVIO 02 /* Rx can receive data during disk I/O */ 1623 | #define CANBRK 04 /* Rx can send a break signal */ 1624 | #define CANCRY 010 /* Receiver can decrypt */ 1625 | #define CANLZW 020 /* Receiver can uncompress */ 1626 | #define CANFC32 040 /* Receiver can use 32 bit Frame Check */ 1627 | #define ESCCTL 0100 /* Receiver expects ctl chars to be escaped 1628 | */ 1629 | #define ESC8 0200 /* Receiver expects 8th bit to be escaped */ 1630 | 1631 | ZP0 and ZP1 contain the size of the receiver's buffer in bytes, or 0 1632 | if nonstop I/O is allowed. 1633 | 1634 | 11.3 ZSINIT 1635 | 1636 | The Sender sends flags followed by a binary data subpacket terminated 1637 | with ZCRCW. 1638 | 1639 | /* Bit Masks for ZSINIT flags byte ZF0 */ 1640 | #define TESCCTL 0100 /* Transmitter expects ctl chars to be escaped 1641 | */ 1642 | #define TESC8 0200 /* Transmitter expects 8th bit to be escaped 1643 | 1644 | 1645 | 1646 | Chapter 11 Rev Oct-14-88 Typeset 10-14-88 25 1647 | 1648 | 1649 | 1650 | 1651 | 1652 | 1653 | 1654 | Chapter 11 ZMODEM Protocol 26 1655 | 1656 | 1657 | 1658 | */ 1659 | 1660 | The data subpacket contains the null terminated Attn sequence, 1661 | maximum length 32 bytes including the terminating null. 1662 | 1663 | 11.4 ZACK 1664 | 1665 | Acknowledgment to a ZSINIT frame, ZCHALLENGE header, ZCRCQ or ZCRCW 1666 | data subpacket. ZP0 to ZP3 contain file offset. The response to 1667 | ZCHALLENGE contains the same 32 bit number received in the ZCHALLENGE 1668 | header. 1669 | 1670 | 11.5 ZFILE 1671 | 1672 | This frame denotes the beginning of a file transmission attempt. 1673 | ZF0, ZF1, and ZF2 may contain options. A value of 0 in each of these 1674 | bytes implies no special treatment. Options specified to the 1675 | receiver override options specified to the sender with the exception 1676 | of ZCBIN. A ZCBIN from the sender overrides any other Conversion 1677 | Option given to the receiver except ZCRESUM. A ZCBIN from the 1678 | receiver overrides any other Conversion Option sent by the sender. 1679 | 1680 | 1681 | 11.5.1 ZF0: Conversion Option 1682 | If the receiver does not recognize the Conversion Option, an 1683 | application dependent default conversion may apply. 1684 | 1685 | ZCBIN "Binary" transfer - inhibit conversion unconditionally 1686 | 1687 | ZCNL Convert received end of line to local end of line 1688 | convention. The supported end of line conventions are 1689 | CR/LF (most ASCII based operating systems except Unix 1690 | and Macintosh), and NL (Unix). Either of these two end 1691 | of line conventions meet the permissible ASCII 1692 | definitions for Carriage Return and Line Feed/New Line. 1693 | Neither the ASCII code nor ZMODEM ZCNL encompass lines 1694 | separated only by carriage returns. Other processing 1695 | appropriate to ASCII text files and the local operating 1696 | system may also be applied by the receiver.[1] 1697 | 1698 | ZCRECOV Recover/Resume interrupted file transfer. ZCREVOV is 1699 | also useful for updating a remote copy of a file that 1700 | grows without resending of old data. If the destination 1701 | file exists and is no longer than the source, append to 1702 | the destination file and start transfer at the offset 1703 | 1704 | 1705 | __________ 1706 | 1707 | 1. Filtering RUBOUT, NULL, Ctrl-Z, etc. 1708 | 1709 | 1710 | 1711 | 1712 | Chapter 11 Rev Oct-14-88 Typeset 10-14-88 26 1713 | 1714 | 1715 | 1716 | 1717 | 1718 | 1719 | 1720 | Chapter 11 ZMODEM Protocol 27 1721 | 1722 | 1723 | 1724 | corresponding to the receiver's end of file. This 1725 | option does not apply if the source file is shorter. 1726 | Files that have been converted (e.g., ZCNL) or subject 1727 | to a single ended Transport Option cannot have their 1728 | transfers recovered. 1729 | 1730 | 11.5.2 ZF1: Management Option 1731 | If the receiver does not recognize the Management Option, the 1732 | file should be transferred normally. 1733 | 1734 | The ZMSKNOLOC bit instructs the receiver to bypass the 1735 | current file if the receiver does not have a file with the 1736 | same name. 1737 | 1738 | Five bits (defined by ZMMASK) define the following set of 1739 | mutually exclusive management options. 1740 | 1741 | ZMNEWL Transfer file if destination file absent. Otherwise, 1742 | transfer file overwriting destination if the source file 1743 | is newer or longer. 1744 | 1745 | ZMCRC Compare the source and destination files. Transfer if 1746 | file lengths or file polynomials differ. 1747 | 1748 | ZMAPND Append source file contents to the end of the existing 1749 | destination file (if any). 1750 | 1751 | ZMCLOB Replace existing destination file (if any). 1752 | 1753 | ZMDIFF Transfer file if destination file absent. Otherwise, 1754 | transfer file overwriting destination if files have 1755 | different lengths or dates. 1756 | 1757 | ZMPROT Protect destination file by transferring file only if 1758 | the destination file is absent. 1759 | 1760 | ZMNEW Transfer file if destination file absent. Otherwise, 1761 | transfer file overwriting destination if the source file 1762 | is newer. 1763 | 1764 | 11.5.3 ZF2: Transport Option 1765 | If the receiver does not implement the particular transport 1766 | option, the file is copied without conversion for later 1767 | processing. 1768 | 1769 | ZTLZW Lempel-Ziv compression. Transmitted data will be 1770 | identical to that produced by compress 4.0 operating on 1771 | a computer with VAX byte ordering, using 12 bit 1772 | encoding. 1773 | 1774 | 1775 | 1776 | 1777 | 1778 | Chapter 11 Rev Oct-14-88 Typeset 10-14-88 27 1779 | 1780 | 1781 | 1782 | 1783 | 1784 | 1785 | 1786 | Chapter 11 ZMODEM Protocol 28 1787 | 1788 | 1789 | 1790 | ZTCRYPT Encryption. An initial null terminated string 1791 | identifies the key. Details to be determined. 1792 | 1793 | ZTRLE Run Length encoding, Details to be determined. 1794 | 1795 | A ZCRCW data subpacket follows with file name, file length, 1796 | modification date, and other information described in a later 1797 | chapter. 1798 | 1799 | 11.5.4 ZF3: Extended Options 1800 | The Extended Options are bit encoded. 1801 | 1802 | ZTSPARS Special processing for sparse files, or sender managed 1803 | selective retransmission. Each file segment is transmitted as 1804 | a separate frame, where the frames are not necessarily 1805 | contiguous. The sender should end each segment with a ZCRCW 1806 | data subpacket and process the expected ZACK to insure no data 1807 | is lost. ZTSPARS cannot be used with ZCNL. 1808 | 1809 | 11.6 ZSKIP 1810 | 1811 | Sent by the receiver in response to ZFILE, makes the sender skip to 1812 | the next file. 1813 | 1814 | 11.7 ZNAK 1815 | 1816 | Indicates last header was garbled. (See also ZRPOS). 1817 | 1818 | 11.8 ZABORT 1819 | 1820 | Sent by receiver to terminate batch file transfers when requested by 1821 | the user. Sender responds with a ZFIN sequence.[2] 1822 | 1823 | 11.9 ZFIN 1824 | 1825 | Sent by sending program to terminate a ZMODEM session. Receiver 1826 | responds with its own ZFIN. 1827 | 1828 | 11.10 ZRPOS 1829 | 1830 | Sent by receiver to force file transfer to resume at file offset 1831 | given in ZP0...ZP3. 1832 | 1833 | 1834 | 1835 | 1836 | 1837 | __________ 1838 | 1839 | 2. Or ZCOMPL in case of server mode. 1840 | 1841 | 1842 | 1843 | 1844 | Chapter 11 Rev Oct-14-88 Typeset 10-14-88 28 1845 | 1846 | 1847 | 1848 | 1849 | 1850 | 1851 | 1852 | Chapter 11 ZMODEM Protocol 29 1853 | 1854 | 1855 | 1856 | 11.11 ZDATA 1857 | 1858 | ZP0...ZP3 contain file offset. One or more data subpackets follow. 1859 | 1860 | 11.12 ZEOF 1861 | 1862 | Sender reports End of File. ZP0...ZP3 contain the ending file 1863 | offset. 1864 | 1865 | 11.13 ZFERR 1866 | 1867 | Error in reading or writing file, protocol equivalent to ZABORT. 1868 | 1869 | 11.14 ZCRC 1870 | 1871 | Request (receiver) and response (sender) for file polynomial. 1872 | ZP0...ZP3 contain file polynomial. 1873 | 1874 | 11.15 ZCHALLENGE 1875 | 1876 | Request sender to echo a random number in ZP0...ZP3 in a ZACK frame. 1877 | Sent by the receiving program to the sending program to verify that 1878 | it is connected to an operating program, and was not activated by 1879 | spurious data or a Trojan Horse message. 1880 | 1881 | 11.16 ZCOMPL 1882 | 1883 | Request now completed. 1884 | 1885 | 11.17 ZCAN 1886 | 1887 | This is a pseudo frame type returned by gethdr() in response to a 1888 | Session Abort sequence. 1889 | 1890 | 11.18 ZFREECNT 1891 | 1892 | Sending program requests a ZACK frame with ZP0...ZP3 containing the 1893 | number of free bytes on the current file system. A value of 0 1894 | represents an indefinite amount of free space. 1895 | 1896 | 11.19 ZCOMMAND 1897 | 1898 | ZCOMMAND is sent in a binary frame. ZF0 contains 0 or ZCACK1 (see 1899 | below). 1900 | 1901 | A ZCRCW data subpacket follows, with the ASCII text command string 1902 | terminated with a NULL character. If the command is intended to be 1903 | executed by the operating system hosting the receiving program 1904 | (e.g., "shell escape"), it must have "!" as the first character. 1905 | Otherwise the command is meant to be executed by the application 1906 | program which receives the command. 1907 | 1908 | 1909 | 1910 | Chapter 11 Rev Oct-14-88 Typeset 10-14-88 29 1911 | 1912 | 1913 | 1914 | 1915 | 1916 | 1917 | 1918 | Chapter 11 ZMODEM Protocol 30 1919 | 1920 | 1921 | 1922 | If the receiver detects an illegal or badly formed command, the 1923 | receiver immediately responds with a ZCOMPL header with an error 1924 | code in ZP0...ZP3. 1925 | 1926 | If ZF0 contained ZCACK1, the receiver immediately responds with a 1927 | ZCOMPL header with 0 status. 1928 | 1929 | Otherwise, the receiver responds with a ZCOMPL header when the 1930 | operation is completed. The exit status of the completed command is 1931 | stored in ZP0...ZP3. A 0 exit status implies nominal completion of 1932 | the command. 1933 | 1934 | If the command causes a file to be transmitted, the command sender 1935 | will see a ZRQINIT frame from the other computer attempting to send 1936 | data. 1937 | 1938 | The sender examines ZF0 of the received ZRQINIT header to verify it 1939 | is not an echo of its own ZRQINIT header. It is illegal for the 1940 | sending program to command the receiving program to send a command. 1941 | 1942 | If the receiver program does not implement command downloading, it 1943 | may display the command to the standard error output, then return a 1944 | ZCOMPL header. 1945 | 1946 | 1947 | 1948 | 12. SESSION TRANSACTION EXAMPLES 1949 | 1950 | 12.1 A simple file transfer 1951 | 1952 | A simple transaction, one file, no errors, no CHALLENGE, overlapped 1953 | I/O: 1954 | 1955 | Sender Receiver 1956 | 1957 | "rz\r" 1958 | ZRQINIT(0) 1959 | ZRINIT 1960 | ZFILE 1961 | ZRPOS 1962 | ZDATA data ... 1963 | ZEOF 1964 | ZRINIT 1965 | ZFIN 1966 | ZFIN 1967 | OO 1968 | 1969 | 1970 | 1971 | 1972 | 1973 | 1974 | 1975 | 1976 | Chapter 12 Rev Oct-14-88 Typeset 10-14-88 30 1977 | 1978 | 1979 | 1980 | 1981 | 1982 | 1983 | 1984 | Chapter 12 ZMODEM Protocol 31 1985 | 1986 | 1987 | 1988 | 12.2 Challenge and Command Download 1989 | 1990 | 1991 | Sender Receiver 1992 | 1993 | "rz\r" 1994 | ZRQINIT(ZCOMMAND) 1995 | ZCHALLENGE(random-number) 1996 | ZACK(same-number) 1997 | ZRINIT 1998 | ZCOMMAND, ZDATA 1999 | (Performs Command) 2000 | ZCOMPL 2001 | ZFIN 2002 | ZFIN 2003 | OO 2004 | 2005 | 2006 | 13. ZFILE FRAME FILE INFORMATION 2007 | 2008 | ZMODEM sends the same file information with the ZFILE frame data 2009 | that YMODEM Batch sends in its block 0. 2010 | 2011 | N.B.: The pathname (file name) field is mandatory. 2012 | 2013 | Pathname The pathname (conventionally, the file name) is sent as a 2014 | null terminated ASCII string. This is the filename format used 2015 | by the handle oriented MSDOS(TM) functions and C library fopen 2016 | functions. An assembly language example follows: 2017 | DB 'foo.bar',0 2018 | No spaces are included in the pathname. Normally only the file 2019 | name stem (no directory prefix) is transmitted unless the 2020 | sender has selected YAM's f option to send the full absolute or 2021 | relative pathname. The source drive designator (A:, B:, etc.) 2022 | usually is not sent. 2023 | 2024 | Filename Considerations 2025 | 2026 | + File names should be translated to lower case unless the 2027 | sending system supports upper/lower case file names. This 2028 | is a convenience for users of systems (such as Unix) which 2029 | store filenames in upper and lower case. 2030 | 2031 | + The receiver should accommodate file names in lower and 2032 | upper case. 2033 | 2034 | + When transmitting files between different operating 2035 | systems, file names must be acceptable to both the sender 2036 | and receiving operating systems. If not, transformations 2037 | should be applied to make the file names acceptable. If 2038 | the transformations are unsuccessful, a new file name may 2039 | 2040 | 2041 | 2042 | Chapter 13 Rev Oct-14-88 Typeset 10-14-88 31 2043 | 2044 | 2045 | 2046 | 2047 | 2048 | 2049 | 2050 | Chapter 13 ZMODEM Protocol 32 2051 | 2052 | 2053 | 2054 | be invented be the receiving program. 2055 | 2056 | If directories are included, they are delimited by /; i.e., 2057 | "subdir/foo" is acceptable, "subdir\foo" is not. 2058 | 2059 | Length The file length and each of the succeeding fields are 2060 | optional.[1] The length field is stored as a decimal string 2061 | counting the number of data bytes in the file. 2062 | 2063 | The ZMODEM receiver uses the file length as an estimate only. 2064 | It may be used to display an estimate of the transmission time, 2065 | and may be compared with the amount of free disk space. The 2066 | actual length of the received file is determined by the data 2067 | transfer. A file may grow after transmission commences, and 2068 | all the data will be sent. 2069 | 2070 | Modification Date A single space separates the modification date 2071 | from the file length. 2072 | 2073 | The mod date is optional, and the filename and length may be 2074 | sent without requiring the mod date to be sent. 2075 | 2076 | The mod date is sent as an octal number giving the time the 2077 | contents of the file were last changed measured in seconds from 2078 | Jan 1 1970 Universal Coordinated Time (GMT). A date of 0 2079 | implies the modification date is unknown and should be left as 2080 | the date the file is received. 2081 | 2082 | This standard format was chosen to eliminate ambiguities 2083 | arising from transfers between different time zones. 2084 | 2085 | 2086 | File Mode A single space separates the file mode from the 2087 | modification date. The file mode is stored as an octal string. 2088 | Unless the file originated from a Unix system, the file mode is 2089 | set to 0. rz(1) checks the file mode for the 0x8000 bit which 2090 | indicates a Unix type regular file. Files with the 0x8000 bit 2091 | set are assumed to have been sent from another Unix (or 2092 | similar) system which uses the same file conventions. Such 2093 | files are not translated in any way. 2094 | 2095 | 2096 | Serial Number A single space separates the serial number from the 2097 | file mode. The serial number of the transmitting program is 2098 | stored as an octal string. Programs which do not have a serial 2099 | 2100 | 2101 | __________ 2102 | 2103 | 1. Fields may not be skipped. 2104 | 2105 | 2106 | 2107 | 2108 | Chapter 13 Rev Oct-14-88 Typeset 10-14-88 32 2109 | 2110 | 2111 | 2112 | 2113 | 2114 | 2115 | 2116 | Chapter 13 ZMODEM Protocol 33 2117 | 2118 | 2119 | 2120 | number should omit this field, or set it to 0. The receiver's 2121 | use of this field is optional. 2122 | 2123 | 2124 | Number of Files Remaining Iff the number of files remaining is sent, 2125 | a single space separates this field from the previous field. 2126 | This field is coded as a decimal number, and includes the 2127 | current file. This field is an estimate, and incorrect values 2128 | must not be allowed to cause loss of data. The receiver's use 2129 | of this field is optional. 2130 | 2131 | 2132 | Number of Bytes Remaining Iff the number of bytes remaining is sent, 2133 | a single space separates this field from the previous field. 2134 | This field is coded as a decimal number, and includes the 2135 | current file. This field is an estimate, and incorrect values 2136 | must not be allowed to cause loss of data. The receiver's use 2137 | of this field is optional. 2138 | 2139 | 2140 | File Type Iff the file type is sent, a single space separates this 2141 | field from the previous field. This field is coded as a 2142 | decimal number. Currently defined values are: 2143 | 2144 | 0 Sequential file - no special type 2145 | 2146 | 1 Other types to be defined. 2147 | The receiver's use of this field is optional. 2148 | 2149 | 2150 | The file information is terminated by a null. If only the pathname 2151 | is sent, the pathname is terminated with two nulls. The length of 2152 | the file information subpacket, including the trailing null, must 2153 | not exceed 1024 bytes; a typical length is less than 64 bytes. 2154 | 2155 | 2156 | 2157 | 2158 | 14. PERFORMANCE RESULTS 2159 | 2160 | 14.1 Compatibility 2161 | 2162 | Extensive testing has demonstrated ZMODEM to be compatible with 2163 | satellite links, packet switched networks, microcomputers, 2164 | minicomputers, regular and error correcting buffered modems at 75 to 2165 | 19200 bps. ZMODEM's economy of reverse channel bandwidth allows 2166 | modems that dynamically partition bandwidth between the two 2167 | directions to operate at optimal speeds. 2168 | 2169 | 2170 | 2171 | 2172 | 2173 | 2174 | Chapter 14 Rev Oct-14-88 Typeset 10-14-88 33 2175 | 2176 | 2177 | 2178 | 2179 | 2180 | 2181 | 2182 | Chapter 14 ZMODEM Protocol 34 2183 | 2184 | 2185 | 2186 | 14.2 Throughput 2187 | 2188 | Between two single task PC-XT computers sending a program image on 2189 | an in house Telenet link, SuperKermit provided 72 ch/sec throughput 2190 | at 1200 baud. YMODEM-k yielded 85 chars/sec, and ZMODEM provided 2191 | 113 chars/sec. XMODEM was not measured, but would have been much 2192 | slower based on observed network propagation delays. 2193 | 2194 | Recent tests downloading large binary files to an IBM PC (4.7 mHz 2195 | V20) running YAMK 16.30 with table driven 32 bit CRC calculation 2196 | yielded a throughput of 1870 cps on a 19200 bps direct connection. 2197 | 2198 | Tests with TELEBIT TrailBlazer modems have shown transfer rates 2199 | approaching 1400 characters per second for long files. When files 2200 | are compressed, effective transfer rates of 2000 characters per 2201 | second are possible. 2202 | 2203 | 2204 | 14.3 Error Recovery 2205 | 2206 | Some tests of ZMODEM protocol error recovery performance have been 2207 | made. A PC-AT with SCO SYS V Xenix or DOS 3.1 was connected to a PC 2208 | with DOS 2.1 either directly at 9600 bps or with unbuffered dial-up 2209 | 1200 bps modems. The ZMODEM software was configured to use 1024 2210 | byte data subpacket lengths above 2400 bps, 256 otherwise. 2211 | 2212 | Because no time delays are necessary in normal file transfers, per 2213 | file negotiations are much faster than with YMODEM, the only 2214 | observed delay being the time required by the program(s) to update 2215 | logging files. 2216 | 2217 | During a file transfer, a short line hit seen by the receiver 2218 | usually induces a CRC error. The interrupt sequence is usually seen 2219 | by the sender before the next data subpacket is completely sent, and 2220 | the resultant loss of data throughput averages about half a data 2221 | subpacket per line hit. At 1200 bps this is would be about .75 2222 | second lost per hit. At 10-5 error rate, this would degrade 2223 | throughput by about 9 per cent. 2224 | 2225 | The throughput degradation increases with increasing channel delay, 2226 | as more data subpackets in transit through the channel are discarded 2227 | when an error is detected. 2228 | 2229 | A longer noise burst that affects both the receiver and the sender's 2230 | reception of the interrupt sequence usually causes the sender to 2231 | remain silent until the receiver times out in 10 seconds. If the 2232 | round trip channel delay exceeds the receiver's 10 second timeout, 2233 | recovery from this type of error may become difficult. 2234 | 2235 | Noise affecting only the sender is usually ignored, with one common 2236 | exception. Spurious XOFF characters generated by noise stop the 2237 | 2238 | 2239 | 2240 | Chapter 14 Rev Oct-14-88 Typeset 10-14-88 34 2241 | 2242 | 2243 | 2244 | 2245 | 2246 | 2247 | 2248 | Chapter 14 ZMODEM Protocol 35 2249 | 2250 | 2251 | 2252 | sender until the receiver times out and sends an interrupt sequence 2253 | which concludes with an XON. 2254 | 2255 | In summation, ZMODEM performance in the presence of errors resembles 2256 | that of X.PC and SuperKermit. Short bursts cause minimal data 2257 | retransmission. Long bursts (such as pulse dialing noises) often 2258 | require a timeout error to restore the flow of data. 2259 | 2260 | 2261 | 15. PACKET SWITCHED NETWORK CONSIDERATIONS 2262 | 2263 | Flow control is necessary for printing messages and directories, and 2264 | for streaming file transfer protocols. A non transparent flow 2265 | control is incompatible with XMODEM and YMODEM transfers. XMODEM 2266 | and YMODEM protocols require complete transparency of all 256 8 bit 2267 | codes to operate properly. 2268 | 2269 | The "best" flow control (when X.25 or hardware CTS is unavailable) 2270 | would not "eat" any characters at all. When the PAD's buffer almost 2271 | fills up, an XOFF should be emitted. When the buffer is no longer 2272 | nearly full, send an XON. Otherwise, the network should neither 2273 | generate nor eat XON or XOFF control characters. 2274 | 2275 | On Telenet, this can be met by setting CCIT X3 5:1 and 12:0 at both 2276 | ends of the network. For best throughput, parameter 64 (advance 2277 | ACK) should be set to something like 4. Packets should be forwarded 2278 | when the packet is a full 128 bytes, or after a moderate delay 2279 | (3:0,4:10,6:0). 2280 | 2281 | With PC-Pursuit, it is sufficient to set parameter 5 to 1 at both 2282 | ends after one is connected to the remote modem. 2283 | 2284 | @ 2285 | set 5:1 2286 | rst? 5:1 2287 | cont 2288 | 2289 | Unfortunately, many PADs do not accept the "rst?" command. 2290 | 2291 | For YMODEM, PAD buffering should guarantee that a minimum of 1040 2292 | characters can be sent in a burst without loss of data or generation 2293 | of flow control characters. Failure to provide this buffering will 2294 | generate excessive retries with YMODEM. 2295 | 2296 | 2297 | 2298 | 2299 | 2300 | 2301 | 2302 | 2303 | 2304 | 2305 | 2306 | Chapter 15 Rev Oct-14-88 Typeset 10-14-88 35 2307 | 2308 | 2309 | 2310 | 2311 | 2312 | 2313 | 2314 | Chapter 15 ZMODEM Protocol 36 2315 | 2316 | 2317 | 2318 | TABLE 1. Network and Flow Control Compatibility 2319 | 2320 | ______________________________________________________________________________ 2321 | | Connectivity | Interactive| XMODEM| WXMODEM| SUPERKERMIT| ZMODEM | 2322 | ______________________________________________________________________________ 2323 | |___________________|_____________|________|_________|_____________|_________| 2324 | |Direct Connect | YES | YES | YES | YES | YES | 2325 | |___________________|_____________|________|_________|_____________|_________| 2326 | |Network, no FC | no | YES | (4) | (6) | YES (1)| 2327 | |___________________|_____________|________|_________|_____________|_________| 2328 | |Net, transparent FC| YES | YES | YES | YES | YES | 2329 | |___________________|_____________|________|_________|_____________|_________| 2330 | |Net, non-trans. FC | YES | no | no (5) | YES | YES | 2331 | |___________________|_____________|________|_________|_____________|_________| 2332 | |Network, 7 bit | YES | no | no | YES (2) | YES (3)| 2333 | |___________________|_____________|________|_________|_____________|_________| 2334 | 2335 | (1) ZMODEM can optimize window size or burst length for fastest 2336 | transfers. 2337 | (2) Parity bits must be encoded, slowing binary transfers. 2338 | (3) Natural protocol extension possible for encoding data to 7 bits. 2339 | (4) Small WXMODEM window size may may allow operation. 2340 | (5) Some flow control codes are not escaped in WXMODEM. 2341 | (6) Kermit window size must be reduced to avoid buffer overrun. 2342 | 2343 | 2344 | 16. PERFORMANCE COMPARISON TABLES 2345 | 2346 | 2347 | "Round Trip Delay Time" includes the time for the last byte in a 2348 | packet to propagate through the operating systems and network to the 2349 | receiver, plus the time for the receiver's response to that packet 2350 | to propagate back to the sender. 2351 | 2352 | The figures shown below are calculated for round trip delay times of 2353 | 40 milliseconds and 5 seconds. Shift registers in the two computers 2354 | and a pair of 212 modems generate a round trip delay time on the 2355 | order of 40 milliseconds. Operation with busy timesharing computers 2356 | and networks can easily generate round trip delays of five seconds. 2357 | Because the round trip delays cause visible interruptions of data 2358 | transfer when using XMODEM protocol, the subjective effect of these 2359 | delays is greatly exaggerated, especially when the user is paying 2360 | for connect time. 2361 | 2362 | A 102400 byte binary file with randomly distributed codes is sent at 2363 | 1200 bps 8 data bits, 1 stop bit. The calculations assume no 2364 | transmission errors. For each of the protocols, only the per file 2365 | functions are considered. Processor and I/O overhead are not 2366 | included. YM-k refers to YMODEM with 1024 byte data packets. YM-g 2367 | refers to the YMODEM "g" option. ZMODEM uses 256 byte data 2368 | subpackets for this example. SuperKermit uses maximum standard 2369 | 2370 | 2371 | 2372 | Chapter 16 Rev Oct-14-88 Typeset 10-14-88 36 2373 | 2374 | 2375 | 2376 | 2377 | 2378 | 2379 | 2380 | Chapter 16 ZMODEM Protocol 37 2381 | 2382 | 2383 | 2384 | packet size, 8 bit transparent transmission, no run length 2385 | compression. The 4 block WXMODEM window is too small to span the 5 2386 | second delay in this example; the resulting thoughput degradation is 2387 | ignored. 2388 | 2389 | For comparison, a straight "dump" of the file contents with no file 2390 | management or error checking takes 853 seconds. 2391 | 2392 | TABLE 2. Protocol Overhead Information 2393 | (102400 byte binary file, 5 Second Round Trip) 2394 | 2395 | ____________________________________________________________________________ 2396 | | Protocol | XMODEM| YM-k | YM-g| ZMODEM| SKermit| WXMODEM| 2397 | ____________________________________________________________________________ 2398 | |_____________________|________|_______|______|________|_________|_________| 2399 | |Protocol Round Trips | 804 | 104 | 5 | 5 | 5 | 4 | 2400 | |_____________________|________|_______|______|________|_________|_________| 2401 | |Trip Time at 40ms | 32s | 4s | 0 | 0 | 0 | 0 | 2402 | |_____________________|________|_______|______|________|_________|_________| 2403 | |Trip Time at 5s | 4020s | 520s | 25s | 25s | 25 | 20 | 2404 | ____________________________________________________________________________ 2405 | |_____________________|________|_______|______|________|_________|_________| 2406 | |Overhead Characters | 4803 | 603 | 503 | 3600 | 38280 | 8000 | 2407 | ____________________________________________________________________________ 2408 | |_____________________|________|_______|______|________|_________|_________| 2409 | |Line Turnarounds | 1602 | 204 | 5 | 5 | 2560 | 1602 | 2410 | ____________________________________________________________________________ 2411 | |_____________________|________|_______|______|________|_________|_________| 2412 | |Transfer Time at 0s | 893s | 858s | 857s| 883s | 1172s | 916s | 2413 | |_____________________|________|_______|______|________|_________|_________| 2414 | |Transfer Time at 40ms| 925s | 862s | 857s| 883s | 1172s | 916s | 2415 | |_____________________|________|_______|______|________|_________|_________| 2416 | |Transfer Time at 5s | 5766s | 1378s| 882s| 918s | 1197s | 936s | 2417 | |_____________________|________|_______|______|________|_________|_________| 2418 | 2419 | 2420 | Figure 5. Transmission Time Comparison 2421 | (102400 byte binary file, 5 Second Round Trip) 2422 | 2423 | ************************************************** XMODEM 2424 | ************ YMODEM-K 2425 | ********** SuperKermit (Sliding Windows) 2426 | ******* ZMODEM 16kb Segmented Streaming 2427 | ******* ZMODEM Full Streaming 2428 | ******* YMODEM-G 2429 | 2430 | 2431 | 2432 | 2433 | 2434 | 2435 | 2436 | 2437 | 2438 | Chapter 16 Rev Oct-14-88 Typeset 10-14-88 37 2439 | 2440 | 2441 | 2442 | 2443 | 2444 | 2445 | 2446 | Chapter 16 ZMODEM Protocol 38 2447 | 2448 | 2449 | 2450 | TABLE 3. Local Timesharing Computer Download Performance 2451 | 2452 | __________________________________________________________________________ 2453 | | Command | Protocol| Time/HD| Time/FD| Throughput| Efficiency| 2454 | __________________________________________________________________________ 2455 | |_______________|__________|_________|_________|____________|____________| 2456 | |kermit -x | Kermit | 1:49 | 2:03 | 327 | 34% | 2457 | |_______________|__________|_________|_________|____________|____________| 2458 | |sz -Xa phones.t| XMODEM | 1:20 | 1:44 | 343 | 36% | 2459 | |_______________|__________|_________|_________|____________|____________| 2460 | |sz -a phones.t | ZMODEM | :39 | :48 | 915 | 95% | 2461 | |_______________|__________|_________|_________|____________|____________| 2462 | 2463 | 2464 | Times were measured downloading a 35721 character text file at 9600 2465 | bps, from Santa Cruz SysV 2.1.2 Xenix on a 9 mHz IBM PC-AT to DOS 2466 | 2.1 on an IBM PC. Xenix was in multiuser mode but otherwise idle. 2467 | Transfer times to PC hard disk and floppy disk destinations are 2468 | shown. 2469 | 2470 | C-Kermit 4.2(030) used server mode and file compression, sending to 2471 | Pro-YAM 15.52 using 0 delay and a "get phones.t" command. 2472 | 2473 | Crosstalk XVI 3.6 used XMODEM 8 bit checksum (CRC not available) and 2474 | an "ESC rx phones.t" command. The Crosstalk time does not include 2475 | the time needed to enter the extra commands not needed by Kermit and 2476 | ZMODEM. 2477 | 2478 | Professional-YAM used ZMODEM AutoDownload. ZMODEM times included a 2479 | security challenge to the sending program. 2480 | 2481 | 2482 | 2483 | 2484 | 2485 | 2486 | 2487 | 2488 | 2489 | 2490 | 2491 | 2492 | 2493 | 2494 | 2495 | 2496 | 2497 | 2498 | 2499 | 2500 | 2501 | 2502 | 2503 | 2504 | Chapter 16 Rev Oct-14-88 Typeset 10-14-88 38 2505 | 2506 | 2507 | 2508 | 2509 | 2510 | 2511 | 2512 | Chapter 16 ZMODEM Protocol 39 2513 | 2514 | 2515 | 2516 | TABLE 4. File Transfer Speeds 2517 | 2518 | ______________________________________________________________________________ 2519 | | Prot file bytes bps ch/sec Notes | 2520 | ______________________________________________________________________________ 2521 | |X jancol.c 18237 2400 53 Tymnet PTL 5/3/87 | 2522 | |X source.xxx 6143 2400 56 Source PTL 5/29/87 | 2523 | |X jancol.c 18237 2400 64 Tymnet PTL | 2524 | |XN tsrmaker.arc 25088 1200 94 GEnie PTL | 2525 | |B/ovth emaibm.arc 51200 1200 101 CIS PTL MNP | 2526 | |UUCP 74 files, each >7000 1200 102 (Average) | 2527 | |ZM jancol.c 18237 1200 112 DataPac (604-687-7144)| 2528 | |X/ovth emaibm.arc 51200 1200 114 CIS PTL MNP | 2529 | |ZM emaibm.arc 51200 1200 114 CIS PTL MNP | 2530 | |ZM frombyte87.txt 62506 1200 117 BIX | 2531 | |SK source.xxx 6143 2400 170 Source PTL 5/29/87 | 2532 | |ZM jancol.c 18237 2400 221 Tymnet PTL upl/dl | 2533 | |B/ovth destro.gif 33613 2400 223 CIS/PTL 9-12-87 | 2534 | |ZM jancol.c 18237 2400 224 Tymnet PTL | 2535 | |ZM tp40kerm.arc 112640 2400 224 BIX 6/88 | 2536 | |ZM readme.lis 9466 2400 231 BIX 6/88 | 2537 | |ZM jancol.c 18237 2400 226/218 TeleGodzilla upl | 2538 | |ZM jancol.c 18237 2400 226 Tymnet PTL 5/3/87 | 2539 | |ZM zmodem.ov 35855 2400 227 CIS PTL node | 2540 | |C jancol.c 18237 2400 229 Tymnet PTL 5/3/87 | 2541 | |ZM jancol.c 18237 2400 229/221 TeleGodzilla | 2542 | |ZM zmodem.ov 35855 2400 229 CIS PTL node upl | 2543 | |ZM jancol.c 18237 2400 232 CIS PTL node | 2544 | |QB gifeof.arc 32187 2400 232 CIS PTL node | 2545 | |ZM pcpbbs.txt 38423 2400 534 MNP Level 5 | 2546 | |ZM mbox 473104 9600 948/942 TeleGodzilla upl | 2547 | |ZM zmodem.arc 318826 14k 1357/1345 TeleGodzilla | 2548 | |ZM mbox 473104 14k 1367/1356 TeleGodzilla upl | 2549 | |ZM c2.doc 218823 38k 3473 Xenix 386 TK upl | 2550 | |ZM mbox -a 511893 38k 3860 386 Xenix 2.2 Beta | 2551 | |ZM c.doc 218823 57k 5611 AT Clone & 386 | 2552 | |____________________________________________________________________________| 2553 | 2554 | Times are for downloads unless noted. Where two speeds are noted, 2555 | the faster speed is reported by the receiver because its transfer 2556 | time calculation excludes the security check and transaction log 2557 | file processing. The TeleGodzilla computer is a 4.77 mHz IBM PC 2558 | with a 10 MB hard disk. The 386 computer uses an Intel motherboard 2559 | at 18 mHz 1ws. The AT Clone (QIC) runs at 8 mHz 0ws. 2560 | Abbreviations: 2561 | B Compuserve B Protocol 2562 | QB Compuserve Quick-B/B+ Protocol 2563 | B/ovth CIS B with Omen Technology OverThruster(TM) 2564 | C Capture DC2/DC4 (no protocol) 2565 | K Kermit 2566 | MNP Microcom MNP error correcting SX/1200 modem 2567 | 2568 | 2569 | 2570 | Chapter 16 Rev Oct-14-88 Typeset 10-14-88 39 2571 | 2572 | 2573 | 2574 | 2575 | 2576 | 2577 | 2578 | Chapter 16 ZMODEM Protocol 40 2579 | 2580 | 2581 | 2582 | PTL Portland Oregon network node 2583 | SK Sliding Window Kermit (SuperKermit) w=15 2584 | X XMODEM 2585 | XN XMODEM protocol implemented in network modes 2586 | X/ovth XMODEM, Omen Technology OverThruster(TM) 2587 | ZM ZMODEM 2588 | 2589 | 2590 | 2591 | 2592 | 2593 | 2594 | 2595 | 2596 | 2597 | 2598 | 2599 | 2600 | 2601 | 2602 | 2603 | 2604 | 2605 | 2606 | 2607 | 2608 | 2609 | 2610 | 2611 | 2612 | 2613 | 2614 | 2615 | 2616 | 2617 | 2618 | 2619 | 2620 | 2621 | 2622 | 2623 | 2624 | 2625 | 2626 | 2627 | 2628 | 2629 | 2630 | 2631 | 2632 | 2633 | 2634 | 2635 | 2636 | Chapter 16 Rev Oct-14-88 Typeset 10-14-88 40 2637 | 2638 | 2639 | 2640 | 2641 | 2642 | 2643 | 2644 | Chapter 16 ZMODEM Protocol 41 2645 | 2646 | 2647 | 2648 | TABLE 5. Protocol Checklist 2649 | Etc: Relay, BLAST, DART 2650 | 2651 | _________________________________________________________________________ 2652 | |Item XMODEM YMDM-k YMDM-g ZMODEM SK Etc.| 2653 | _________________________________________________________________________ 2654 | |IN SERVICE | 1977 | 1982 | 1985 | 1986 | 1985 | ? | 2655 | |VENDORS | ?? | ?? | >20 | >20 | ?? | 1 | 2656 | _________________________________________________________________________ 2657 | |HOST AVAILABILITY | | | | | | | 2658 | |Compuserve | YES | - | - | YES | - | - | 2659 | |BIX | YES | - | - | YES | YES | - | 2660 | |Portal | | | YES | - | - | SOON| 2661 | |The Source | YES | - | - | - | YES | - | 2662 | |_______________________|________|________|_______|_______|_______|_____| 2663 | |USER FEATURES | | | | | | | 2664 | |User Friendly | - | - | - | YES | (10) | - | 2665 | |Commands/batch | 2*N | 2 | 2 | 1 | 1(1) | | 2666 | |Commands/file | 2 | 0 | 0 | 0 | 0 | | 2667 | |Command Download | - | - | - | YES | YES(6)| - | 2668 | |Menu Compatible | - | - | - | YES | - | - | 2669 | |Crash Recovery | - | - | - | YES | - | ?? | 2670 | |File Management | - | - | - | YES | - | some| 2671 | |Security Check | - | - | - | YES | - | - | 2672 | |_______________________|________|________|_______|_______|_______|_____| 2673 | |COMPATIBILITY | | | | | | | 2674 | |Dynamic Files | YES | - | - | YES | YES | ? | 2675 | |Packet SW NETS | - | - | - | YES | YES | ? | 2676 | |7 bit PS NETS | - | - | - | (3) | YES | ? | 2677 | |Old Mainframes | - | - | - | (3) | YES | ? | 2678 | |_______________________|________|________|_______|_______|_______|_____| 2679 | |ATTRIBUTES | | | | | | | 2680 | |Reliability(5) | fair | fair(5)| none | BEST | good | ? | 2681 | |Streaming | - | - | YES | YES | YES | | 2682 | |Overhead(2) | 7% | 1% | 1% | 4%(8) | 30% | | 2683 | |Faithful Xfers | - | YES(7) | YES(7)| YES | YES | ? | 2684 | |Preserve Date | - | YES | YES | YES | - | ? | 2685 | |_______________________|________|________|_______|_______|_______|_____| 2686 | |COMPLEXITY | | | | | | | 2687 | |No-Wait Sample | - | - | - | opt | REQD | REQD| 2688 | |Ring Buffers | - | - | - | opt | REQD | REQD| 2689 | |Complexity | LOW(5)| LOW(5) | LOW | MED | HIGH | ? | 2690 | |_______________________|________|________|_______|_______|_______|_____| 2691 | |EXTENSIONS | | | | | | | 2692 | |Server Operation | - | - | - | YES(4)| YES | ? | 2693 | |Multiple Threads | - | - | - | future| - | - | 2694 | _________________________________________________________________________ 2695 | 2696 | NOTES: 2697 | (1) Server mode or Omen Technology Kermit AutoDownload 2698 | (2) Character count, binary file, transparent channel 2699 | 2700 | 2701 | 2702 | Chapter 16 Rev Oct-14-88 Typeset 10-14-88 41 2703 | 2704 | 2705 | 2706 | 2707 | 2708 | 2709 | 2710 | Chapter 16 ZMODEM Protocol 42 2711 | 2712 | 2713 | 2714 | (3) Future enhancement provided for 2715 | (4) AutoDownload operation 2716 | (5) Omen Technology's Cybernetic Data Recovery(TM) improves XMODEM 2717 | and YMODEM reliability with complex proprietary logic. 2718 | (6) Server commands only 2719 | (7) Only with True YMODEM(TM) 2720 | (8) More then 3% from protected network control characters 2721 | (9) With Segmented Streaming 2722 | (10) With Pro-YAM extensions 2723 | 2724 | 2725 | 2726 | 2727 | 2728 | 2729 | 2730 | 2731 | 2732 | 2733 | 2734 | 2735 | 2736 | 2737 | 2738 | 2739 | 2740 | 2741 | 2742 | 2743 | 2744 | 2745 | 2746 | 2747 | 2748 | 2749 | 2750 | 2751 | 2752 | 2753 | 2754 | 2755 | 2756 | 2757 | 2758 | 2759 | 2760 | 2761 | 2762 | 2763 | 2764 | 2765 | 2766 | 2767 | 2768 | Chapter 16 Rev Oct-14-88 Typeset 10-14-88 42 2769 | 2770 | 2771 | 2772 | 2773 | 2774 | 2775 | 2776 | Chapter 16 ZMODEM Protocol 43 2777 | 2778 | 2779 | 2780 | 17. FUTURE EXTENSIONS 2781 | 2782 | Future extensions include: 2783 | 2784 | + Compatibility with 7 bit networks 2785 | 2786 | + Server/Link Level operation: An END-TO-END error corrected 2787 | program to program session is required for financial and other 2788 | sensitive applications. 2789 | 2790 | + Multiple independent threads 2791 | 2792 | + Bidirectional transfers (STEREO ZMODEM) 2793 | 2794 | + Encryption 2795 | 2796 | + Compression 2797 | 2798 | + File Comparison 2799 | 2800 | + Selective transfer within a file (e.g., modified segments of a 2801 | database file) 2802 | 2803 | + Selective Retransmission for error correction 2804 | 2805 | 2806 | 18. REVISIONS 2807 | 2808 | 10-14-88 Pascal source code now available in Phil Burn's PibTerm 2809 | v4.2. 6-24-88 An exception to the previously unconditional ZCBIN 2810 | override: a ZCRESUM specified by the receiver need not be overridden 2811 | by the sender's ZCBIN. 2812 | 2813 | 11-18-87 Editorial improvements 2814 | 2815 | 10-27-87 Optional fields added for number of files remaining to be 2816 | sent and total number of bytes remaining to be sent. 2817 | 2818 | 07-31-1987 The receiver should ignore a ZEOF with an offset that 2819 | does not match the current file length. The previous action of 2820 | responding with ZRPOS caused transfers to fail if a CRC error 2821 | occurred immediately before end of file, because two retransmission 2822 | requests were being sent for each error. This has been observed 2823 | under exceptional conditions, such as data transmission at speeds 2824 | greater than the receiving computer's interrupt response capabilitiy 2825 | or gross misapplication of flow control. 2826 | 2827 | Discussion of the Tx backchannel garbage count and ZCRCW after error 2828 | ZRPOS was added. Many revisions for clarity. 2829 | 2830 | 07-09-87 Corrected XMODEM's development date, incorrectly stated as 2831 | 2832 | 2833 | 2834 | Chapter 18 Rev Oct-14-88 Typeset 10-14-88 43 2835 | 2836 | 2837 | 2838 | 2839 | 2840 | 2841 | 2842 | Chapter 18 ZMODEM Protocol 44 2843 | 2844 | 2845 | 2846 | 1979 instead of the actual August 1977. More performance data was 2847 | added. 2848 | 2849 | 05-30-87 Added ZMNEW and ZMSKNOLOC 2850 | 2851 | 05-14-87 Window management, ZACK zshhdr XON removed, control 2852 | character escaping, ZMSPARS changed to ZXPARS, editorial changes. 2853 | 2854 | 04-13-87 The ZMODEM file transfer protocol's public domain status 2855 | is emphasized. 2856 | 2857 | 04-04-87: minor editorial changes, added conditionals for overview 2858 | version. 2859 | 2860 | 03-15-87: 32 bit CRC added. 2861 | 2862 | 12-19-86: 0 Length ZCRCW data subpacket sent in response to ZPAD or 2863 | ZDELE detected on reverse channel has been changed to ZCRCE. The 2864 | reverse channel is now checked for activity before sending each 2865 | ZDATA header. 2866 | 2867 | 11-08-86: Minor changes for clarity. 2868 | 2869 | 10-2-86: ZCNL definition expanded. 2870 | 2871 | 9-11-86: ZMPROT file management option added. 2872 | 2873 | 8-20-86: More performance data included. 2874 | 2875 | 8-4-86: ASCII DLE (Ctrl-P, 020) now escaped; compatible with 2876 | previous versions. More document revisions for clarity. 2877 | 2878 | 7-15-86: This document was extensively edited to improve clarity and 2879 | correct small errors. The definition of the ZMNEW management option 2880 | was modified, and the ZMDIFF management option was added. The 2881 | cancel sequence was changed from two to five CAN characters after 2882 | spurious two character cancel sequences were detected. 2883 | 2884 | 2885 | 19. MORE INFORMATION 2886 | 2887 | Please contact Omen Technology for troff source files and typeset 2888 | copies of this document. 2889 | 2890 | 2891 | 19.1 TeleGodzilla Bulletin Board 2892 | 2893 | More information may be obtained by calling the TeleGodzilla 2894 | bulletin board at 503-621-3746. TeleGodzilla supports 19200 2895 | (Telebit PEP), 2400 and 1200 bps callers with automatic speed 2896 | recognition. 2897 | 2898 | 2899 | 2900 | Chapter 19 Rev Oct-14-88 Typeset 10-14-88 44 2901 | 2902 | 2903 | 2904 | 2905 | 2906 | 2907 | 2908 | Chapter 19 ZMODEM Protocol 45 2909 | 2910 | 2911 | 2912 | Relevant files include YZMODEM.ZOO, YAMDEMO.ZOO, YAMHELP.ZOO, 2913 | ZCOMMEXE.ARC, ZCOMMDOC.ARC, ZCOMMHLP.ARC. 2914 | 2915 | Useful commands for TeleGodzilla include "menu", "dir", "sx file 2916 | (XMODEM)", "kermit sb file ...", and "sz file ...". 2917 | 2918 | 19.2 Unix UUCP Access 2919 | 2920 | UUCP sites can obtain the current version of this file with 2921 | uucp omen!/u/caf/public/zmodem.doc /tmp 2922 | A continually updated list of available files is stored in 2923 | /usr/spool/uucppublic/FILES. 2924 | uucp omen!~uucp/FILES /usr/spool/uucppublic 2925 | 2926 | The following L.sys line allows UUCP to call site "omen" via Omen's 2927 | bulletin board system "TeleGodzilla". TeleGodzilla is an instance 2928 | of Omen Technology's Professional-YAM in host operation, acting as a 2929 | bulletin board and front ending a Xenix system. 2930 | 2931 | In response to TeleGodzilla's "Name Please:" (e:--e:), uucico gives 2932 | the Pro-YAM "link" command as a user name. Telegodzilla then asks 2933 | for a link password (d:). The password (Giznoid) controls access to 2934 | the Xenix system connected to the IBM PC's other serial port. 2935 | Communications between Pro-YAM and Xenix use 9600 bps; YAM converts 2936 | this to the caller's speed. 2937 | 2938 | Finally, the calling uucico sees the Xenix "Login:" message (n:-- 2939 | n:), and logs in as "uucp". No password is used for the uucp 2940 | account. 2941 | 2942 | omen Any ACU 2400 1-503-621-3746 e:--e: link d: Giznoid n:--n: uucp 2943 | 2944 | 2945 | 2946 | 20. ZMODEM PROGRAMS 2947 | 2948 | A copy of this document, a demonstration version of 2949 | Professional-YAM, a flash-up tree structured help file and 2950 | processor, are available in YZMODEM.ZOO on TeleGodzilla and other 2951 | bulletin boards. This file must be unpacked with LOOZ.EXE, also 2952 | available on TeleGodzilla. YZMODEM.ZOO may be distributed provided 2953 | none of the files are deleted or modified without the written 2954 | consent of Omen Technology. 2955 | 2956 | TeleGodzilla and other bulletin boards also feature ZCOMM, a 2957 | shareware communications program. ZCOMM includes Omen Technology's 2958 | TurboLearn(TM) Script Writer, ZMODEM, Omen's highly acclaimed XMODEM 2959 | and YMODEM protocol support, Sliding Windows Kermit, several 2960 | traditional protocols, a powerful script language, and the most 2961 | accurate VT100/102 emulation available in a usr supported program. 2962 | The ZCOMM files include: 2963 | 2964 | 2965 | 2966 | Chapter 20 Rev Oct-14-88 Typeset 10-14-88 45 2967 | 2968 | 2969 | 2970 | 2971 | 2972 | 2973 | 2974 | Chapter 20 ZMODEM Protocol 46 2975 | 2976 | 2977 | 2978 | + ZCOMMEXE.ARC Executable files and beginner's telephone directory 2979 | 2980 | + ZCOMMDOC.ARC "Universal Line Printer Edition" Manual 2981 | 2982 | + ZCOMMHLP.ARC Tree structured Flash-UP help processor and 2983 | database 2984 | 2985 | C source code and manual pages for the Unix/Xenix rz and sz programs 2986 | are available on TeleGodzilla in RZSZ.ZOO. This ZOO archive may be 2987 | unpacked with LOOZ.EXE, also available on TeleGodzilla. Most Unix 2988 | like systems are supported, including V7, Sys III, 4.x BSD, SYS V, 2989 | Idris, Coherent, and Regulus. 2990 | 2991 | RZSZ.ZOO includes a ZCOMM/Pro-YAM/PowerCom script ZUPL.T to upload 2992 | the small (178 lines) YMODEM bootstrap program MINIRB.C without a 2993 | file transfer protocol. MINIRB uses the Unix stty(1) program to set 2994 | the required raw tty modes, and compiles without special flags on 2995 | virtually all Unix and Xenix systems. ZUPL.T directs the Unix 2996 | system to compile MINIRB, then uses it as a bootstrap to upload the 2997 | rz/sz source and manual files. 2998 | 2999 | Pascal source code for ZMODEM support is available in PibTerm v4.2 3000 | written by Phil Burns. 3001 | 3002 | The PC-DOS EXEC-PC, QuickBBS, Opus and Nochange bulletin boards 3003 | support ZMODEM. Integrated ZMODEM support for the Collie bulletin 3004 | board program is planned. Most of the PC-DOS bulletin board 3005 | programs that lack integrated ZMODEM support ZMODEM with external 3006 | modules (DSZ, etc.). 3007 | 3008 | The BinkleyTerm, Dutchie and D'Bridge email systems support ZMODEM 3009 | as their primary protocol. 3010 | 3011 | The IN-SYNCH PC-DOS Teleconferencing system uses ZMODEM. 3012 | 3013 | The LAN modem sharing program Line Plus has announced ZMODEM 3014 | support. 3015 | 3016 | Many programs have added direct ZMODEM support, including Crosstalk 3017 | Mark IV, and Telix 3. 3018 | 3019 | Most other PC-DOS communications programs support external ZMODEM 3020 | via Omen Technology's DSZ, including PibTerm, Qmodem SST and BOYAN. 3021 | 3022 | The ZMDM communications program by Jwahar Bammi runs on Atari ST 3023 | machines. 3024 | 3025 | The Online! and A-Talk Gold programs for the Amiga support ZMODEM. 3026 | 3027 | The Byte Information eXchange supports ZMODEM. The Compuserve 3028 | Information Service has ported the Unix rz/sz ZMODEM programs to 3029 | 3030 | 3031 | 3032 | Chapter 20 Rev Oct-14-88 Typeset 10-14-88 46 3033 | 3034 | 3035 | 3036 | 3037 | 3038 | 3039 | 3040 | Chapter 20 ZMODEM Protocol 47 3041 | 3042 | 3043 | 3044 | DECSYSTEM 20 assembler, and has announced future support for ZMODEM. 3045 | 3046 | 20.1 Adding ZMODEM to DOS Programs 3047 | 3048 | DSZ is a small shareware program that supports XMODEM, YMODEM, and 3049 | ZMODEM file transfers. DSZ is designed to be called from a bulletin 3050 | board program or another communications program. It may be called 3051 | as 3052 | dsz port 2 sz file1 file2 3053 | to send files, or as 3054 | dsz port 2 rz 3055 | to receive zero or more file(s), or as 3056 | dsz port 2 rz filea fileb 3057 | to receive two files, the first to filea and the second (if sent) to 3058 | fileb. This form of dsz may be used to control the pathname of 3059 | incoming file(s). In this example, if the sending program attempted 3060 | to send a third file, the transfer would be terminated. 3061 | 3062 | Dsz uses DOS stdout for messages (no direct CRT access), acquires 3063 | the COMM port vectors with standard DOS calls, and restores the COMM 3064 | port's interrupt vector and registers upon exit. 3065 | 3066 | Further information on dsz may be found in dsz.doc and the ZCOMM or 3067 | Pro-YAM user manuals. 3068 | 3069 | 3070 | 21. YMODEM PROGRAMS 3071 | 3072 | The Unix rz/sz programs support YMODEM as well as ZMODEM. Most Unix 3073 | like systems are supported, including V7, Sys III, 4.2 BSD, SYS V, 3074 | Idris, Coherent, and Regulus. 3075 | 3076 | A version for VAX-VMS is available in VRBSB.SHQ, in the same 3077 | directory. 3078 | 3079 | Irv Hoff has added 1k packets and YMODEM transfers to the KMD and 3080 | IMP series programs, which replace the XMODEM and MODEM7/MDM7xx 3081 | series respectively. Overlays are available for a wide variety of 3082 | CP/M systems. 3083 | 3084 | Many other programs, including MEX-PLUS and Crosstalk Mark IV also 3085 | support some of YMODEM's features. 3086 | 3087 | 3088 | 3089 | 3090 | 3091 | 3092 | 3093 | 3094 | 3095 | 3096 | 3097 | 3098 | Chapter 21 Rev Oct-14-88 Typeset 10-14-88 47 3099 | 3100 | 3101 | 3102 | 3103 | 3104 | 3105 | 3106 | Chapter 21 ZMODEM Protocol 48 3107 | 3108 | 3109 | 3110 | Questions about YMODEM, the Professional-YAM communications program, 3111 | and requests for evaluation copies may be directed to: 3112 | 3113 | Chuck Forsberg 3114 | Omen Technology Inc 3115 | 17505-V Sauvie Island Road 3116 | Portland Oregon 97231 3117 | VOICE: 503-621-3406 :VOICE 3118 | Modem (TeleGodzilla): 503-621-3746 3119 | Usenet: ...!tektronix!reed!omen!caf 3120 | Compuserve: 70007,2304 3121 | Source: TCE022 3122 | 3123 | 3124 | 22. ACKNOWLEDGMENTS 3125 | 3126 | The High Reliability Software(TM), TurboLearn Script Writer(TM), 3127 | Cybernetic Data Recovery(TM), AutoDownload(TM), Intelligent Crash 3128 | Recovery(TM), Error Containment(TM), Full Time Capture(TM), True 3129 | YMODEM(TM), OverThruster(TM), Password Guardian(TM), 3130 | CryptoScript(TM), and TurboDial(TM) are Omen Technology trademarks. 3131 | 3132 | ZMODEM was developed for the public domain under a Telenet contract. 3133 | The ZMODEM protocol descriptions and the Unix rz/sz program source 3134 | code are public domain. No licensing, trademark, or copyright 3135 | restrictions apply to the use of the protocol, the Unix rz/sz source 3136 | code and the ZMODEM name. 3137 | 3138 | Encouragement and suggestions by Thomas Buck, Ward Christensen, Earl 3139 | Hall, Irv Hoff, Stuart Mathison, and John Wales, are gratefully 3140 | acknowledged. 32 bit CRC code courtesy Gary S. Brown. 3141 | 3142 | 3143 | 23. RELATED FILES 3144 | 3145 | The following files may be useful while studying this document: 3146 | 3147 | YMODEM.DOC Describes the XMODEM, XMODEM-1k, and YMODEM batch file 3148 | transfer protocols. This file is available on TeleGodzilla 3149 | as YMODEM.DQC. 3150 | 3151 | zmodem.h Definitions for ZMODEM manifest constants 3152 | 3153 | rz.c, sz.c, rbsb.c Unix source code for operating ZMODEM programs. 3154 | 3155 | rz.1, sz.1 Manual pages for rz and sz (Troff sources). 3156 | 3157 | zm.c Operating system independent low level ZMODEM subroutines. 3158 | 3159 | minirb.c A YMODEM bootstrap program, 178 lines. 3160 | 3161 | 3162 | 3163 | 3164 | Chapter 23 Rev Oct-14-88 Typeset 10-14-88 48 3165 | 3166 | 3167 | 3168 | 3169 | 3170 | 3171 | 3172 | Chapter 23 ZMODEM Protocol 49 3173 | 3174 | 3175 | 3176 | RZSZ.ZOO,rzsz.arc Contain the C source code and manual pages listed 3177 | above, plus a ZCOMM script to upload minirb.c to a Unix or 3178 | Xenix system, compile it, and use the program to upload the 3179 | ZMODEM source files with error checking. 3180 | 3181 | DSZ.ZOO,dsz.arc Contains DSZ.COM, a shareware X/Y/ZMODEM subprogram, 3182 | DESQview "pif" files for background operation in minimum 3183 | memory, and DSZ.DOC. 3184 | 3185 | ZCOMM*.ARC Archive files for ZCOMM, a powerful shareware 3186 | communications program. 3187 | 3188 | 3189 | 3190 | 3191 | 3192 | 3193 | 3194 | 3195 | 3196 | 3197 | 3198 | 3199 | 3200 | 3201 | 3202 | 3203 | 3204 | 3205 | 3206 | 3207 | 3208 | 3209 | 3210 | 3211 | 3212 | 3213 | 3214 | 3215 | 3216 | 3217 | 3218 | 3219 | 3220 | 3221 | 3222 | 3223 | 3224 | 3225 | 3226 | 3227 | 3228 | 3229 | 3230 | Chapter 23 Rev Oct-14-88 Typeset 10-14-88 49 3231 | 3232 | 3233 | 3234 | 3235 | 3236 | 3237 | 3238 | 3239 | 3240 | 3241 | 3242 | CONTENTS 3243 | 3244 | 3245 | 1. INTENDED AUDIENCE................................................ 2 3246 | 3247 | 2. WHY DEVELOP ZMODEM?.............................................. 2 3248 | 3249 | 3. ZMODEM Protocol Design Criteria.................................. 4 3250 | 3.1 Ease of Use............................................... 4 3251 | 3.2 Throughput................................................ 5 3252 | 3.3 Integrity and Robustness.................................. 6 3253 | 3.4 Ease of Implementation.................................... 6 3254 | 3255 | 4. EVOLUTION OF ZMODEM.............................................. 7 3256 | 3257 | 5. ROSETTA STONE.................................................... 10 3258 | 3259 | 6. ZMODEM REQUIREMENTS.............................................. 10 3260 | 6.1 File Contents............................................. 10 3261 | 3262 | 7. ZMODEM BASICS.................................................... 12 3263 | 7.1 Packetization............................................. 12 3264 | 7.2 Link Escape Encoding...................................... 12 3265 | 7.3 Header.................................................... 13 3266 | 7.4 Binary Data Subpackets.................................... 16 3267 | 7.5 ASCII Encoded Data Subpacket.............................. 16 3268 | 3269 | 8. PROTOCOL TRANSACTION OVERVIEW.................................... 16 3270 | 8.1 Session Startup........................................... 16 3271 | 8.2 File Transmission......................................... 18 3272 | 8.3 Session Cleanup........................................... 20 3273 | 8.4 Session Abort Sequence.................................... 20 3274 | 3275 | 9. STREAMING TECHNIQUES / ERROR RECOVERY............................ 21 3276 | 9.1 Full Streaming with Sampling.............................. 21 3277 | 9.2 Full Streaming with Reverse Interrupt..................... 23 3278 | 9.3 Full Streaming with Sliding Window........................ 23 3279 | 9.4 Full Streaming over Error Free Channels................... 24 3280 | 9.5 Segmented Streaming....................................... 24 3281 | 3282 | 10. ATTENTION SEQUENCE............................................... 24 3283 | 3284 | 11. FRAME TYPES...................................................... 25 3285 | 11.1 ZRQINIT................................................... 25 3286 | 11.2 ZRINIT.................................................... 25 3287 | 11.3 ZSINIT.................................................... 25 3288 | 11.4 ZACK...................................................... 26 3289 | 11.5 ZFILE..................................................... 26 3290 | 11.6 ZSKIP..................................................... 28 3291 | 11.7 ZNAK...................................................... 28 3292 | 11.8 ZABORT.................................................... 28 3293 | 3294 | 3295 | 3296 | - i - 3297 | 3298 | 3299 | 3300 | 3301 | 3302 | 3303 | 3304 | 3305 | 3306 | 3307 | 3308 | 11.9 ZFIN...................................................... 28 3309 | 11.10 ZRPOS..................................................... 28 3310 | 11.11 ZDATA..................................................... 29 3311 | 11.12 ZEOF...................................................... 29 3312 | 11.13 ZFERR..................................................... 29 3313 | 11.14 ZCRC...................................................... 29 3314 | 11.15 ZCHALLENGE................................................ 29 3315 | 11.16 ZCOMPL.................................................... 29 3316 | 11.17 ZCAN...................................................... 29 3317 | 11.18 ZFREECNT.................................................. 29 3318 | 11.19 ZCOMMAND.................................................. 29 3319 | 3320 | 12. SESSION TRANSACTION EXAMPLES..................................... 30 3321 | 12.1 A simple file transfer.................................... 30 3322 | 12.2 Challenge and Command Download............................ 31 3323 | 3324 | 13. ZFILE FRAME FILE INFORMATION..................................... 31 3325 | 3326 | 14. PERFORMANCE RESULTS.............................................. 33 3327 | 14.1 Compatibility............................................. 33 3328 | 14.2 Throughput................................................ 34 3329 | 14.3 Error Recovery............................................ 34 3330 | 3331 | 15. PACKET SWITCHED NETWORK CONSIDERATIONS........................... 35 3332 | 3333 | 16. PERFORMANCE COMPARISON TABLES.................................... 36 3334 | 3335 | 17. FUTURE EXTENSIONS................................................ 43 3336 | 3337 | 18. REVISIONS........................................................ 43 3338 | 3339 | 19. MORE INFORMATION................................................. 44 3340 | 19.1 TeleGodzilla Bulletin Board............................... 44 3341 | 19.2 Unix UUCP Access.......................................... 45 3342 | 3343 | 20. ZMODEM PROGRAMS.................................................. 45 3344 | 20.1 Adding ZMODEM to DOS Programs............................. 47 3345 | 3346 | 21. YMODEM PROGRAMS.................................................. 47 3347 | 3348 | 22. ACKNOWLEDGMENTS.................................................. 48 3349 | 3350 | 23. RELATED FILES.................................................... 48 3351 | 3352 | 3353 | LIST OF FIGURES 3354 | 3355 | 3356 | Figure 1. Order of Bytes in Header................................... 14 3357 | 3358 | Figure 2. 16 Bit CRC Binary Header................................... 14 3359 | 3360 | 3361 | 3362 | - ii - 3363 | 3364 | 3365 | 3366 | 3367 | 3368 | 3369 | 3370 | 3371 | 3372 | 3373 | 3374 | Figure 3. 32 Bit CRC Binary Header................................... 14 3375 | 3376 | Figure 4. HEX Header................................................. 15 3377 | 3378 | Figure 5. Transmission Time Comparison............................... 37 3379 | 3380 | 3381 | LIST OF TABLES 3382 | 3383 | 3384 | TABLE 1. Network and Flow Control Compatibility...................... 36 3385 | 3386 | TABLE 2. Protocol Overhead Information............................... 37 3387 | 3388 | TABLE 3. Local Timesharing Computer Download Performance............. 38 3389 | 3390 | TABLE 4. File Transfer Speeds........................................ 39 3391 | 3392 | TABLE 5. Protocol Checklist.......................................... 41 3393 | 3394 | 3395 | 3396 | 3397 | 3398 | 3399 | 3400 | 3401 | 3402 | 3403 | 3404 | 3405 | 3406 | 3407 | 3408 | 3409 | 3410 | 3411 | 3412 | 3413 | 3414 | 3415 | 3416 | 3417 | 3418 | 3419 | 3420 | 3421 | 3422 | 3423 | 3424 | 3425 | 3426 | 3427 | 3428 | - iii - 3429 | 3430 | 3431 | 3432 | 3433 | 3434 | 3435 | 3436 | 3437 | 3438 | The ZMODEM Inter Application File Transfer Protocol 3439 | 3440 | Chuck Forsberg 3441 | 3442 | Omen Technology Inc 3443 | 3444 | 3445 | ABSTRACT 3446 | 3447 | 3448 | 3449 | The ZMODEM file transfer protocol provides reliable file and command 3450 | transfers with complete END-TO-END data integrity between application 3451 | programs. ZMODEM's 32 bit CRC protects against errors that continue to 3452 | sneak into even the most advanced networks. 3453 | 3454 | Unlike traditional and many recently introduced protocols, ZMODEM 3455 | safeguards all data and supervisory information with effective error 3456 | detection. 3457 | 3458 | ZMODEM rapidly transfers files, particularly with buffered (error 3459 | correcting) modems, timesharing systems, satellite relays, and wide area 3460 | packet switched networks. 3461 | 3462 | User Friendliness is an important ZMODEM feature. ZMODEM AutoDownload 3463 | (Automatic file Download initiated without user intervention) greatly 3464 | simplifies file transfers compared to the traditional protocols. 3465 | 3466 | ZMODEM provides advanced file management features including Crash 3467 | Recovery, flexible control of selective file transfers, and security 3468 | verified command downloading. 3469 | 3470 | ZMODEM protocol features allow implementation on a wide variety of systems 3471 | operating in a wide variety of environments. A choice of buffering and 3472 | windowing modes allows ZMODEM to operate on systems that cannot support 3473 | other streaming protocols. Finely tuned control character escaping allows 3474 | operation with real world networks without Kermit's high overhead. 3475 | 3476 | ZMODEM is the only high performance high reliability public protocol that 3477 | does not require large buffer allocations for normal file transfers. 3478 | 3479 | Although ZMODEM software is more complex than unreliable XMODEM routines, 3480 | a comphrensive protocol description and actual C source code to production 3481 | programs have allowed dozens of developers to upgrade their applications 3482 | with efficient, reliable ZMODEM file transfers with a minimum of effort. 3483 | 3484 | ZMODEM was developed for the public domain under a Telenet contract. The 3485 | ZMODEM protocol descriptions and the Unix rz/sz program source code are 3486 | public domain. No licensing, trademark, or copyright restrictions apply 3487 | to the use of the protocol, the Unix rz/sz source code and the ZMODEM 3488 | name. 3489 | -------------------------------------------------------------------------------- /fymodem.c: -------------------------------------------------------------------------------- 1 | /** 2 | * Free YModem implementation. 3 | * 4 | * Fredrik Hederstierna 2014 5 | * 6 | * This file is in the public domain. 7 | * You can do whatever you want with it. 8 | * 9 | * This program is distributed in the hope that it will be useful, 10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 12 | */ 13 | 14 | /** 15 | * Some future improvements and ideas 16 | * 17 | * Add rx/tx callbacks if eg storing file to external storage, 18 | * and full buffer cannot be in memory at the same time. 19 | * 20 | * Add support for Ymodem-G standard as described in docs for streaming. 21 | * 22 | * Add suppport for async operation mode if calling system cannot handle 23 | * that calls are synchroneus and blocking. 24 | * 25 | * Add unittest 26 | * 27 | * Add support for ZModem (which may imply total rewrite). 28 | */ 29 | 30 | #include 31 | 32 | /* filesize 999999999999999 should be enough... */ 33 | #define YM_FILE_SIZE_LENGTH (16) 34 | 35 | /* packet constants */ 36 | #define YM_PACKET_SEQNO_INDEX (1) 37 | #define YM_PACKET_SEQNO_COMP_INDEX (2) 38 | #define YM_PACKET_HEADER (3) /* start, block, block-complement */ 39 | #define YM_PACKET_TRAILER (2) /* CRC bytes */ 40 | #define YM_PACKET_OVERHEAD (YM_PACKET_HEADER + YM_PACKET_TRAILER) 41 | #define YM_PACKET_SIZE (128) 42 | #define YM_PACKET_1K_SIZE (1024) 43 | #define YM_PACKET_RX_TIMEOUT_MS (1000) 44 | #define YM_PACKET_ERROR_MAX_NBR (5) 45 | 46 | /* contants defined by YModem protocol */ 47 | #define YM_SOH (0x01) /* start of 128-byte data packet */ 48 | #define YM_STX (0x02) /* start of 1024-byte data packet */ 49 | #define YM_EOT (0x04) /* End Of Transmission */ 50 | #define YM_ACK (0x06) /* ACKnowledge, receive OK */ 51 | #define YM_NAK (0x15) /* Negative ACKnowledge, receiver ERROR, retry */ 52 | #define YM_CAN (0x18) /* two CAN in succession will abort transfer */ 53 | #define YM_CRC (0x43) /* 'C' == 0x43, request 16-bit CRC, use in place of first NAK for CRC mode */ 54 | #define YM_ABT1 (0x41) /* 'A' == 0x41, assume try abort by user typing */ 55 | #define YM_ABT2 (0x61) /* 'a' == 0x61, assume try abort by user typing */ 56 | 57 | /* ------------------------------------------------ */ 58 | 59 | /* user callbacks, implement these for your target */ 60 | /* user function __ym_getchar() should return -1 in case of timeout */ 61 | #define __ym_getchar(timeout_ms) printf("%d", (int)timeout_ms) 62 | #define __ym_putchar(c) do { (void)(c); /* printf("%d",(int)c); */ } while(0) 63 | #define __ym_sleep_ms(delay_ms) do { (void)(delay_ms); } while(0) 64 | #define __ym_flush() do { ; } while(0) 65 | /* example functions for POSIX/Unix */ 66 | #define __ym_getchar_posix(timeout_ms) read(timeout_ms/1000) 67 | #define __ym_putchar_posix(c) (void)write(c) 68 | #define __ym_sleep_ms_posix(delay_ms) sleep(delay_ms/1000) 69 | #define __ym_flush_posix() (void)flush() 70 | 71 | /* error logging function */ 72 | #define YM_ERR(fmt, ...) do { printf(fmt, __VA_ARGS__); } while(0) 73 | 74 | /* ------------------------------------------------ */ 75 | /* calculate crc16-ccitt very fast 76 | Idea from: http://www.ccsinfo.com/forum/viewtopic.php?t=24977 77 | */ 78 | static uint16_t ym_crc16(const uint8_t *buf, uint16_t len) 79 | { 80 | uint16_t x; 81 | uint16_t crc = 0; 82 | while (len--) { 83 | x = (crc >> 8) ^ *buf++; 84 | x ^= x >> 4; 85 | crc = (crc << 8) ^ (x << 12) ^ (x << 5) ^ x; 86 | } 87 | return crc; 88 | } 89 | 90 | /* ------------------------------------------------- */ 91 | /* write 32bit value as asc to buffer, return chars written. */ 92 | static uint32_t ym_writeU32(uint32_t val, uint8_t *buf) 93 | { 94 | uint32_t ci = 0; 95 | if (val == 0) { 96 | /* If already zero then just return zero */ 97 | buf[ci++] = '0'; 98 | } 99 | else { 100 | /* Maximum number of decimal digits in uint32_t is 10, add one for z-term */ 101 | uint8_t s[11]; 102 | int32_t i = sizeof(s) - 1; 103 | /* z-terminate string */ 104 | s[i] = 0; 105 | while ((val > 0) && (i > 0)) { 106 | /* write decimal char */ 107 | s[--i] = (val % 10) + '0'; 108 | val /= 10; 109 | } 110 | uint8_t *sp = &s[i]; 111 | /* copy results to out buffer */ 112 | while (*sp) { 113 | buf[ci++] = *sp++; 114 | } 115 | } 116 | /* z-term */ 117 | buf[ci] = 0; 118 | /* return chars written */ 119 | return ci; 120 | } 121 | 122 | /* ------------------------------------------------- */ 123 | /* read 32bit asc value from buffer */ 124 | static void ym_readU32(const uint8_t* buf, uint32_t *val) 125 | { 126 | const uint8_t *s = buf; 127 | uint32_t res = 0; 128 | uint8_t c; 129 | /* trim and strip leading spaces if any */ 130 | do { 131 | c = *s++; 132 | } while (c == ' '); 133 | while ((c >= '0') && (c <= '9')) { 134 | c -= '0'; 135 | res *= 10; 136 | res += c; 137 | /* next char */ 138 | c = *s++; 139 | } 140 | *val = res; 141 | } 142 | 143 | /* -------------------------------------------------- */ 144 | /** 145 | * Receive a packet from sender 146 | * @param rxlen 147 | * 0: end of transmission 148 | * -1: abort by sender 149 | * >0: packet length 150 | * @return 0: normally return, success 151 | * -1: timeout or packet error 152 | * 1: abort by user / corrupt packet 153 | */ 154 | static int32_t ym_rx_packet(uint8_t *rxdata, 155 | int32_t *rxlen, 156 | uint32_t packets_rxed, 157 | uint32_t timeout_ms) 158 | { 159 | *rxlen = 0; 160 | 161 | int32_t c = __ym_getchar(timeout_ms); 162 | if (c < 0) { 163 | /* end of stream */ 164 | return -1; 165 | } 166 | 167 | uint32_t rx_packet_size; 168 | 169 | switch (c) { 170 | case YM_SOH: 171 | rx_packet_size = YM_PACKET_SIZE; 172 | break; 173 | case YM_STX: 174 | rx_packet_size = YM_PACKET_1K_SIZE; 175 | break; 176 | case YM_EOT: 177 | /* ok */ 178 | return 0; 179 | case YM_CAN: 180 | c = __ym_getchar(timeout_ms); 181 | if (c == YM_CAN) { 182 | *rxlen = -1; 183 | /* ok */ 184 | return 0; 185 | } 186 | /* fall-through */ 187 | case YM_CRC: 188 | if (packets_rxed == 0) { 189 | /* could be start condition, first byte */ 190 | return 1; 191 | } 192 | /* fall-through */ 193 | case YM_ABT1: 194 | case YM_ABT2: 195 | /* User try abort, 'A' or 'a' received */ 196 | return 1; 197 | default: 198 | /* This case could be the result of corruption on the first octet 199 | of the packet, but it's more likely that it's the user banging 200 | on the terminal trying to abort a transfer. Technically, the 201 | former case deserves a NAK, but for now we'll just treat this 202 | as an abort case. */ 203 | *rxlen = -1; 204 | return 0; 205 | } 206 | 207 | /* store data RXed */ 208 | *rxdata = (uint8_t)c; 209 | 210 | uint32_t i; 211 | for (i = 1; i < (rx_packet_size + YM_PACKET_OVERHEAD); i++) { 212 | c = __ym_getchar(timeout_ms); 213 | if (c < 0) { 214 | /* end of stream */ 215 | return -1; 216 | } 217 | /* store data RXed */ 218 | rxdata[i] = (uint8_t)c; 219 | } 220 | 221 | /* just a sanity check on the sequence number/complement value. 222 | caller should check for in-order arrival. */ 223 | uint8_t seq_nbr = (rxdata[YM_PACKET_SEQNO_INDEX] & 0xff); 224 | uint8_t seq_cmp = ((rxdata[YM_PACKET_SEQNO_COMP_INDEX] ^ 0xff) & 0xff); 225 | if (seq_nbr != seq_cmp) { 226 | /* seq nbr error */ 227 | return 1; 228 | } 229 | 230 | /* check CRC16 match */ 231 | uint16_t crc16_val = ym_crc16((const unsigned char *)(rxdata + YM_PACKET_HEADER), 232 | rx_packet_size + YM_PACKET_TRAILER); 233 | if (crc16_val) { 234 | /* CRC error, non zero */ 235 | return 1; 236 | } 237 | *rxlen = rx_packet_size; 238 | /* success */ 239 | return 0; 240 | } 241 | 242 | /* ------------------------------------------------- */ 243 | /** 244 | * Receive a file using the ymodem protocol 245 | * @param rxdata Pointer to the first byte 246 | * @param rxlen Max in length 247 | * @return The length of the file received, or 0 on error 248 | */ 249 | int32_t fymodem_receive(uint8_t *rxdata, 250 | size_t rxlen, 251 | char filename[FYMODEM_FILE_NAME_MAX_LENGTH]) 252 | { 253 | /* alloc 1k on stack, ok? */ 254 | uint8_t rx_packet_data[YM_PACKET_1K_SIZE + YM_PACKET_OVERHEAD]; 255 | int32_t rx_packet_len; 256 | 257 | uint8_t filesize_asc[YM_FILE_SIZE_LENGTH]; 258 | uint32_t filesize = 0; 259 | 260 | bool first_try = true; 261 | bool session_done = false; 262 | 263 | uint32_t nbr_errors = 0; 264 | 265 | /* z-term string */ 266 | filename[0] = 0; 267 | 268 | /* receive files */ 269 | do { /* ! session done */ 270 | if (first_try) { 271 | /* initiate transfer */ 272 | __ym_putchar(YM_CRC); 273 | } 274 | first_try = false; 275 | 276 | bool crc_nak = true; 277 | bool file_done = false; 278 | uint32_t packets_rxed = 0; 279 | 280 | /* set start position of rxing data */ 281 | uint8_t *rxptr = rxdata; 282 | do { /* ! file_done */ 283 | /* receive packets */ 284 | int32_t res = ym_rx_packet(rx_packet_data, 285 | &rx_packet_len, 286 | packets_rxed, 287 | YM_PACKET_RX_TIMEOUT_MS); 288 | switch (res) { 289 | case 0: { 290 | /* packet received, clear packet error counter */ 291 | nbr_errors = 0; 292 | switch (rx_packet_len) { 293 | case -1: { 294 | /* aborted by sender */ 295 | __ym_putchar(YM_ACK); 296 | return 0; 297 | } 298 | case 0: { 299 | /* EOT - End Of Transmission */ 300 | __ym_putchar(YM_ACK); 301 | /* TODO: Add some sort of sanity check on the number of 302 | packets received and the advertised file length. */ 303 | file_done = true; 304 | /* resend CRC to re-initiate transfer */ 305 | __ym_putchar(YM_CRC); 306 | break; 307 | } 308 | default: { 309 | /* normal packet, check seq nbr */ 310 | uint8_t seq_nbr = rx_packet_data[YM_PACKET_SEQNO_INDEX]; 311 | if (seq_nbr != (packets_rxed & 0xff)) { 312 | /* wrong seq number */ 313 | __ym_putchar(YM_NAK); 314 | } else { 315 | if (packets_rxed == 0) { 316 | /* The spec suggests that the whole data section should 317 | be zeroed, but some senders might not do this. 318 | If we have a NULL filename and the first few digits of 319 | the file length are zero, then call it empty. */ 320 | int32_t i; 321 | for (i = YM_PACKET_HEADER; i < YM_PACKET_HEADER + 4; i++) { 322 | if (rx_packet_data[i] != 0) { 323 | break; 324 | } 325 | } 326 | /* non-zero bytes found in header, filename packet has data */ 327 | if (i < YM_PACKET_HEADER + 4) { 328 | /* read file name */ 329 | uint8_t *file_ptr = (uint8_t*)(rx_packet_data + YM_PACKET_HEADER); 330 | i = 0; 331 | while ((*file_ptr != '\0') && 332 | (i < FYMODEM_FILE_NAME_MAX_LENGTH)) { 333 | filename[i++] = *file_ptr++; 334 | } 335 | filename[i++] = '\0'; 336 | /* skip null term char */ 337 | file_ptr++; 338 | /* read file size */ 339 | i = 0; 340 | while ((*file_ptr != '\0') && 341 | (*file_ptr != ' ') && 342 | (i < YM_FILE_SIZE_LENGTH)) { 343 | filesize_asc[i++] = *file_ptr++; 344 | } 345 | filesize_asc[i++] = '\0'; 346 | /* convert file size */ 347 | ym_readU32(filesize_asc, &filesize); 348 | /* check file size */ 349 | if (filesize > rxlen) { 350 | YM_ERR("YM: RX buffer too small (0x%08x vs 0x%08x)\n", (unsigned int)rxlen, (unsigned int)filesize); 351 | goto rx_err_handler; 352 | } 353 | __ym_putchar(YM_ACK); 354 | __ym_putchar(crc_nak ? YM_CRC : YM_NAK); 355 | crc_nak = false; 356 | } 357 | else { 358 | /* filename packet is empty, end session */ 359 | __ym_putchar(YM_ACK); 360 | file_done = true; 361 | session_done = true; 362 | break; 363 | } 364 | } 365 | else { 366 | /* This shouldn't happen, but we check anyway in case the 367 | sender sent wrong info in its filename packet */ 368 | if (((rxptr + rx_packet_len) - rxdata) > (int32_t)rxlen) { 369 | YM_ERR("YM: RX buffer overflow (exceeded 0x%08x)\n", (unsigned int)rxlen); 370 | goto rx_err_handler; 371 | } 372 | int32_t i; 373 | for (i = 0; i < rx_packet_len; i++) { 374 | rxptr[i] = rx_packet_data[YM_PACKET_HEADER + i]; 375 | } 376 | rxptr += rx_packet_len; 377 | __ym_putchar(YM_ACK); 378 | } 379 | packets_rxed++; 380 | } /* sequence number check ok */ 381 | } /* default */ 382 | } /* inner switch */ 383 | break; 384 | } /* case 0 */ 385 | default: { 386 | /* ym_rx_packet() returned error */ 387 | if (packets_rxed > 0) { 388 | nbr_errors++; 389 | if (nbr_errors >= YM_PACKET_ERROR_MAX_NBR) { 390 | YM_ERR("YM: RX errors too many: %d - ABORT.\n", (unsigned int)nbr_errors); 391 | goto rx_err_handler; 392 | } 393 | } 394 | __ym_putchar(YM_CRC); 395 | break; 396 | } /* default */ 397 | } /* switch */ 398 | 399 | /* check end of receive packets */ 400 | } while (! file_done); 401 | 402 | /* check end of receive files */ 403 | } while (! session_done); 404 | 405 | /* return bytes received */ 406 | return filesize; 407 | 408 | rx_err_handler: 409 | __ym_putchar(YM_CAN); 410 | __ym_putchar(YM_CAN); 411 | __ym_sleep_ms(1000); 412 | return 0; 413 | } 414 | 415 | /* ------------------------------------ */ 416 | static void ym_send_packet(uint8_t *txdata, 417 | int32_t block_nbr) 418 | { 419 | int32_t tx_packet_size; 420 | 421 | /* We use a short packet for block 0, all others are 1K */ 422 | if (block_nbr == 0) { 423 | tx_packet_size = YM_PACKET_SIZE; 424 | } 425 | else { 426 | tx_packet_size = YM_PACKET_1K_SIZE; 427 | } 428 | 429 | uint16_t crc16_val = ym_crc16(txdata, tx_packet_size); 430 | 431 | /* For 128 byte packets use SOH, for 1K use STX */ 432 | __ym_putchar( (block_nbr == 0) ? YM_SOH : YM_STX ); 433 | /* write seq numbers */ 434 | __ym_putchar(block_nbr & 0xFF); 435 | __ym_putchar(~block_nbr & 0xFF); 436 | 437 | /* write txdata */ 438 | int32_t i; 439 | for (i = 0; i < tx_packet_size; i++) { 440 | __ym_putchar(txdata[i]); 441 | } 442 | 443 | /* write crc16 */ 444 | __ym_putchar((crc16_val >> 8) & 0xFF); 445 | __ym_putchar(crc16_val & 0xFF); 446 | } 447 | 448 | /* ----------------------------------------------- */ 449 | /* Send block 0 (the filename block), filename might be truncated to fit. */ 450 | static void ym_send_packet0(const char* filename, 451 | int32_t filesize) 452 | { 453 | int32_t pos = 0; 454 | /* put 256byte on stack, ok? reuse other stack mem? */ 455 | uint8_t block[YM_PACKET_SIZE]; 456 | if (filename) { 457 | /* write filename */ 458 | while (*filename && (pos < YM_PACKET_SIZE - YM_FILE_SIZE_LENGTH - 2)) { 459 | block[pos++] = *filename++; 460 | } 461 | /* z-term filename */ 462 | block[pos++] = 0; 463 | 464 | /* write size, TODO: check if buffer can overwritten here. */ 465 | pos += ym_writeU32(filesize, &block[pos]); 466 | } 467 | 468 | /* z-terminate string, pad with zeros */ 469 | while (pos < YM_PACKET_SIZE) { 470 | block[pos++] = 0; 471 | } 472 | 473 | /* send header block */ 474 | ym_send_packet(block, 0); 475 | } 476 | 477 | /* ------------------------------------------------- */ 478 | static void ym_send_data_packets(uint8_t* txdata, 479 | uint32_t txlen, 480 | uint32_t timeout_ms) 481 | { 482 | int32_t block_nbr = 1; 483 | 484 | while (txlen > 0) { 485 | /* check if send full 1k packet */ 486 | uint32_t send_size; 487 | if (txlen > YM_PACKET_1K_SIZE) { 488 | send_size = YM_PACKET_1K_SIZE; 489 | } else { 490 | send_size = txlen; 491 | } 492 | /* send packet */ 493 | ym_send_packet(txdata, block_nbr); 494 | int32_t c = __ym_getchar(timeout_ms); 495 | switch (c) { 496 | case YM_ACK: { 497 | txdata += send_size; 498 | txlen -= send_size; 499 | block_nbr++; 500 | break; 501 | } 502 | case -1: 503 | case YM_CAN: { 504 | return; 505 | } 506 | default: 507 | break; 508 | } 509 | } 510 | 511 | int32_t ch; 512 | do { 513 | __ym_putchar(YM_EOT); 514 | ch = __ym_getchar(timeout_ms); 515 | } while ((ch != YM_ACK) && (ch != -1)); 516 | 517 | /* send last data packet */ 518 | if (ch == YM_ACK) { 519 | ch = __ym_getchar(timeout_ms); 520 | if (ch == YM_CRC) { 521 | do { 522 | ym_send_packet0(0, 0); 523 | ch = __ym_getchar(timeout_ms); 524 | } while ((ch != YM_ACK) && (ch != -1)); 525 | } 526 | } 527 | } 528 | 529 | /* ------------------------------------------------------- */ 530 | int32_t fymodem_send(uint8_t* txdata, size_t txsize, const char* filename) 531 | { 532 | /* flush the RX FIFO, after a cool off delay */ 533 | __ym_sleep_ms(1000); 534 | __ym_flush(); 535 | (void)__ym_getchar(1000); 536 | 537 | /* not in the specs, send CRC here just for balance */ 538 | int32_t ch; 539 | do { 540 | __ym_putchar(YM_CRC); 541 | ch = __ym_getchar(1000); 542 | } while (ch < 0); 543 | 544 | /* we do require transfer with CRC */ 545 | if (ch != YM_CRC) { 546 | goto tx_err_handler; 547 | } 548 | 549 | bool crc_nak = true; 550 | bool file_done = false; 551 | do { 552 | ym_send_packet0(filename, txsize); 553 | /* When the receiving program receives this block and successfully 554 | opened the output file, it shall acknowledge this block with an ACK 555 | character and then proceed with a normal XMODEM file transfer 556 | beginning with a "C" or NAK tranmsitted by the receiver. */ 557 | ch = __ym_getchar(YM_PACKET_RX_TIMEOUT_MS); 558 | if (ch == YM_ACK) { 559 | ch = __ym_getchar(YM_PACKET_RX_TIMEOUT_MS); 560 | if (ch == YM_CRC) { 561 | ym_send_data_packets(txdata, txsize, YM_PACKET_RX_TIMEOUT_MS); 562 | /* success */ 563 | file_done = true; 564 | } 565 | } 566 | else if ((ch == YM_CRC) && (crc_nak)) { 567 | crc_nak = false; 568 | continue; 569 | } 570 | else if ((ch != YM_NAK) || (crc_nak)) { 571 | goto tx_err_handler; 572 | } 573 | } while (! file_done); 574 | 575 | return txsize; 576 | 577 | tx_err_handler: 578 | __ym_putchar(YM_CAN); 579 | __ym_putchar(YM_CAN); 580 | __ym_sleep_ms(1000); 581 | return 0; 582 | } 583 | 584 | /* ------------------------------------ */ 585 | /* Simple example function how to use */ 586 | int main(void) 587 | { 588 | char buf[100]; 589 | char fname[FYMODEM_FILE_NAME_MAX_LENGTH]; 590 | size_t length = sizeof(buf); 591 | uint32_t i = 0; 592 | while (i < sizeof(fname)) { fname[i++] = '\0'; } 593 | sprintf(fname, "%s", "test.txt"); 594 | int32_t r = fymodem_receive((uint8_t *)buf, length, fname); 595 | int32_t s = fymodem_send((uint8_t *)buf, length, "test.txt"); 596 | return (int)r+(int)s; 597 | } 598 | -------------------------------------------------------------------------------- /fymodem.h: -------------------------------------------------------------------------------- 1 | #ifndef _FYMODEM_H_ 2 | #define _FYMODEM_H_ 3 | 4 | /** 5 | * Free YModem implementation. 6 | * 7 | * Fredrik Hederstierna 2014 8 | * 9 | * This file is in the public domain. 10 | * You can do whatever you want with it. 11 | * 12 | * This program is distributed in the hope that it will be useful, 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 15 | */ 16 | 17 | #include 18 | #include 19 | #include 20 | #include 21 | #include 22 | #include 23 | 24 | /* max length of filename */ 25 | #define FYMODEM_FILE_NAME_MAX_LENGTH (64) 26 | 27 | /* receive file over ymodem */ 28 | int32_t fymodem_receive(uint8_t *rxdata, 29 | size_t rxsize, 30 | char filename[FYMODEM_FILE_NAME_MAX_LENGTH]); 31 | 32 | /* send file over ymodem */ 33 | int32_t fymodem_send(uint8_t *txdata, 34 | size_t txsize, 35 | const char *filename); 36 | 37 | #endif 38 | -------------------------------------------------------------------------------- /makefile: -------------------------------------------------------------------------------- 1 | # Just for check for warnings and errors 2 | all: 3 | @echo "Compile with C standard c89 no optimization..." 4 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O0 -std=c89 5 | @echo "Compile with C standard gnu89 no optimization..." 6 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O0 -std=gnu89 7 | @echo "Compile with C standard c99 no optimization..." 8 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O0 -std=c99 9 | @echo "Compile with C standard gnu99 no optimization..." 10 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O0 -std=gnu99 11 | @echo "Compile with C standard c11 no optimization..." 12 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O0 -std=c11 13 | @echo "Compile with C standard gnu11 no optimization..." 14 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O0 -std=gnu11 15 | 16 | @echo "Compile with C standard c89 speed optimization..." 17 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O3 -std=c89 18 | @echo "Compile with C standard gnu89 speed optimization..." 19 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O3 -std=gnu89 20 | @echo "Compile with C standard c99 speed optimization..." 21 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O3 -std=c99 22 | @echo "Compile with C standard gnu99 speed optimization..." 23 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O3 -std=gnu99 24 | @echo "Compile with C standard c11 speed optimization..." 25 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O3 -std=c11 26 | @echo "Compile with C standard gnu11 speed optimization..." 27 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -O3 -std=gnu11 28 | 29 | @echo "Compile with C standard c89 size optimization..." 30 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -Os -std=c89 31 | @echo "Compile with C standard gnu89 size optimization..." 32 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -Os -std=gnu89 33 | @echo "Compile with C standard c99 size optimization..." 34 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -Os -std=c99 35 | @echo "Compile with C standard gnu99 size optimization..." 36 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -Os -std=gnu99 37 | @echo "Compile with C standard c11 size optimization..." 38 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -Os -std=c11 39 | @echo "Compile with C standard gnu11 size optimization..." 40 | gcc -o fymodem -I. fymodem.c -Werror -W -Wall -Wextra -Os -std=gnu11 41 | --------------------------------------------------------------------------------