                                             Ralf Biedermann
                                             Ortfeld 3
                                             27299 Langwedel
                                             Germany
                                             (49) 4235-8407
                                        Maus:Ralf Biedermann @ HB
                                        uucp:rb@rbsoft.bias.uni-bremen.de
                                           
                                          
Short documentation of TCache

It  is  only allowed to distribute the version TC_TEST.LZH without changes.
With  version 6.3 I released two versions of TCache. One is the testversion
which  displays  a  long  text  every  time  you  boot  your system. In the
registred  version  there  will  be  only  a text before you configured the
parameters   of   TCache.  It  is  possible  that  there  will  be  further
restrictions in the next version.

---------------------------------------------------------------------------
0. General information !

TCache  is  share-/charityware  which means that if you like TCache and use
it  regulary  you have to make a donation for an animalcharity (>=10 german
marks  or  equivalent)  if you don't want to make a donation then TCache is
shareware  (>=30  german  marks)  . If you send me a proof of your donation
you'll  receive the latest version of TCache including commented sourcecode
of  version  6.0  (comments  in  german  sorry).  If  you write from inside
germany  include  a  stamped  self  addressed  envelope.  If you write from
outside  germany include 2 IRC and a self addressed envelope. And of course
in  both cases a 3.5'' double density disc. Because it is very difficult to
send  money  to  a  foreign  country  I  am always open for other ideas for
example  a  pack  of HD-disc or a CD or some candy but in these cases write
me  a letter with your idea because when I eat even more candy I can't move
anymore and there will be no version 6.4 of TCache ;-{)}

---------------------------------------------------------------------------
1. What is TCache ?

TCache  is  a  very  fast  Harddisk-Cache  for the Atari range of computers
(ST/STE/TT/Falcon).  A  cacheprogram  stores  sectors from disk/harddisk in
ram   and  increases  the  speed  of  repeated  access  quite  dramaticly.  
Speedimprovements up to a factor of 6 is nothing special.

---------------------------------------------------------------------------
2. How to install TCache ?

You  must  copy TCache63.PRG into the autofolder of your bootdrive. Because
TCache  is  deactivated  after the first installation you have to make some
configurations   using   the   accessory   TC_ACC63.ACC.   You  can  rename
TC_ACC63.ACC  to  TC63_ACC.PRG  and  start it  from  the desktop or you put
TC_ACC63.ACC  into the rootdirectory of your bootdrive and perform a reset.
Now  you have to make the apropriate changes to the configuration of TCache
und  save  it  directly  in the programcode of TCache63.PRG. The meaning of
every option will be explained in the next chapter.

---------------------------------------------------------------------------
3. Options of TCache

With  the  programm  TC_ACC63.ACC  (.PRG!)  you  can change every option of
TCache.  In  this chapter I will try to explain every possibility in simple
words, because I can't explain it in detail in english.

-   If  you  click  on  the  top-button  you  will  receive  the  following
informations:  1. Name of the author (me). 2. Bootdevice, the single letter
in the top row. 3. over all memory requirement, in the button.

-  on the right are five radiobuttons. If you press one of the buttons the 
information  in  the big area on the left side will get a new contents.  

-  'Options' will let you change the options for every drive. These options
must  be  set for every drive. More about every single option later in this
document.

-  'Parameter'  shows  some  global values of TCache, this means that these
option are valid for all drives.

-   'Statistics'  gives  statistical  informations  about  the  success  of
cacheing for every drive.

-  'Special'  hides  two  interesting features of TCache. One denies access
for  choosen drives without a password and the second redirects access from
one drive to another one.

- 'Utilities' hides some global options and more special features.

-  under  the  radiobuttons are 16 more radiobuttons labeled with 'A'..'P',
with  these  buttons  you  can  select a drive for wich you want to see the
local  options  ('Options')  or  the statistics ('Statistics'). If you have
selected  either 'Parameter' or 'Special' or 'Utilities' these buttons will
have no effekt.

In  the  last  row  of the accessory are three buttons. The 'Abbort'-button 
means leave the accessory without any changes, 'OK' means apply all changes 
and  leave  the accessoy and save means apply all changes, save the changes 
in the program TCACHE63.PRG (name can be entred with a fileselectorbox) and 
leave the accessory.

---------------------------------------------------------------------------
Now some explanations of 'Options'

'Options' must be configured for every drive (click on 'A'..'P').

-  'drive  supported'  means that the drive selected (bottom right) will be
cached  according  to  your  further  configuration.  If this button is not
selected none of the other option for this drive will be active.

-  'write  changes  only'  means  that only sectors with a changed contents
will be written to disk.

-  'delayed write' means that a writeoperation will be delayed for a while.
This  is  a  bit dangerous because not every information will be immediatly
on  disk,  if the computer crashes before the information is written it can
result  in a loss of data. But this option is very usefull because a lot of
datahandling  will  be speeded up quite a bit. The best example is deleting
a  lot  of  files  with  'delayed  write'  it  will  have the speed of most
ramdiscs. If you want to change this option for one or more drives you must 
enter the correct password in a separate menu under 'Utilities'.

-  'writeprotected'  is  a  softwareprotection  of  a  writeaccess  for the
selected  drive.  If  you want to change this option for one or more drives
you must enter the correct password in a separate menu under 'Utilities'.

-  'calculate  checksum'  informs  TCache to calculate a checksum for every
sector.  This  option  is only usefull while testing new programs or during
programdevelopment because the speed will go down dramaticly.

-  'lock  Fat  & Root-Dir' means that sectors belonging to either FAT (file
allocation  table) or the rootdirectory will be locked in cache, they can't
be  overwritten.  If  you use only 32..256K for cache this option can speed
up things a bit.

-  'Mediach()  when  HIT' means that for every cachehit (sector is found in
cache)  the  program  checks if the media was changed in the meantime. This
option  must  be activ for every medium which could be changed, for example
floppydiscs. On harddiscs it's faster to leave this option unselected.

-  On the bottom is a row of radiobuttons labeled '0'..'9'. Theses buttons 
are  used  to  configure  the  so  called readprefetch. Readprefetch means 
reading  more  sectors  in  one call than GEMDOS wants to. If GEMDOS wants 
only  one  sector  TCache  reads more sectors and stores them in cache, if 
GEMDOS  wants  the  next sector it is already in ram and the speed will be 
very  high. With these buttons you can select the number of sectors TCache 
reads instead of only one sector. 

---------------------------------------------------------------------------
Now some explanations of 'Parameter'

-  'cachesize'  is the amount of ram you wants to use for TCache. TCache is
very  fast even if you try >1MB so don't be afraid to test large amounts of
memory.  This  size  is  only  used  for  storing sectordata, but for every
sector  there  is  an overhead of around 40 bytes so the total memory usage
will be higher than entered here.

-  'hashtable'  needs  a value between 8 and 16. This number is responsible
for  the  searchspeed when looking for a new sector. If you choose a number
n  then the memoryrequirement ist 4*2^n byte which means that 16 needs 256K
of  memory.  The  best  price/performance  value  in  my opinion is between
10..12.

-  'max.  prefetch'  is the size of the prefetchbuffer. This buffer is used 
for  sectorprefetch  and  for  cache  write back. A value between 10..99 is 
usefull. 32 is a good choice.

- 'readblock' contains the largest blocksize for reading which will be held 
in  cache. For example if you enter the value 32 every readaccess with less 
than 33 sectors will be load into the cacheram if there is enough room.

-  'writeblock'  contains  the  largest blocksize for writing which will be
held  in  cache.  For  example  if you enter the value 32 every writeaccess
with  less  than  33  sectors  will  be  load into the cacheram if there is
enough room.

-  'flushdelay' is the time which will be spent between the last discaccess
and  cache write back (castoff or flush). This value is multiplied by 5 and
the  result  is  a number of VBI (vertical blank interrupts) to wait before
starting writing back. For example if you enter the number 20 and you use a 
monochrome monitor with 70hz the delay will be 20*5/70==1.43sec.

-  'usage'  shows how full the cache is. If the number is inverted than the
cache  is  full  of  locked data. The second number shows the percentage of
Cache  used  by  locked data, for instance FAT-sectors if you have selected
'lock FAT & RootDir' for at least one drive.

- 'LED' let your floppy-led flash for every harddiscaccess.

- 'CLR' will flush and clear cachememory.

- 'LOCK' all sectors will be locked in cache (see 'lock Fat & Root-Dir')

- 'ACTIVE' enables or disables TCache completly.

---------------------------------------------------------------------------
Now some explanations of 'Statistics'

'Statistics' can be seen for every drive (click on 'A'..'P').

- 'read access' number of readaccesses since start of TCache or last 'CLR'.

-  'readhits' readhits since start of TCache or last 'CLR'. Number of saved
readaccesses.

-  'write  access'  number  of  writeaccesses since start of TCache or last 
'CLR'.

-  'writehits'  writehits  since  start  of TCache or last 'CLR'. Number of
saved writeaccesses.

-  'checksum  errors'  number af checksumerrors since start of TCache. This
value  is  only  of  interest  if 'calculate checksum' is active for one or
more drives.

-  'access  odd  address'  shows  the  number  of  reads/writes to/from odd
addresses.  This  can be of interest for program testing/developing because
a normal ST/STE is a lot slower in accessing odd adresses.

- 'free memory' shows the amount of free memory on the selected drive.

- 'sectorsize' shows the size of one sector for the selected drive.

---------------------------------------------------------------------------
Now some explanations of 'Special'

-  The  top half of this area is used for a security option. 'no access for
drive'  can  protect one or more drives against unwanted accesses from your
boss/brother.  You must make your configuration AND enter the password. You
won't  see  the  password  because it's hidden. On delivery the password is
set   to   'TCRB'.   The   password   must   be   entered   in   the   menu
Utilities-Password.  If you want to change this password you must enter the
menu  Utilities-Password and enter the old password in the top line and the
new password twice in the last two lines in this menu.

-  The  bottom  half  allows  you  to redirect the access from one drive to
another  drive.  With the arrows you can select the drive you would like to
be  redirected.  With  the radiobuttons beneath you can select the drive to
which the accesses will be redirected.

---------------------------------------------------------------------------
Now some explanations of 'Utilities'

-  'ramdisc'  shows  another  menue  which allows you to install a ramdisk.
Just  select  the drive and the amount of ram and press 'install'. If there
is  already  a  ramdisk  installed  press  'remove' to remove this one. The
ramdisc  is  very  fast  but  not  resetresident.  If  you have started the
konfigurationprogram  (TC63_ACC)  as  an application and you are using MinT
or Mag!X than it is impossible to install or remove the ramdisc.

-  'ACC-folder' shows another menue from which you can select a folder from
which  the  ACC's  will  be loaded after the next reset. Of course you must
save  the  configuration  for the desired result. To select the path simply
click  on  the  pathname and a fileselectorbox will apear. The button 'load
from folder' must be selected as well.

-  'steprate'  allows  you  to  switch  the  steprate for drive 'A' or 'B'.
Simply  select the desired steprate for drive 'A' (top row) and 'B' (second
row)  and select 'apply steprate'. If you save the TCache-configuration the
steprates will be set on boot.

-  'virtual' shows a menue which lets you install logical drives, these are
drives  which  aren't  physicly  attached  to  your computer. Together with
'Special'   'driveredirection'   you   can  create  almost  every  harddisc
configuration.  This  option is especially usefull if you want to install a
programm which is configured for drives which are absent on your computer.

-  'information' shows another menu with further global informations. These
informations  are:  'read  absolut'  Rwabs()-readmode >= 8, 'write absolut'
Rwbas()-writemode  >=  8,  'write-error'  number of problems during delayed
write,  'single  sector'  number of singlesectoraccesses, 'multiple sector'
number  of  multisectoraccesses,  'total  access' total number of accesses,
'Fat  & Rootaccess' number of accesses for the FAT or the rootrirectory and
last but not least 'total saved' number of saved accesses.

-  Turbo  ;-{)}  disables the statistical functions and some safetyroutines
for  every drive but 'A' and 'B'. This switch will speed up TCache a little
but  the  option  should only be used if there are no changeble devices but
drive  'A'  and 'B' in your system. This options should only be used if you 
are shure that your media and programeviroment is perfectly ok.

-  'del  delayed'  is  a  switch  which is responsible for the behaviour of
handling  delayed sectors. If this switch is active every delayed sector is
deleted  from  a  linked  list. This switch is only usefull if cachesize is
>1MB and 'delayed write' is activated. 

-  'LRU'  is  a switch for another way to handle the cache. LRU means 'last
recently   used'.   This  option  has  this  name  because  when  activated
(selected)  space  for  a new sector is taken from that sector which is not
accessed  for the longest time, otherwise space is taken from a round-robin
behaviour.  This  option  is  most  usefull  with  small cache (<=128K) and
without 'lock Fat & RootDir'.

- 'bootsector' is a switch to allow write-access to the bootsector. If this 
Button is enabled every attempt to write to the bootsector is answered with 
an errormessage.

-  'Flush  all'  means that all delayed data ist writen in one go. If this 
button isn't selected between blocks will be a little break. 

-  'sectortest'  means that TCache validates the sectornumbers. If someone 
tries  to  access a sectornumber outside of the partition an error 'sector 
not found' (-8) will be returned. 

-  'absolut' allows or denies accesses to a drive in an absolut manor which
means access to a drive without using partitioninformation. If you want  to
partition your HD absolut must be allowed.

- 'testing' shows if the ACC should test TCache every five seconds or not.

-  'PUN-INFO'  is  a flag which tells TCache to use the so called PUN-INFO 
structure  to  get  informations  about  the  largest sectorsize. If is not 
selected TCache makes a Getbpb() for every supported drive on startup.

-  'NOX !' is a very special thing. If you have a cookie called 'NOX!' and 
the  value  of  this cookie is a pointer to a subroutine then on start and 
end of a Rwabs()-call this routine will be called. 

-  'Drvbit-Check'  checks  the  systemvariable  '_drvbits' and denies every
access  to  a drive which isn't in '_drvbits' (anymore). It's main interest
is in program testing/developing.

-  'XBra-Check'  is  an  option  for TCache. TCache checks its programcode 
everytime  you  leave  a  program.  TCache  uses  the XBRA-standard and if 
anyone  changes  something  in  the programmcode TCache deinstalls itself. 
With  this switch you can select whether TCache should allow manipulations 
in his XBRA-structure or not. 

-  'etv_term'  means  that every time you leave a program the cache will be
flushed.  Only  of  interest  if  'delayed  write' is activ for one or more
drives.

-  'WriteReset' if selected TCache tries to flush the cache even if someone
has pressed 'CTRL+ALT+DEL' (warmreset). Only of interest if 'delayed write'
is active for one or more drives. 

-  'Gemdos'  if  selected  even  the  directories  of folders are locked in
cache.   Attention  this option needs a lot of ram, even on small harddiscs
I recommend >512K. 

-  'Clock' reads a special version of a realtimeclock on normal ST's during
booting.
