Apple-2-SW/rom4x
1
0
Fork 0
mirror of https://github.com/mgcaret/rom4x.git synced 2024-12-22 03:29:18 +00:00
Code Issues Projects Releases Wiki Activity

Docs updates for xmodem

Browse Source
This commit is contained in:
mgcaret 2018-10-13 14:18:13 -07:00
parent 65c2a4c7d0
commit a14af25f96
2 changed files with 56 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
rom4x/README.md
View File

@ -11,6 +11,7 @@ It adds the following features to the Apple //c:
- Tell the machine to boot the SmartPort, the internal floppy drive, or an external floppy drive.
- The system drops to BASIC if no bootable device is found (this is the default behavior in the IIc Plus).
- Configure default boot device by saving a file on the RAM Disk.
- As of the 10/01/2018 release, provides XModem-CRC features (see [xmodem.md](xmodem.md)).
RAM expansion cards known to work with ROM 4X include the Apple Memory Expansion Card (but no battery!), and the A2Heaven [RAM Express II](http://a2heaven.com/webshop/index.php?rt=product/product&product_id=146) for the original //c, and the [RAM Express II+](http://a2heaven.com/webshop/index.php?rt=product/product&product_id=144) for the memory-expandable //c and IIc Plus.
@ -114,6 +115,10 @@ This is like option 6, but using an external 5.25 drive. The only OS I am aware
This destructively copies a short routine to $800, which under most circumstances is also immediately overwritten by the boot sector, so should not be a problem..
#### XModem-CRC
See [xmodem.md](xmodem.md).
### Configuration File
If the RAM card is ProDOS-formatted, you can save a binary file in the volume directory called `BOOTX`. ROM 4X will find this file and use the Aux Type field (the load address) to set a default of the menu options above when no option has been selected using the menu. For example, `BSAVE /RAM4/BOOTX,A6,L0` will cause ROM 4X to skip booting the RAM card and go straight to booting the internal floppy drive (menu item 6). The contents of `BOOTX` are irrelevant, only the Aux Type is used. You cannot set it to jump into the monitor because that action happens before the boot code takes over.

51
rom4x/xmodem.md Normal file
View File

@ -0,0 +1,51 @@
# ROM 4X XModem-CRC
The 10/01/2018 release of ROM 4X includes XModem-CRC functionality.
The feature restores functionality to the SAVE and LOAD commands in AppleSoft BASIC, and re-introduces the W and R commands in the monitor.
The commands send/receive data through the Modem Port of the Apple //c.
The XModem-CRC functionality has been tested between the Apple //c and a PC running [Qodem](http://qodem.sourceforge.net) and between two Apple //cs using a null modem cable.
## Use of the XModem-CRC features
By default the data is sent at 115,200 bps 8N1. If you want to keep the current serial port speed/bits setting, hold the Closed Apple key while pressing the RETURN key for the below commands. Note that if the serial port is configured for 7 bit data, the transfer will fail.
### AppleSoft BASIC
To send the current program through the modem port, type `SAVE`. A 'W' will appear in the upper right corner of the screen, and after several seconds will start flashing. The save routine will wait approximately one minute for a receiver to be ready, otherwise it will exit and say "ERR". If you accidentally type SAVE, hit the ESC key and you will be returned to AppleSoft (again, with 'ERR'). Once the transfer starts, the upper right corner will cycle from 0 through 7 as each block is received (this is the lower 3 bits of the block number).
To receive a program through the modem port, type `LOAD`. A 'R' will appear in the upper right corner, and start flashing after a few seconds. The load routine will attempt to initiate the transfer every 3 seconds for one minute, otherwise exit with 'ERR'. If you wish to cancel the transfer, hit the ESC key. If you hit ESC before any blocks are received, your current program will stay intact. Once blocks are received, if the transfer fails or is cancelled, it will be as if NEW had been executed. A successful transfer results in the downloaded program being in memory.
### Monitor
To send data, type `xxxx.yyyyW`, as if you were using a machine with a cassette port, to send the data between addresses `xxxx` and `yyyy` (inclusive). The routine has the same wait/error conditions as the AppleSoft `SAVE` command, above.
To receive data, you can type `0R` to receive at the same address from which the data was written, or `zzzzR` to receive at address `zzzz` instead. The routine has the same receive/error conditions as the AppleSoft `LOAD` command, above.
As an example, you can copy the hi-res graphics page 1 from one machine to another via null modem cable by typing `2000.3FFFW` on the machine with the graphics and `0R` on the other machine.
## Troubleshooting
Occasionally the serial port gets finicky and receiving will instantly result in an ERR. Doing a trivial `SAVE` or `W` on the receiver, and then canceling and restarting the receive, will usually resolve this.
## Data Format
The data is sent/received via the XModem-CRC protocol, **without fallback to plain XModem**. Most modern terminal programs support XModem-CRC.
The data is sent with a 4-byte header in the first block that contains the address and length (minus one) of the data being sent. The exact length is sent in order to avoid leaking memory when receiving an AppleSoft program, as XModem does not have a built-in means of providing the length of the transfer.
When receiving, the machine will continue to receive blocks regardless of the length it receives in the first block, until the sender indicates it is done sending.
When transferring between an Apple //c and a PC, the 4-byte header must be included when sending a file to the //c. This will be present in any file originally received from a //c via XModem-CRC, but you will need to find a way to add it to anything that did not.
## Credits
I got the idea to implement this while discussing on Facebook the fact that `SAVE` and `LOAD` on the //c jump to the ampersand vector. The Facebook "Apple II Enthusiasts" group has inspired a lot of what I put into ROM 4X/5X.
I'd like to thank Reactive Micro for stepping up to deliver the ROM to people who can't build/burn it on their own. I have no desire to be in the taking orders/shipping business, and I am grateful, as are others, that there is someone who is.
Finally, the XModem-CRC routines are modified versions of Daryl Rictor's routines available at [6502.org](http://www.6502.org/source/io/xmodem/xmodem.htm).