Software and Utilities for Trident Disks:
                              Tfs and Tfu






1. Introduction


This document  describes Bcpl-based software  for operating any  of the
family of  Trident disk  drives attached  to an  Alto using  a "Trident
controller card" (the software presently deals with the T-80  and T-300
models).   Hardware  and diagnostic  information  can be  found  in the
document "Trident disk for the Alto"  (on <AltoDocs>AltoTrident.press),
by Roger Bates.

A  "Shugart controller  card" also  exists, for  connecting  to Shugart
model  SA-4004  and SA-4008  disk  drives.  The  Shugart  controller is
microprogram compatible  with the Trident  controller, and  the Trident
software can operate it as  well.  In this document, all  references to
Trident  disks  apply to  Shugart  disks as  well,  except  where noted
otherwise.

The software  documentation is  divided into three  parts: (1)  a brief
"how-to"  section  describing   the  software  package   available  for
operating the  Trident; (2)  a section  describing the  utility program
Tfu; and (3) a section describing the software package in  more detail.
There is a short revision  history at the end.  (Documentation  for the
Triex program, formerly included  here, has been eliminated.   Triex is
now needed only for hardware checkout and is not required during normal
operation.)

The  Tfs  package and  utilities  all assume  that  the disk  is  to be
formatted with  1024 data  words per sector.   The maximum  capacity of
each disk is given in the following table.

    Disk     Tracks   Heads    Sectors  Total pages   Total words
    T-80     815      5        9        36,675        37,555,200
    T-300    815      19       9        139,675       142,709,760
    SA-4004  202      4        8        6,464         6,619,136
    SA-4008  202      8        8        12,928        13,238,272

For all disks  except the T-300, it  is possible to construct  a single
Alto-format file system utilizing  the full disk capacity.  Due  to the
restriction of virtual disk addresses to 16 bits, a single  file system
may utilize only about 47 percent of a T-300 disk, and it  is necessary
to construct multiple file systems  in order to make use of  the entire
disk.

Because of bandwidth limitations,  it is unwise to operate  the Trident
disk while the Alto display is on.  Although the Tfs package  will save
the display state, turn it  off, run the disk, and restore  the display
for  every  transfer, the  user  may  prefer to  turn  the  display off
himself.  The Tfs management of the display causes the screen  to flash
objectionably whenever frequent calls to Tfs are underway.

                             ------------
                   Copyright Xerox Corporation 1980


Trident disk software        June 14, 1980                            2




The  present version  runs only  under Operating  System version  16 or
newer.



2. Trident File System (Tfs) software package


The  software   for  operating  the   Trident  disk  is   contained  in
<Alto>Tfs.dm,  and  consists   of  the  following   relocatable  files:
TfsInit.br, TfsBase.br, TfsA.br, TfsWrite.br TfsCreate.br, TfsClose.br,
TfsDDMgr.br,   TfsNewDisk.br,   TfsSwat.br,   and   TriConMc.br.    The
definitions file Tfs.d is also included.

Source files are contained in <AltoSource>TfsSources.dm.  Included also
are the Trident microcode source files, TriConMc.mu  and TriConBody.mu.
These are needed if you want to load other microcode into the Ram along
with the Trident microcode.

The  LoadRam.br file,  formerly included  as part  of the  Tfs,  is now
available as a separate package.


2.1. Initializing the microcode

Operating the  Trident requires special  microcode that must  be loaded
into the  RAM before  disk activity can  start.  The  procedure LoadRam
will load the RAM from a table loaded into your program (it is actually
part of TriConMc.br).  It will  then "boot" the Alto in order  to start
the  appropriate  micro-tasks in  the  RAM.  (This  booting  process is
"silent" -- it does not re-load Alto memory from the file Sys.Boot, but
instead lets your program  continue.) The standard way to  call LoadRam
to load the Trident disk microcode is:

        external DiskRamImage
        external LoadRam

        let result=LoadRam(DiskRamImage, true)  //Load and boot
        if result ls 0 then
                [
                Ws("The Alto has no RAM or no Ethernet board.")
                Ws(" Cannot operate Trident")
                finish
                ]

After  LoadRam  has  returned successfully,  the  code  of  LoadRam and
TriConMc may be overlaid with data -- they are no longer needed.

When exiting a  program that has micro-tasks  active in the RAM,  it is
helpful  to  "silently"  boot  the Alto  so  that  all  micro-tasks are
returned to the ROM.   If this is not  done, subsequent use of  the RAM
may cause some running micro-task to run awry.  To achieve  the "silent
boot," simply call the procedure TFSSilentBoot() at 'finish' time or as
part of a 'user finish procedure'.

For further information, consult the LoadRam package documentation.


Trident disk software        June 14, 1980                            3




2.2. Initializing the Trident drive

Once the RAM has been loaded, the Trident disk can be initialized.  The
procedure TFSInit will  do this, provided  that a legal  file structure
has previously been  established on the  drive (see Tfu  Erase, below).
The procedure returns  a "disk object," a  handle which can be  used to
invoke all the disk routines.   This disk object (or "disk"  for short)
can be passed to various  Alto Operating System procedures in  order to
open streams on Trident disk files, delete Trident disk files, etc.

tridentDisk = TFSInit(zone, allocate [false], driveNumber [0], ddMgr
            [0], freshDisk [false])

zone        You must provide a free-storage pool from which  memory for
            the disk  object and  possibly for a  buffer window  on the
            disk  bit table  can  be seized.   The zone  must  obey the
            normal  conventions  (see  Alto  Operating  System Manual);
            zones created by InitializeZone are fine.

allocate    This flag is true if you wish the machinery  for allocating
            or de-allocating disk space  enabled.  If it is  enabled, a
            small DDMgr object and a 1024-word buffer will be extracted
            from the zone in order to buffer the bit table  (unless you
            supply a ddMgr argument, described below).

driveNumber This argument, which defaults to 0, specifies the number of
            the Trident disk drive being initialized.  If the  drive is
            a T-300,  the left-hand  byte specifies  the number  of the
            file system to be accessed on that drive, in the range 0 to
            2.  (For further information, consult the  section entitled
            'Disk Format'.)

ddMgr       This argument, which defaults to 0, supplies a handle  on a
            'DiskDescriptor    Manager'    (DDMgr)     object,    whose
            responsibility it is to manage pages of  the DiskDescriptor
            (bit table), which, on the Trident, must be paged  into and
            out  of  memory  due to  its  considerable  size.   If this
            argument  is defaulted,  a separate  DDMgr will  be created
            upon each call to TFSInit, at a cost of a little  over 1024
            words.  If you intend to have multiple Trident  drives open
            simultaneously, you  may conserve  memory by  first issuing
            the call  'ddMgr =  TFSCreateDDMgr(zone)' and  then passing
            the returned pointer as the ddMgr argument in each  call to
            TFSInit, thereby permitting  the single ddMgr to  be shared
            among  all drives.   (This argument  is ignored  unless the
            allocate argument is true.)

freshDisk   Normally,  TFSInit  attempts  to  open  and  read   in  the
            DiskDescriptor file  in order  to obtain  information about
            the  file  system.   However, if  freshDisk  is  true, this
            operation is  inhibited and  the corresponding  portions of
            the  disk  object are  set  up with  default  values.  This
            operation is essential for creating a virgin file system.

tridentDisk The procedure returns  a disk object,  or 0 if  the Trident
            cannot  be  operated  for  some  reason.   The  most likely
            reasons are:

            1. No Trident disk controller plugged into the Alto.


Trident disk software        June 14, 1980                            4




            2. No such disk unit, or disk unit not on-line.

            3.  Can't  find  SysDir,  can't  open   DiskDescriptor,  or
            DiskDescriptor format is incompatible.  (These errors can't
            happen if freshDisk is true.)

            Important: If the AC power  to drive 0 is turned off  or no
            drive 0  is connected,  it is not  possible to  operate any
            drive.  (Drive 0 need not be on-line, however.) This is due
            to a  hardware bug  that has been  deemed too  difficult to
            fix.

After TFSInit has been executed, the code can be overlaid, as it is not
used for normal disk operation.


2.3. Closing the Trident disk

When all operations on  the disk are completed, the  TFSClose procedure
will insure that any important state saved in Alto memory  is correctly
written  on the  disk.   This step  can  be omitted  if  the 'allocate'
argument to TFSInit was false (assuming you don't mind the loss  of the
storage that was extracted from 'zone' by TFSInit).

        TFSClose(tridentDisk, dontFree [false])

The second argument is  optional (default=false), and if true  will not
permit the DiskDescriptor Manager (DDMgr) to be destroyed.  This option
is useful in conjunction with the 'ddMgr' argument to TFSInit.


2.4. Example

Following  is  an  example  that  uses  the  Trident  disk  system  and
demonstrates the  procedures described above.   Note that the  calls on
operating system disk  stream routines all pass  a private zone  to use
for stream structures, rather than the default sysZone.  The  reason is
that streams on Trident disks require large buffers (1024  words) which
quickly  exhaust  the available  space  in sysZone.   In  addition, the
stream  routines  will  consume more  stack  space  when  operating the
Trident disk than they do when operating the standard Alto disk.

Since the Alto  OS does not  know about Trident  disks, a call  to Swat
will  not properly  wait for  all Trident  transfers to  complete, with
consequent undefined results.  This problem is easily  remedied through
use of an  assembly-language Swat context-switching  procedure TFSSwat,
which is included as part of the TFS package.  The example shows how it
is set up.

//Example.bcpl -- TFS Example
//Bldr Example TfsBase TfsA TfsWrite TfsCreate TfsClose TfsDDMgr
//  TfsSwat TfsInit LoadRam TriConMc

get "streams.d"

external [
        TFSInit
        TFSClose
        TFSSilentBoot
        LoadRam


Trident disk software        June 14, 1980                            5




        DiskRamImage

        OpenFile
        Closes
        Puts
        DeleteFile

        InitializeZone
        SetEndCode
        TFSSwatContextProc
        lvUserFinishProc
        lvSwatContextProc
        ]

static [ savedUFP; savedSCP; TFSdisk = 0 ]

let TryIt() be
[
        let driveNumber=0
        let zonevec= vec 3000
        let TFSzone = InitializeZone(zonevec, 3000)

//Initialize the RAM:
        let res=LoadRam(DiskRamImage, true)
        if res ls 0 then [ Ws("Cannot load the RAM."); finish ]

//Set up to cleanly finish or call swat
        savedUFP = @lvUserFinishProc
        @lvUserFinishProc = MyFinish
        savedSCP = @lvSwatContextProc
        @lvSwatContextProc = TFSSwatContextProc

//Initialize the disk:
        TFSdisk = TFSInit(TFSzone, true, driveNumber)
        if TFSdisk eq 0 then
                [ Ws("Cannot operate Trident disk"); finish ]

//Reclaim space used by initialization code:
        SetEndCode(TFSInit)     //Overlay TFSinit, LoadRam, TriConMc

//Now we are ready to operate the disk:
        DeleteFile("Old.Bad", 0, 0, TFSzone, 0, TFSdisk)

        let s=OpenFile("New.Good", ksTypeReadWrite, 0,0,0,0,
                                TFSzone, 0, TFSdisk)

        for i=1 to 1000 do
         for j=1 to 1000 do Puts(s, $a) //Write a million bytes!

        Closes(s)

        finish
]

and MyFinish() be
[
        if TFSdisk ne 0 then TFSClose(TFSdisk)
        @lvUserFinishProc = savedUFP
        @lvSwatContextProc = savedSCP
        TFSSilentBoot()


Trident disk software        June 14, 1980                            6




]



3. Trident File Utility, Tfu


The  Tfu utility  (saved on  <Alto>Tfu.Run) is  used to  certify  a new
Trident pack  for operation, to  initialize a pack  with a  virgin file
system, and  to perform various  file copying, deleting,  and directory
listing operations.

Commands are given  to Tfu on  the command line:  immediately following
the word "Tfu" is a sub-command name (only enough characters of  a sub-
command are needed in order to distinguish it from other sub-commands),
followed by optional arguments.  Several subcommands may appear  on one
command line, separated by vertical  bars.  Thus "TFU Drive 1  | Erase"
will erase drive 1.  There must be a space on each side of the vertical
bar.

All information shown on the  display by Tfu is also written  into file
Tfu.log  (on  the  Diablo  disk).   Certain  commands  pause  and  type
"Continue?" after each screenful; type any character to proceed.

In what follows, an "Xfile" argument is a filename, perhaps preceded by
a string that specifies which disk is to be used:

        DP0:name.extension      -- use standard Alto (Diablo) disk
        TPn:name.extension      -- use Trident drive n (n=0 to 7)
        name.extension          -- use default disk (Trident)

The "default disk" is always a Trident drive; the identity of the drive
is set with the Drive command.

TFU DRIVE driveNumber

      This command sets the default Trident drive number to use for the
      remainder of the command line.  The default drive  is effectively
      an  'argument' to  the  CERTIFY, ERASE,  DIRECTORY,  CONVERT, and
      BADSPOTS commands.   (On a T-300,  file systems 0,  1, and  2 are
      specified  as  'TPx', 'TP40x',  and  'TP100x', where  'x'  is the
      actual unit number.)

TFU CERTIFY [passes]

      This command  initializes the  headers on  a virgin  Trident disk
      pack, then runs the specified number of passes (default  10) over
      the  entire  pack,  testing it  using  random  data.   Any sector
      exhibiting an uncorrectable ECC error, or correctable  ECC errors
      on two or more separate occasions, is permanently marked unusable
      in  the  pack's bad  page  list.  This  information  will survive
      across all  subsequent normal  file system  operations (including
      TFU ERASE), but may be clobbered by the Triex program.

      This command should be executed on every new Trident  pack before
      performing any other operations  (such as TFU ERASE).   10 passes
      of  TFU CERTIFY  are  adequate for  reasonably  thorough testing,
      though more are recommended for packs to be used  in applications
      requiring high  reliability.  The running  time per pass  for TFU


Trident disk software        June 14, 1980                            7




      CERTIFY is approximately 3  minutes on a Trident T-80,  9 minutes
      on a T-300, and 1.5 minutes on a Shugart SA-4008.

      TFU  CERTIFY  may  be  terminated  prematurely  by  striking  any
      character to get its attention, then typing 'Q'.  Subsequent runs
      of TFU CERTIFY will not clobber the existing bad page information
      but  rather will  append to  it.  It  is recommended  (though not
      necessary) that TFU CERTIFY be executed before each TFU  ERASE so
      as to pick up any new bad spots that may have developed.

      TFU CERTIFY ordinarily  asks you to  confirm wiping out  the disk
      before going ahead  and doing so;  however, the /N  global switch
      may be used to indicate that no confirmation is necessary.

TFU BADSPOTS

      Displays the addresses  of all known bad  spots on the  disk pack
      mounted on the default drive.

TFU RESETBADSPOTS

      Resets the bad spot table of the disk pack mounted on the default
      drive.  (Note that TFU  CERTIFY appends to the existing  bad spot
      table.) There should normally be no need to execute this command,
      but it may be useful, for example, after a disk pack  is cleaned,
      if the known bad spots were caused by dirt.

TFU ERASE [tracks]

      This command initializes (or reinitializes) a file system  on the
      pack mounted on  the default Trident  drive, after asking  you to
      confirm your destructive intentions (overridden by the  /N global
      switch).  The tracks argument specifies how many "tracks"  of the
      drive are to be included  in the file system; it defaults  to the
      maximum   possible.    If   smaller   numbers   are   used,   the
      initialization is  correspondingly faster.   In any  case, tracks
      beyond  the  one  specified are  available  for  use  outside the
      confines of the file system.  (Note that one "track" is 45 pages;
      this corresponds  to one  cylinder on  a T-80  and to  nothing in
      particular on other disks.)

      The disk pack should previously have been initialized  and tested
      by means of the TFU CERTIFY command.

      The DiskDescriptor file is normally located in the middle  of the
      file  system  so as  to  minimize average  head  movement between
      DiskDescriptor  and file  pages.   However, this  does  limit the
      maximum size contiguous file that can be created to a little less
      than half the  file system.  If you  wish to create  a contiguous
      file  larger  than  that,  use the  /B  local  switch  (i.e., TFU
      ERASE/B)  to  force  the  DiskDescriptor  to  be  located  at the
      beginning of the file system instead.

TFU COPY Xfile _ Xfile

      This command copies  a file in the  direction of the  arrow.  The
      destination file may be optionally followed by the switch  /C, in
      which case (provided it is a Trident disk file), the file will be
      allocated on the disk at consecutive disk addresses.  (Note: More


Trident disk software        June 14, 1980                            8




      precisely, an attempt will be made to perform such an allocation.
      If the attempt  fails, you will  sometimes get an  error message.
      The best way to  verify that a file  is contiguous is to  use the
      "address" command, below.)

TFU CREATEFILE Xfile pages

      This command  creates a contiguous  file named Xfile  with length
      "pages."

TFU DELETE Xfile Xfile ...

      This command deletes the given file(s).

TFU RENAME Xfile _ Xfile

      This command renames a file.

TFU DIRECTORY [Xfile]

      This command lists the directory of the default Trident  drive on
      the file Xfile; if Xfile is omitted, each entry will be  shown on
      the display.   A somewhat  more verbose  listing can  be obtained
      with TFU DIR/V.

TFU ADDRESS Xfile

      This command reads the entire file and displays a list (in octal)
      of virtual disk addresses of the file pages.

TFU CONVERT

      An incompatible change in  the format of DiskDescriptor  was made
      in the Tfs  release of July 24,  1977.  The current  Tfs software
      will refuse  to access  Trident disks written  in the  old format
      (specifically,  TFSInit  will  return  zero).   The  TFU  CONVERT
      command  reformats  the  DiskDescriptor  to  conform  to  current
      conventions (it is a no-op if applied to a disk that  has already
      been converted).  Once you have converted all your Trident disks,
      you should take care to  get rid of all programs loaded  with the
      old  Tfs,  since   the  old  Tfs   did  NOT  check   for  version
      compatibility.

TFU EXERCISE passes drive drive drive ...

      This command  embarks on  a lengthy  "exercise" procedure;  it is
      repeated 'passes'  times (default=10), and  uses the  disk drives
      listed after 'passes' (if none are specified, all drives that are
      on-line  are used).   It  operates by  making a  series  of files
      (test.001,  test.002  etc.)  on the  disk  packs,  and performing
      various  copying, deleting,  writing and  positioning operations.
      The  files are  deleted when  the exercise  finishes.  It  is not
      essential that the packs be fully erased initially; the procedure
      for building test files will try to fill up the disk,  just short
      of overflowing.   Each pass  of the  test takes  approximately 20
      minutes per T-80,  60 minutes per T-300,  and 10 minutes  per SA-
      4008.

      One or  more of  the following global  switches may  be specified
      (i.e., a command of the form TFU/switch EXER...):


Trident disk software        June 14, 1980                            9




      /W  Use a systematic data pattern when writing files, rather than
          arbitrary garbage.

      /C  Carefully check  the data  read from  the disk  (implies /W).
          Use of  this switch  makes the  test run  considerably slower
          than normal.

      /D  Leave  the display  on during  Trident disk  transfers.  This
          causes data  late errors to  occur and thereby  exercises the
          error recovery  logic.  (It  also slows down  the test  by at
          least a factor of 10.)

      /E  Turn  the Ethernet  on  during Trident  disk  transfers, with
          results similar to /D.



4. The Tfs software package in more detail


If programmers wish to interface  the the Trident disk at  levels lower
than Operating System streams,  the Tfs package provides  an additional
interface.   The  "disk" object  created  by TFSInit  has  a  number of
abstract operations  defined on it,  which the Tfs  package implements.
Documentation for these operations  can be found in the  Alto Operating
System Manual in  the section labeled "Disks  and Bfs." The  catalog of
available procedures is:

In TfsBase.Br and TfsA.Br:
        ActOnDiskPages(disk, CAs, DAs, ....)
        RealDiskDA(disk, vda, ....)
        VirtualDiskDA(disk, ....)
        InitializeDiskCBZ(disk, cbz, ...)
        DoDiskCommand(disk, cb, ...)
        GetDiskCb(disk, cbz, ...)

In TfsWrite.Br:
        WriteDiskPages(disk, CAs, DAs, ....)
        AssignDiskPage(disk, vda)*

In TfsCreate.Br
        CreateDiskFile(disk, name, ....)*
        DeleteDiskPages(disk, CA, ....)*
        ReleaseDiskPage(disk, vda)*

In TfsClose.Br
        CloseDisk(disk, dontFree)


The items with *'s following may be invoked only if the disk object was
created with the 'allocate'  argument set to true.   WriteDiskPages may
be invoked even if 'allocate' is false, provided it never allocates new
disk space.  It should be noted that the standard Alto  Streams package
invokes WriteDiskPages even for files opened for reading only, and that
TFSInit  uses  Streams to  read  in the  DiskDescriptor.   Hence  it is
necessary  that  all  of  the  Tfs  modules  (TfsBase,  TfsA, TfsWrite,
TfsCreate,  and  TfsDDMgr)  be  loaded  in  order  to  avoid  undefined
'external' references.  However, after initialization is  complete, the
space occupied by TfsCreate and TfsDDMgr may be reclaimed if you do not


Trident disk software        June 14, 1980                           10




intend to allocate  or delete pages, and  TfsWrite may be  discarded if
you  are  not  using  streams  but  rather  are  calling ActOnDiskPages
directly.

The TfsWrite  and TfsCreate modules  require that TfsDDMgr.Br  (or some
equivalent) be  loaded.  This module  provides the  standard primitives
necessary for managing the  DiskDescriptor.  The DDMgr is  an 'object',
so  it may  be replaced  by  one of  your own  devising so  long  as it
provides equivalent operations.  An example of this would be  to manage
pages of the  DiskDescriptor as part of  a more general  virtual memory
mechanism (perhaps through use  of the Alto VMem package).   A complete
description of the required  DDMgr operations may be found  as comments
at the beginning of TfsDDMgr.Bcpl.

In addition to the  standard "actions" defined in Disks.d,  Tfs permits
the following.  These  actions are defined  in Tfs.d and  are available
only on Trident disks.

        DCreadLnD   Read header, read label, no data.

        DCreadnD    Check header, check label, no data.

        DCwriteLnD  Check header, write label, no data.

These actions neither read nor  write the data record and  therefore do
not require a buffer to be provided.

CreateDiskFile has a special feature for operating the Trident disks --
an optional seventh argument.   If this argument (pageBuf)  is present,
it is  assumed to  point to  a 1024-word  buffer that  will be  used to
create the leader page for the file.  This feature may be used  to save
stack space in  CreateDisk file and/or  to write interesting  data into
the portion of the  leader page not used  by the file system  (only the
first  256 words  are used  by the  file system;  the remainder  has no
standard interpretation).

VirtualDiskDA returns fillInDA as  the virtual address for a  real disk
address that  is either  illegal or  outside the  confines of  the file
system.

The procedures for creating and destroying the disk object, TFSInit and
TFSClose,      were      explained      above.       The      procedure
TFSWriteDiskDescriptor(disk)  will write  out onto  the disk  all vital
information about the disk that  is presently saved in memory.   If you
write programs that run the disk for extremely long periods of time, it
is wise to write the disk descriptor occasionally.  The  only automatic
call on TFSWriteDiskDescriptor is performed by TFSClose.

TfsInit.Br  contains a  procedure TFSDiskModel(disk)  that  returns the
model number of the drive referenced by the disk handle (80 = T-80, 300
= T-300, 4004 = SA-4004,  4008 = SA-4008).  This is useful  in deciding
whether to open a second or third file system on a T-300.

A   lower   level   of   access   is   permitted   with   the  routines
InitializeDiskCBZ, GetDiskCb, and  DoDiskCommand, analogous to  the Bfs
routines  described in  the Operating  System Manual.   Users  of these
routines may  wish to  retrieve source  files for  the Tfs  package and
examine the definitions in Tfs.D and the actual disk operation  in some
detail. Sources are on <AltoSource>TfsSources.Dm.


Trident disk software        June 14, 1980                           11




4.1. TFSNewDisk

The  TFSNewDisk procedure,  defined in  TfsNewDisk.Br, "erases"  a disk
(formatting it  and making  all its  pages appear  free) and  creates a
virgin Alto file system (SysDir and DiskDescriptor).  It is called by:

        success = TFSNewDisk(zone, driveNumber [0], diskSize [default],
ddVDA [diskSize/2])

The zone passed to TFSNewDisk  must be capable of supplying  about 3500
words of storage.  If the drive is a T-300, the driveNumber may include
a file  system number (0  to 2) in  its left byte,  as is the  case for
TFSInit.   The diskSize  argument is  the number  of disk  pages  to be
included in the file system; it defaults to the maximum possible, which
is all of any disk besides a  T-300 or a little less than half of  a T-
300.   ddVDA  is  the  virtual disk  address  at  which  to  locate the
DiskDescriptor file; see the TFU ERASE command for elaboration on this.

TFSNewDisk returns true if successful.


4.2. DiskFindHole

The procedure DiskFindHole, in DiskFindHole.Br, can be used to locate a
"hole" of available space in the disk bit table.  The call:

        virtualDA = DiskFindHole(disk, nPages)

will attempt to locate a contiguous hole nPages long.  If it fails, the
procedure returns -1, otherwise  the virtual disk address of  the first
page of the hole.

In order to create a  contiguous file, it is first necessary  to create
the minimal file with a leader page at the given disk address  and then
to use Operating  System or Tfs routines  to extend the  file properly.
The first step is achieved by calling

ReleaseDiskPage(disk, AssignDiskPage(disk, vda-1))

where 'vda' is the desired  disk address (i.e., the result  returned by
DiskFindHole).  This  value will  control the  selection of  an initial
disk address for the leader page.  Once the file is created, it is wise
to extend it to its final length immediately, as other disk allocations
might encroach on the "hole" that was located.

For example, if we are using the Operating System, we might  proceed as
follows:

        let nPages=433          //Number of data pages needed.
        let vda=DiskFindHole(disk, nPages+2)
                                //(+2= 1 for leader, 1 for last page)
        test vda eq -1
                ifso Ws("Cannot find a hole big enough") ]
                ifnot ReleaseDiskPage(disk, AssignDiskPage(disk,vda-1))

        let s=OpenFile("New.Contiguous",ksTypeWriteOnly,0,verNew,0,0,0,
                        TFSzone, 0, disk)
        PositionPage(s, nPages) //Make the file the right length
        Closes(s)


Trident disk software        June 14, 1980                           12




5. File structure on the Trident disk


The  file structure  built on  the Trident  disk by  Tfs  (Trident File
System) is as exact a copy of the Alto file structure built  Bfs (Basic
File System)  as is  possible.  Certain exceptions  are present  due to
hardware  and  microcode   differences.   The  Alto   Operating  System
Reference Manual should be consulted for all file formats  and internal
information not presented here.


5.1. Disk Format

The Trident or Shugart disk drives are set up to run with the following
parameters:

        Disk            Cylinders Heads     Sectors
        T-80            815       5         9
        T-300           815       19        9
        SA-4004         202       4         8
        SA-4008         202       8         8

TFU CERTIFY  will format each  sector of the  disk in the  standard Tfs
format:

        header words per sector:        2
        label words per sector:         10
        data words per sector:          1024

Thus, for  example, a T-80  disk will have  9*5*815 = 36,675  sectors =
37,555,200 words.  Sector 0 will not be used by Tfs.  All but  sector 0
will be available to the file system.

Ordinarily, Tfs utilizes only the first 383 cylinders (= 65,493 sectors
= 67,064,032  words) of  a T-300  disk.  This  is the  largest integral
number of cylinders that can  be addressed using a 16-bit  virtual disk
address.  The 16-bit virtual  address limitation is deeply  embedded in
all existing  higher-level Alto file  system software, so  changing the
Tfs  interface  to  permit  a larger  virtual  address  space  would be
impractical.

Instead, Tfs permits one  to obtain another, entirely  independent disk
object  for referencing  the second  383 cylinders  of the  same T-300,
thereby  permitting  a  separate,  self-contained  file  system  to  be
constructed.  This is  done by passing  a '1' in  the left byte  of the
'driveNumber' argument to TFSInit or TFSNewDisk (that is,  drive '#400'
refers to the second file system  on a T-300 pack mounted on  drive 0).
A  third  file  system   (number  '2',  drive  '#1000')  may   also  be
constructed, but it  contains only 49 cylinders  (= 8379 pages,  only 6
percent of  the disk's  total capacity),  so doing  so is  probably not
worthwhile.


5.2. Disk Header and Label

On the  Trident, a  real disk  address requires  two words  to express,
rather  than  the  single  word  on  the  Diablo  31.   Also, microcode
considerations gave rise to a  reordering of the entries in  the Label.
The result is that both the header and label formats are  different for


Trident disk software        June 14, 1980                           13




the Trident.   The Trident  format follows.  If  you are  interested in
this level  of detail, the  file Tfs.d (contained  within <Alto>Tfs.dm)
should be consulted.

        // disk header
        structure DH:
                [
                track word
                head byte
                sector byte
                ]

        // disk label
        structure DL:
                [
                fileid word lFID
                packID word
                numChars word
                pageNumber word
                previous @DH
                next @DH
                ]
                manifest lDL = size DL/16


5.3. Disk Descriptor

Every valid Tfs disk has on  it two files which must contain  the state
information necessary  to maintain  the integrity  of the  file system.
The Tfs system directory, "SysDir.", is identical in format and purpose
with  its  Bfs  counterpart.  However  the  Tfs  disk  descriptor file,
"DiskDescriptor.", while identical in purpose, is formatted differently
to allow easy  manipulation of the bit  table (which, for  the Trident,
has  to be  paged in  and out  of memory).   This difference  in format
should not be evident to even low-level Trident users (unless you write
your own DDMgr), but is mentioned here for completeness.


5.4. Bad Page Table

Tfs  and  Tfu  observe  the standard  Alto  file  system  convention of
recording -2's in the labels of all known bad pages.  However,  if this
were the only location of such information, "erasing" a disk (to create
a virgin file  system) would require two  passes over the  entire disk:
one to collect the addresses of all known bad pages and one to mark all
remaining pages  deleted.  This  would require  an excessive  amount of
time, particularly on a T-300.

A duplicate table of known bad pages is therefore recorded  on physical
page zero (= cylinder 0, head  0, sector 0) of the disk.  This  page is
not available to  the file system for  other reasons having to  do with
end-of-file detection.   The format of  the table is  given by  the BPL
structure, which is defined in  Tfs.d.  Note that the entries  are REAL
disk  addresses  and  can  therefore refer  to  any  page  on  the disk
regardless of whether or not such a page is accessible through the file
system.  (A  T-300 has  only one bad  page table,  even if  it contains
several file systems.)

The  TFU  CERTIFY  command  is responsible  for  testing  the  pack and


Trident disk software        June 14, 1980                           14




building the bad page  table.  The TFSNewDisk procedure (called  by TFU
ERASE)  is  careful  not  to clobber  this  information  but  rather to
propagate it to the other  places where it is needed (namely,  the disk
bit table and  the labels of the  bad pages themselves).  As  a result,
the bad  page information,  once initialized,  will survive  across all
normal operations on the disk, including "erase" operations.

There does not presently  exist any facility for manually  appending to
this list when new bad  pages are discovered.  Experience to  date with
the Trident disks (which provide  correction for error bursts of  up to
11  bits in  length) has  shown that  such a  facility is  probably not
needed.  Thorough testing of  disks (using TFU CERTIFY)  is recommended
before putting them into regular use, however.



6. Revision History


July 24, 1977

Incompatibilities:

The format of  DiskDescriptor has changed.   The new Tfs  cannot access
old disks or vice versa.  See description under "TFU CONVERT".

There  is  now  another  file,  TfsA.Br,  that  is  logically  part  of
TfsBase.Br and  must be  loaded along with  it.  It  contains assembly-
language code formerly included as "tables" in TfsBase.Br.

New Features:

Partial support for T-300 disks.

Conforms  to new  conventions for  maintaining addresses  of  known bad
pages.

TFSInit checks for valid SysDir leader page and DiskDescriptor version.

Count of bit table  discrepancies added to DiskDescriptor.   (These are
pages falsely claimed to be free in the bit table.)

VirtualDiskDA returns fillInDA for illegal real disk addresses.

Additional Trident-specific disk actions.

Tfs is now entirely reentrant,  so it is safe for the  Idle() procedure
to give control to another process that in turn calls Tfs procedures.

October 21, 1977

Incompatibilities:

The former TfsWrite module has been broken into four  pieces: TfsWrite,
TfsCreate, TfsClose, and TfsDDMgr.  In most applications, all four must
be loaded.

The  'sharedBT' argument  to  TFSInit has  been replaced  by  a 'ddMgr'
argument.  The mechanism for sharing a bit table buffer  among multiple


Trident disk software        June 14, 1980                           15




drives has  been entirely changed.   (Programs that omit  this argument
are unaffected by the change.)

The  TFSCreateVDA static  has  been removed.   In  its place  is  a new
procedure TFSSetStartingVDA(disk, vda) that serves the same purpose.

The syntax  of the TFU  EXERCISE command has  been changed.  It  is now
'TFU EXERCISE <passes> <list of drives>', and <list of drives> defaults
to all drives that are on-line.

New features:

Complete  support  for  T-300 disks.   In  conjunction  with  this, the
TFSDiskModel procedure has been added.

It is now  possible for DiskDescriptor  pages to be  managed externally
(perhaps through  some sort of  virtual memory mechanism)  by use  of a
user-defined 'DiskDescriptor Manager' object.

TFSSilentBoot procedure added.

November 9, 1977

Incompatibilities: None.

New features:

TFU CERTIFY and TFU  BADSPOTS commands added.  TFU  CERTIFY initializes
the headers on a virgin disk pack and then runs repeated tests over the
entire pack, permanently recording  any bad spots that it  finds.  This
command  replaces   all  the   normal  uses   of  the   Triex  program,
documentation for which has been removed.

Microcode modified  for more  efficient reading  on Alto-IIs  (by about
25%).

February 26, 1978

Incompatibilities: Software updated to new time standard; will  not run
under OS versions earlier than 14.

New  features:  Microcode  source  now  in  two  parts,  to  facilitate
combining it with other microprograms.

December 15, 1978

Incompatibilities:  some  of  the TFS  DDMgr  procedures  renamed (used
internally).

New  features: returnIfNoCb  argument  to TFSGetCb;  ddVDA  argument to
TFSNewDisk; TFU ERASE/B option to maximize contiguous free storage; TFU
RESETBADSPOTS command added; TFS and TFU should run on Dorado.

June 25, 1979

Incompatibilities: none.

Changes:  Optional  "hintLastPage"  argument  added  to ActOnDiskPages,
WriteDiskPages, and DeleteDiskPages; several minor bugs fixed.


Trident disk software        June 14, 1980                           16




July 17, 1979

Incompatibilities:  The structure  of a  DSK (and  therefore  a TFSDSK)
changed,   so   programs   that  get   "Tfs.d"   must   be  recompiled;
TFSSetStartingVDA(disk,    vda)    procedure    removed--instead    use
ReleaseDiskPage(disk, AssignDiskPage(disk, vda-1)).

Changes: New operations InitializeDiskCBZ, DoDiskCommand, and GetDiskCb
added to the DSK  object in preparation for  OS 17.  Note that  the new
TFS will work under  earlier versions of the  OS, but the old  TFS will
not work under OS 17.

November 24, 1979

Incompatibilities: The manner  in which the  TFS turns the  display off
and on has been changed so  that it works correctly even if  the caller
accesses the  disk at  the DoDiskCommand/GetDiskCb  level, and  even if
there are multiple contexts making calls to the TFS.  Existing software
that uses the low-level procedures may require modification.

The microcode has  been modified, so  recompilation is required  of any
microprograms that include TriConMc.mu or TriConBody.mu as a component.
(The  interface  to the  microcode  has changed  slightly;  consult the
revised documentation in <AltoDocs>AltoTrident.press.)

Changes:  This  release  includes  some  substantial  changes  in error
recovery at both the microcode and the software level.   Formerly there
were  problems that  could  cause the  software  to get  hung  up under
extreme conditions such as operating the disk with the display on.

Unrecoverable  disk  errors   are  now  reported  with   more  complete
information.  (This requires new versions of Swat and Sys.errors, being
released simultaneously.) Additionally, if the currently-selected drive
goes   not-ready,  TFS   generates   an  error   rather   than  hanging
indefinitely.  Finally, attempting to write on a read-only  drive gives
rise to a distinct error.

TFU has been cleaned up somewhat.  It always generates a  typescript in
file TFU.log  (this replaces the  former TFU.ExerciseLog).   Disk drive
names are  now standardized: TP0  for Trident drive  0, DP0  for Diablo
drive 0.  TFU DELETE  can take multiple arguments.  TFU  RENAME command
has been added.

June 14, 1980

Incompatibilities: none.

Changes: The software  is now capable  of dealing with  Shugart SA-4004
and SA-4008 disk drives, interfaced through a Shugart  controller card.
The TFSDiskModel procedure has been changed appropriately.

Note: This  version of  the software must  be compiled  with the  OS 18
system definitions files (Disks.d, etc.), but may be operated  under OS
releases as old as OS 16.