TTuurrbbooRRSS ----------------------------------------------------------------- Copyright 1993 Neat and Nifty Software PPuubblliicc DDoommaaiinn DDooccuummeennttaattiioonn TTuurrbbooRRSS ----------------------------------------------------------------- Version 1.00 CCooppyyrriigghhtt NNoottiiccee TurboRS is Copyright 1993 by Neat and Nifty Software This document is Copyright 1993 by Neat and Nifty Neither this document or associated software may be copied in whole or in part without the expressed permission of Neat and Nifty, unless distributed in its entire form along with all associated files. Release 1.00 of TurboRS is released as Public Domain and may be distributed on diskette or in archival form provided that the following files are included: TURBORS.TXT This document NOTICE.TXT Public Domain Notice TURBORS.PRG The software driver TURBOCNF.TTP Software Utility EXAMPLES.S Assembly Programming Examples ORDER.FRM Order Form for TurboRS DDiissccllaaiimmeerr Neat and Nifty makes no warranty of any kind, either stated or implied to the appropriateness of this product for any particular purpose. Continued use of this product is done entirely at the users own risk. Under no circumstances shall Neat and Nifty be liable for any damages (including loss of data, business time or information, or any other form of loss) incurred through use of this product, even if Neat and Nifty has been advised in advance of the possibility of such damages. NNoottiiccee This public domain release is not the complete TurboRS package. TurboRS itself is a hardware upgrade for the Atari ST line of computers which boosts the maximum baud rate of the ST serial port (TT Modem1) to 115200 baud. This release is meant to demonstrate TurboRS functionality, and also to provide a reference for programmers who wish to support it. The TurboRS hardware is required to use the extended baud rates supported by this package. i TTuurrbbooRRSS Hardware design: Daryl Richards Hardware testing: Daryl Richards Kevin Tessner Driver design: Daryl Richards Driver coding: Daryl Richards Kevin Tessner TurboCNF design and coding: Kevin Tessner Documentation: Kevin Tessner Edited By: Tass Chapman Atari TT Supplied by: George Kirkaldie Beta Testing: Daryl Richards Kevin Tessner George Kirkaldie ii CCoonntteennttss 1 T_u_r_b_o_R_S_ 1 How it Works . . . . . . . . . . . . . . . . . . . . . . 1 2 T_h_e_ T_u_r_b_o_R_S_ D_r_i_v_e_r_ 2 3 U_s_i_n_g_ T_u_r_b_o_C_N_F_ 3 Setting the Current Parameters . . . . . . . . . . . . . 3 Remapping Baud Rates . . . . . . . . . . . . . . . . . . 3 Locking a Baud Rate . . . . . . . . . . . . . . . . . . 3 Locking Flow Control . . . . . . . . . . . . . . . . . . 4 Viewing and Clearing the Settings . . . . . . . . . . . 4 Saving and Reloading the Settings . . . . . . . . . . . 4 Disabling / Enabling TurboRS . . . . . . . . . . . . . . 4 4 P_r_o_g_r_a_m_m_i_n_g_ f_o_r_ T_u_r_b_o_R_S_ 5 Through Software . . . . . . . . . . . . . . . . . . . . 5 Through Hardware . . . . . . . . . . . . . . . . . . . . 6 38400 Without TurboRS . . . . . . . . . . . . . . . . . 6 5 N_e_a_t_ a_n_d_ N_i_f_t_y_ 7 I_n_d_e_x_ 8 iii TurboRS (C) 1993 Neat and Nifty Page 1 ----------------------------------------------------------------- 11 TT_uu_rr_bb_oo_RR_SS_ In association with a small software driver, TurboRS allows your ST's serial port to operate at extended rates up to 115200 baud. The serial port remains fully software compatible, and is usually hardware compatible as well. The TurboRS software will work with any version of Tos running on any processor. HHooww iitt WWoorrkkss The baud rates in the ST are generated by System Timer D. The TurboRS board merely intercepts Timer D's output and replaces it with an externally generated signal for rates higher than 19200 baud. This interception is controlled by the unused RTS outputs of the MIDI and Keyboard control chips, or ACIAs. By using the software driver other programs can access the extended rates through standard system calls. TurboRS also allows you to remap any baud rate onto another. For example 300 baud can become 38400 for instant compatibility with older software. In addition, new communications products are being developed that directly support the extended rates without any remapping at all. Although TurboRS can be installed in the Atari TT, please note that it works only on the Modem1 port, and will have no effect, hardware or software, on the other available serial ports. There may be a future release which will work with Modem1 and Modem2. Some software on the Atari ST is marginally too slow to handle rates above 19200 baud and will lose characters during full speed bursts. TAZ, a high performance terminal package from Neat and Nifty Software, will operate reliably at higher speeds. Machines running with accelerators as low as 12Mhz have few problems, while 16Mhz Mega STEs and Atari TTs handle the higher baud rates with ease. TurboRS (C) 1993 Neat and Nifty Page 2 ----------------------------------------------------------------- 22 TT_hh_ee_ TT_uu_rr_bb_oo_RR_SS_ DD_rr_ii_vv_ee_rr_ To install the driver, simply run TURBORS.PRG from the distribution disk. It can be placed in the auto folder of your boot disk and should not affect any other software. If you are loading any serial port fixes, it is usually a good idea to load them first. When the driver loads, it looks for the file TURBORS.CNF on the root directory of the boot drive. If this file is found, TurboRS will automatically load up your preferred settings. Running TurboCNF with the -s option will create or update this file to the current settings. If this file is not found, TurboRS will revert to its default which matches the standard TOS bootup state. Without the hardware the driver will alert you with the message "No Hardware: 19200 Baud Physical Max". It will still install itself and perform all functions normally. The only limitation is that your serial port will never physically be running higher than 19200 baud. TurboRS (C) 1993 Neat and Nifty Page 3 ----------------------------------------------------------------- 33 UU_ss_ii_nn_gg_ TT_uu_rr_bb_oo_CC_NN_FF_ TurboCNF works with the TurboRS driver to add extended rate compatibility to non-TurboRS aware programs. It allows you to remap any rate to the ST baud rates, and also to lock the baud rate and flow control parameters. SSeettttiinngg tthhee CCuurrrreenntt PPaarraammeetteerrss The current baud rate can be set by typing it as a single argument to TurboCNF. Additional parameters can be set by including them after the desired rate in the order of Parity, Data Bits and Stop bits. For example, "TurboCNF 19200N81" will set the ST to 19200 baud, no parity, 8 data bits and 1 stop bit. Valid parity parameters are N, E, O for None, Even or Odd. Valid data bit settings are 5, 6, 7 and 8, while valid stop bit settings are 1, 2 and 3. Note that setting 3 actually produces 1.5 stop bits. If no additional parameters are given after the baud rate, the current ones will remain unchanged. RReemmaappppiinngg BBaauudd RRaatteess Baud rates are remapped by telling TurboCNF the rate to remap, followed by an equals sign and the rate to substitute. For example, to turn 300 baud into 38400, just run TurboCNF with the argument "300=38400". Multiple rates can be remapped on the same command line, ie: "TurboCNF 300=38400 1200=57600 4800=115200". All standard ST rates (including the useless ones) are supported by TurboCNF. That is: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 9600 and 19200. LLoocckkiinngg aa BBaauudd RRaattee Baud rates can be locked with the -l argument followed by the rate to be locked. To remove rate locking, simply use -l by itself. For example "TurboCNF -l38400" would lock the baud rate at 38400. Locked rates cannot be changed without rebooting the machine, or running TurboCNF with another -l argument. TurboRS (C) 1993 Neat and Nifty Page 4 ----------------------------------------------------------------- LLoocckkiinngg FFllooww CCoonnttrrooll For high speed modem use, flow control is essential. For this reason it can also be locked by TurboCNF. Use -f followed by one of the following control codes: 0 - No flow control 1 - XON/XOFF flow control 2 - RTS/CTS flow control 3 - XON/XOFF & RTS/CTS flow control Using -f by itself will remove a flow control lock. As of Tos 2.06, option 3 does not work properly, though it is described in Atari documentation. VViieewwiinngg aanndd CClleeaarriinngg tthhee SSeettttiinnggss To view the existing baud rate mapping and other settings, use the -v option. To reset all baud rates to standard mapping and clear the locks, use -r. SSaavviinngg aanndd RReellooaaddiinngg tthhee SSeettttiinnggss The current settings can be saved to the configuration file TURBORS.CNF in the root directory. When the driver loads it will use this file as its default. To create or update this file, use the -s option. If you would like to reload the settings in this file, run TurboCNF with -c. DDiissaabblliinngg // EEnnaabblliinngg TTuurrbbooRRSS If you are experiencing compatibility problems, the -d argument can be used to deactivate TurboRS. You can still change settings while the driver is disabled, but they will not take effect until TurboRS is enabled again with -e. TurboRS (C) 1993 Neat and Nifty Page 5 ----------------------------------------------------------------- 44 PP_rr_oo_gg_rr_aa_mm_mm_ii_nn_gg_ ff_oo_rr_ TT_uu_rr_bb_oo_RR_SS_ TThhrroouugghh SSooffttwwaarree:: The normal ST serial control is handled through the rsconf call (trap #14, function 15) which accepts the values 0 through 15 to specify the desired baud rate. The TurboRS driver adds the codes 16-18 for 38400, 57600 and 115200 baud respectively. Simply pass these values through the standard call and you're done. Please note that passing these numbers to rsconf without the driver installed may yield very bizarre rates! To detect whether or not the TurboRS driver is in memory, look in the cookie jar where you will find the cookie "TBRS" if the TurboRS driver is present. The value linked to this cookie is a pointer to the following structure in memory: struct { long magic; /* Used to verify cookie. Should always read $31415926 */ int rates[16]; /* Remap codes for ST baud rates - used to force higher rates with non - TurboRS aware programs. default: rates = [0,1,...,15] */ int lock_rate; /* Locked rate code (remap independent) if not -1 */ int lock_flow; /* Locked flow control if not -1 */ } TurboRS_Cookie; Note that "magic" should always be checked for $31415926 when determining the presence of the TurboRS driver. This is your insurance that the driver is not only present but also enabled. BBS programmers should take note of the lock_rate and lock_flow variables. These can be used to insure that BBS doors will not change the baud rate or flow control settings. This can make your BBS more "bullet proof". After setting these variables, call rsconf with any valid baud parameter. This insures that the locked values will take immediate effect. Don't forget to unlock them again afterwards by resetting them to -1. The TurboRS extended rsconf functionality (rate remapping and locking) apply only to the standard ST serial port, and will have no effect when other Bconmap compatible ports are configured. TurboRS (C) 1993 Neat and Nifty Page 6 ----------------------------------------------------------------- TThhrroouugghh HHaarrddwwaarree:: If your program must access the ACIAs directly, these are the values of bit 6 (RTS) of the ACIA control register required to control TurboRS. Note that when bit 6 is set, bit 5 must be clear or a break will be sent. The value in brackets is the control byte to use at each address to maintain the default MIDI and Keyboard settings of the ST (of course, if this is what you are going to do, you should just be using the driver). Rate $FFFFFC00 $FFFFFC04 TimerD 0 ($96) 0 ($95) 38400 0 ($96) 1 ($D5) 57600 1 ($D6) 0 ($95) 115200 1 ($D6) 1 ($D5) To autodetect the hardware, program the MFP for 9600 baud and set the ACIAs for 115200. Next disable the Modem1 interrupts to avoid clogging the Bios' routines. Transmit nulls in a loop and count how many you send in a tenth second. If you transmit more than 200, (technically 96, but this gives a much wider error margin) the TurboRS hardware is present. UNLESS YOUR SOFTWARE MUST PROGRAM THE ACIAS DIRECTLY FOR OTHER PURPOSES, USING THE DRIVER AND THE COOKIE IS THE ONLY WAY WE ADVISE SUPPORTING THE TURBORS BOARD. 3388440000 WWiitthhoouutt TTuurrbbooRRSS The ST is capable of handling 38400 baud without extra hardware by setting the MFP's USART to use the input clock directly. The default mode is to divide this clock by 16, which allows the USART to sample the incoming data 16 times per bit. When used directly, the incoming data is sampled only once per bit. Transmission is 100% reliable, but receive errors will occur when this sample is taken on a bit transition. This limits reception in this mode to 80% reliability. This mode can be programmed through the standard rsconf call by requesting 2400 baud (code 4) and clearing bit 7 of the UCR parameter. A standard rsconf call with bit 7 set restores normal operation. TurboRS (C) 1993 Neat and Nifty Page 7 ----------------------------------------------------------------- 55 NN_ee_aa_tt_ aa_nn_dd_ NN_ii_ff_tt_yy_ Neat and Nifty consists of Daryl Richards and Kevin Tessner. All products released under Neat and Nifty are copyrighted products of same and carry no warranties, stated or implied against misuse, damage, loss of data or any other loss, as a result of using said products. For bug reports, suggestions, or criticism, we can be reached as: ktessner@sanity.tdkcs.waterloo.on.ca drichards@sanity.tdkcs.waterloo.on.ca Or by writing to: Neat and Nifty 43 Carwood Crescent Kitchener Ontario N2G 3C6 Canada For the latest TurboRS updates and other products from Neat and Nifty, contact the following BBS system: Sanitarium (RATSoft ST) (519) 623-6116 300-16.8k Dual Standard Neat and Nifty conference OR Email to Pi or Mr Martian If you are interested in purchasing the full TurboRS package, please print out and complete ORDER.FRM included with this release. Please enclose a certified cheque or money order payable to Kevin Tessner and mail it to the above address. Please do not send cash in the mail! TurboRS (C) 1993 Neat and Nifty Page 8 ----------------------------------------------------------------- II_nn_dd_ee_xx_ Accelerators (1) Public Domain (i) ACIA Rsconf (5) Direct Accessing (6) Flow Locking (5) RTS Output (1) Rate Locking (5) Atari Mega STE Sanitarium (7) Rate Handling (1) Settings Atari ST Default (2) Rate Handling (1) Reloading (4) Serial Port (1) Saving (4) Atari TT TBRS Cookie (5) Rate Handling (1) Structure (5) Support (1) Verification (5) Autodetect Timer D (1) Hardware (6) Trap #14 (5) Software (5) TurboCNF (3) BBS Doors (5) Disabling (4) Bconmap (5) Enabling (4) Bug Reports (7) Locking Flow (4) Cookie Jar (5) Locking Rate (3) Copyright (i) Remapping Rates (3) Disclaimer (i) Resetting (4) Lock_flow Setting Rate (3) BBS Usage (5) View Settings (4) Cookie Structure (5) TurboRS Unlocking (5) Credits (ii) Lock_rate Description (1) BBS Usage (5) Software Driver (2) Cookie Structure (5) TURBORS.CNF (2) Unlocking (5) TURBORS.PRG Modem1 (1) Installing (2) Modem2 (1) Warnings (2) Neat and Nifty (7)