99/4A DISK PERIPHERAL SOFTWARE SUB-PROGRAMS
The following was published in TILines in the 1980s, and is a combination of data from various manuals and my own inputs. -[Colin Hinson]
Apologies for the layout and tables, one day I will find the time to fix the layout in html and fix the tables in html instead of relying on Courier font.
DISK PERIPHERAL D.S.R. SUB-PROGRAMS.
--------------------------------------
Level 1 Subroutines.
The lowest routines in the disk DSR are called level 1 subroutines.
These routines make the higher levels independent of the physical disk
medium, e.g. changing the disk software for a double density disk would
only involve changing the routines on this level provided the physical
sector size remains at 256 bytes.
There are two Sub-programs available on this level:
1. Sector Read/Write
2. Format disk.
The following paragraphs contain a description of the subprograms
and their call requirements. All parameters are transferred through the
FAC block in CPU ram. This block is located at a relative position of
>4A (which for the 99/4a is >834A).
All the subprograms are called by a 'BLWP @DSRLNK' followed by a
data statement: 'DATA >A'. (Note that the Editor Assembler manual is
WRONG - it gives >10 for the data on the third line of the first
paragraph on page 262). Before calling any of the subprograms, location
>8356 (name length pointer) must be set up to point at the location in
VRAM where the name length and the subprogram number have been written.
e.g. If subprogram >14 is called then a location in VRAM (say >1000)
must contain 2 bytes, the first of which is >01 (the name length), and
the second of which is the subprogram number >14. Location >8356 in CPU
RAM points to the first of these bytes - i.e. contains >1000.
Error codes are returned in >8350
SECTOR READ/WRITE - SUBPROGRAM >10
----------------------------------
The transfer block for this subprogram is:
+---------------------------+
>834A | (Sector number) |
+---------------------------+
>834C | Unit # | READ/WRITE |
+---------------------------+
>834E | VDP Buffer start address |
+---------------------------+
>8350 | Sector number |
+---------------------------+
The meaning of each entry is:
Unit Number: - Indicates the disk drive on which the operation is to
be performed. For a T.I. controller, this has to be
either 1, 2, or 3.
READ/WRITE - Indicates the direction of data flow:
0 = WRITE
NOT 0 = READ
VDP buffer start address. - Indicates the start of VDP buffer for
data transfer. The number of bytes transferred will
always be 256.
Sector number - Number of the sector to be written or read. Sectors
are addressed as logical sectors (0-359 for a single
sided single density disk), rather than as a track
and sector number, which would require a knowledge
of the physical layout of the floppy disk. The
sector number has to be given in CPU ram locations
>8350 and >8351, and will be returned in CPU ram
locations >834A and >834B.
DISK FORMATTING - SUBPROGRAM >11
--------------------------------
The transfer block for this subprogram is:
+---------------------------+
>834A | (# of sectors/disk) |
+---------------------------+
>834C |DSR Ver|Unit #| # of tracks|
+---------------------------+
>834E | VDP Buffer start address |
+---------------------------+
>8350 | Density | # of sides |
+---------------------------+
The meaning of each entry is:
# of sectors/disk - Is returned by the routine to provide compatibility
between the normal controller and double density or SA200
systems.
DSR Version (This is the MS nibble)
0 indicates the format requires nothing special and can be done
on any version of the DSR.
1 indicates the format requires the 2nd version of the DSR for
one of two reasons. It may be because a double sided format
is requested, or it may be because a # of sectors other than
35 or 40 is requested (but see below!).
Unit Number: - Indicates the disk drive on which the operation is to
be performed. For a T.I. controller, this has to be either
1, 2, or 3. This is the LS nibble.
# of tracks - Indicates the number of tracks to be formatted. In the
only versions released, this entry has to be either 35 or
40!!! Upon return, this entry contains the number of sectors
per track.
VDP buffer start address - Indicates the start address of the VDP
buffer that can be used by the disk controller to write tracks.
The amount of memory used depneds on the disk format. For a
single density format, the buffer memory used is a nominal 3125
bytes. This can vary with disk motor speed to a maximum of
3300 bytes. To be compatible with double density versions of
the controller (such as MYARC), the minimum buffer size must
be 8K bytes.
Density - 0 = single
# of sides - Indicates the number of sides to format.
The above subprogram will format the entire disk on the given unit
unless the disk in the unit has been hardware write protected. It can
use any VDP memory starting at the location given in the transfer block.
---------------------
LEVEL 2 SUBROUTINES
-------------------
The Level 2 subroutines use the "file" concept, rather than the
"logical sector number". Note that the file concept on this level is
limited to an abstract type of file which has NO properties such as
"program file" or "data file". A file on this level is merely a
collection of data, stored in logical blocks of 256 bytes each.
The logical blocks on this level are accessed by filename and
logical block offset. This offset starts with block 0 and ends with
block N-1 for a file with a length of N blocks.
MODIFY FILE PROTECTION - SUBPROGRAM >12
---------------------------------------
The transfer block for this subprogram is:
+---------------------------+
>834C | UNIT # | Protect code |
+---------------------------+
>834E | Pointer to file name |
+---------------------------+
The protect bit for the indicated file will be set or
reset according to the information given in CPU ram location >4D:
0 -Reset the file protect bit. The file is no longer protected
against modification or deletion.
1 -Set the file protect bit. Disallow SAVE and OPEN for
OUTPUT, APPEND, or UPDATE mode.
The pointer to the file name must point to the VDP ram location
of the first character of the file name. The name must be left
adjusted in a 10 character field, right filled with spaces. No
checks are made to ensure the legality of the file name.
FILE RENAME ROUTINE - SUBPROGRAM >13
---------------------------------------
The transfer block for this subprogram is:
+---------------------------+
>834C | UNIT # | Unused |
+---------------------------+
>834E | Pointer to new name |
+---------------------------+
>8350 | Pointer to old name |
+---------------------------+
Both pointers to the file names must point to the VDP ram
location of the first character of a file name. Each name must be
left adjusted in a 10 character field, right filled with spaces.
No checks are made to ensure the legality of the file names.
Since the rename has to be done on the same disk, only one unit
number entry is required.
Error codes are returned, as usual, at location >8350. The error
codes returned are identical to the standard file management error
codes, i.e. only the upper three bits of the error byte are significant.
BUFFER ALLOCATION ROUTINE - SUBPROGRAM >16
------------------------------------------
The transfer block for this subprogram is:
+---------------------------+
>834C | ZERO |
+---------------------------+
>834E | # of files | ZERO |
+---------------------------+
>8350 | ZERO |
+---------------------------+
The "argument" for this subprogram is the number of file buffers to
be allocated. Whilst it is not actually necessary to clear >834C, &
>8350, experience has shown that strange results sometimes occur if you
don't.
The effect of this routine is that an attempt is made to allocate
enough VDP ram space for disk usage to facilitate the simultaneous
opening of the given nuumber of files. This number has to be between 1
and 16.
The disk software automatically relocates all buffer areas that
have been linked in the following manner (see also previous article on
VDP ram allocation):
Byte 1 - Validation code
Bytes 2 & 3 Top of memory before allocation of this buffer.
Byte 4 High byte of CRU address for given buffer area. For
programs this byte is 0.
The linkage to the first buffer area is made through the current
top of memory, given in CPU ram location >8370.
The top of memory is also automatically updated after successful
completion of this subprogram.
A check is made that the current request leaves at least >800 bytes
of VDP ram space for screen and data storage. If this is not the case,
or if the total number of buffers is zero or greater than 16, the
request is ignored and an error code will be indicated in CPU ram
location >8350.
Successful completion is indicated by a 0 byte in CPU ram location
>8350. A non-zero byte indicates unsuccessful completion.
T.I. 99/4A DISK PERIPHERAL - SUBPROGRAMS (CONTINUED)
DIRECT FILE ACCESS ROUTINES.
The direct file access routines can be used for accessing disc
files without paying attention to the type of disc file (PROGRAM or
DATA). The level of access is equivalent to the Level 2 disk software,
which means that access is performed on the basis of straight AUs.
However, Level 3 information can be passed at file open time.
Since the input and output direct access subprograms can be used
together to copy files, the usedr has to be very careful with the
information returned by the input file subprogram, since some of this
information may be used by the output file subprogram.
Direct File Input - Subprogram >14
----------------------------------
The transfer block for the subprogram is:
+-----------------------------+
>834C | Unit # | Access code |
+-----------------------------+
>834E | Pointer to file name |
+-----------------------------+
>8350 (X) | Addt'l info |
+--------------+
The meaning of each entry is:
Unit # - Indicates the disk drive on which the operation is to be
performed. This entry has to be either 1, 2, or 3.
Access code - An access code is used to indicate which function is
to be performed, since this subprogram combines multiple
functions. The following codes are used:
0 Transfer file parameters. This will transfer Level 2
parameters to the additional information area (six
bytes). It also passes the number of AUs allocated
for the file.
N When N is not equal to zero, this indicates the number
of AUs to be read from the given file, starting at
the AU indicated in the additional information block.
After the READ is complete, this entry contains the
actual number of AUs read. If all AUs have been read
the entry will be zero.
Pointer to file name. - Contains a pointer to the first character
of a 10 character filename, possibly padded to the right
with spaces. The filename is NOT checked by the disc
software.
Additional information - Points to a 10 bytes location in CPU ram
containing additional information for direct disc access:
+-----------------------------+
X | VDP Buffer Start Address |
+-----------------------------+
X+2 | # of first AU |
+-----------------------------+
X+4 | Status flags | # records/AU |
+-----------------------------+
X+6 | EOF offset | log. rec Size|
+-----------------------------+
X+8 | # of Level 3 rec's allocated|
+-----------------------------+
The VDP Buffer start address indicates where the information read
from the disc can be stored. The buffer has to be able to
store at least N * 256 bytes, in which N is the access code.
The # of first AU entry indicates the AU number at which the read
should begin. If the access code = 0 (parameter passing),
the total number of AUs allocated for the file will be
returned.
The remaining six bytes are explained in a previous article giving
information about the the File Descriptor records (Sector 1
on the disc).
The user must be very careful when changing these bytes,
since they directly affect Level 3 operation. If the
information in these 6 bytes is not modified consistently
then unpredictable results may (WILL if you don't want them
to!) occur.
Error codes are returned at location >8350 in CPU RAM
Direct File Output - Subprogram >15
----------------------------------
The transfer block for the subprogram is:
+-----------------------------+
>834C | Unit # | Access code |
+-----------------------------+
>834E | Pointer to file name |
+-----------------------------+
>8350 (X) | Addt'l info |
+--------------+
The meaning of each entry is:
Unit # - Indicates the disk drive on which the operation is to be
performed. This entry has to be either 1, 2, or 3.
Access code - An access code is used to indicate which function is
to be performed, since this subprogram combines multiple
functions. The following codes are used:
0 Create file and copy Level 3 parameters from the
additional information area.
N When N is not equal to zero, this indicates the number
corrupted disc sector - sorry guys
1
«™Јy)»“KЈЈ+qЈyЈC);Kі+q3Kc)a›Ј “ЈKs9 ўQЈC)
©Ks#K Ј+!KqЈC) ##KЈK{s aKs3{“k ЈK{qc{
rAѓ{KsЈ+‘Јy3Kc)s k)qi{sЈ Ks™ ѓ{KsЈ+‘ЈyЈC)3K“›ЎC “ Ј+—щб ##Ў;aKs3
зщiiii_щiiH of a 10 character filename, possibly padded to the rightE with spaces. The f
lename is NOT checked by the disc software.H Additional information - Points to a 1
bytes location in CPU ramя--+я-------+яI
containing additional inormation for direct disc access: 2 +-----------------------------+2 X
| VDP Buffer Start Address |2
+-------------
---------------+яion in CPU ramя--+я-------+я
X+2 | # of first AU |
+-----------------------------+
X+4 | Status flags | # records/AU |
+-----------------------------+
X+6 | EOF offset | log. rec Size|
+-----------------------------+
X+8 | # of Level 3 rec's allocated|
+-----------------------------+
The VDP Buffer start address indicates where the information to be
written to the disc is stored. The buffer must of course
contain at least N * 256 bytes, in which N is the access code.
The # of first AU entry indicates the AU number at which the write
should begin. If the access code = 0 (parameter passing),
the total number of AUs allocated for the file has to be
indicated. (automatically passed if a read has been done
first).
The remaining six bytes are explained in a previous article giving
information about the the File Descriptor records (Sector 1
on the disc).
The user must be very careful when changing these bytes,
since they directly affect Level 3 operation. If the
information in these 6 bytes is not modified consistently
then unpredictable results may (WILL if you don't want them
to!) occur.
Error codes are returned at location >8350 in CPU RAM
---------------------------------
This is the end of this series of articles which I hope have been
of use to someone out there. As I have had no feedback of any kind I
assume they have been acceptable. I have tried to cover things
concerning the disc system which do not appear in the Editor/Assembler
manual, so if you are starting from scratch, read that first - it covers
PABs etc fully.
Colin Hinson
Donations for the upkeep of these pages :
If you have any comments, complaints, suggestions, requests, links that don't work etc, please drop me a line via my Genuki email page.
If you want to know when the page changes, try a change tracker such as PageCrawl.io