

























          TTuurrbbooRRSS
          -----------------------------------------------------------------
          Copyright 1993 Neat and Nifty Software


          PPuubblliicc DDoommaaiinn DDooccuummeennttaattiioonn

          TTuurrbbooRRSS
          -----------------------------------------------------------------
          Version 1.00


          CCooppyyrriigghhtt NNoottiiccee

          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


          DDiissccllaaiimmeerr

          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.


          NNoottiiccee

          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

          TTuurrbbooRRSS


          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

                                       CCoonntteennttss


          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
          -----------------------------------------------------------------


                                      11 TT_uu_rr_bb_oo_RR_SS_


          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.

          HHooww iitt WWoorrkkss

          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
          -----------------------------------------------------------------


                                 22 TT_hh_ee_ TT_uu_rr_bb_oo_RR_SS_ DD_rr_ii_vv_ee_rr_


          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
          -----------------------------------------------------------------


                                   33 UU_ss_ii_nn_gg_ TT_uu_rr_bb_oo_CC_NN_FF_


          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.

          SSeettttiinngg tthhee CCuurrrreenntt PPaarraammeetteerrss

          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.

          RReemmaappppiinngg BBaauudd RRaatteess

          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.

          LLoocckkiinngg aa BBaauudd RRaattee

          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
          -----------------------------------------------------------------


          LLoocckkiinngg FFllooww CCoonnttrrooll

          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.

          VViieewwiinngg aanndd CClleeaarriinngg tthhee SSeettttiinnggss

          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.

          SSaavviinngg aanndd RReellooaaddiinngg tthhee SSeettttiinnggss

          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.

          DDiissaabblliinngg // EEnnaabblliinngg TTuurrbbooRRSS

          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
          -----------------------------------------------------------------


                              44 PP_rr_oo_gg_rr_aa_mm_mm_ii_nn_gg_ ff_oo_rr_ TT_uu_rr_bb_oo_RR_SS_


          TThhrroouugghh SSooffttwwaarree::

          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
          -----------------------------------------------------------------


          TThhrroouugghh HHaarrddwwaarree::

          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.

          3388440000 WWiitthhoouutt TTuurrbbooRRSS

          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
          -----------------------------------------------------------------


                                   55 NN_ee_aa_tt_ aa_nn_dd_ NN_ii_ff_tt_yy_


          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
          -----------------------------------------------------------------




                                        II_nn_dd_ee_xx_


          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)
