unit xbios

xBios handlers

author: bocianu bocianu@gmail.com


Handful of useful procedures to fiddle with Atari IO (disk) using xBios. For more informations about xBios - look here: https://xxl.atari.pl/.
Known limitations of xBios:
- New files cannot be created.
- Existing files cannot be extended in length.
- New directories cannot be created programatically.

This library is a part of 'blibs' - set of custom Mad-Pascal libraries.
https://gitlab.com/bocianu/blibs

Constants:

name:value:description:
xBIOS_ADDRESS$800Change this value if you are using xbios at non-default location
xBIOS_VERSIONxBIOS_ADDRESS + $02location of version number in memory
xBIOS_RENAME_ENTRYxBIOS_ADDRESS + $03original xBios procedures vectors
xBIOS_LOAD_FILExBIOS_ADDRESS + $06
xBIOS_OPEN_FILExBIOS_ADDRESS + $09
xBIOS_LOAD_DATAxBIOS_ADDRESS + $0c
xBIOS_WRITE_DATAxBIOS_ADDRESS + $0f
xBIOS_OPEN_CURRENT_DIRxBIOS_ADDRESS + $12
xBIOS_GET_BYTExBIOS_ADDRESS + $15
xBIOS_PUT_BYTExBIOS_ADDRESS + $18
xBIOS_FLUSH_BUFFERxBIOS_ADDRESS + $1b
xBIOS_SET_LENGTHxBIOS_ADDRESS + $1e
xBIOS_SET_INIADxBIOS_ADDRESS + $21
xBIOS_SET_FILE_OFFSETxBIOS_ADDRESS + $24
xBIOS_SET_RUNADxBIOS_ADDRESS + $27
xBIOS_SET_DEFAULT_DEVICExBIOS_ADDRESS + $2a
xBIOS_OPEN_DIRxBIOS_ADDRESS + $2d
xBIOS_LOAD_BINARY_FILExBIOS_ADDRESS + $30
xBIOS_OPEN_DEFAULT_DIRxBIOS_ADDRESS + $33
xBIOS_SET_DEVICExBIOS_ADDRESS + $36
xBIOS_RELOCATE_BUFFERxBIOS_ADDRESS + $39
xBIOS_GET_ENTRYxBIOS_ADDRESS + $3c
xBIOS_OPEN_DEFAULT_FILExBIOS_ADDRESS + $3f
xBIOS_READ_SECTORxBIOS_ADDRESS + $42
xBIOS_FIND_ENTRYxBIOS_ADDRESS + $45
xBIOS_SET_BUFFER_SIZExBIOS_ADDRESS + $48

Types:

name:type:description:
TxBiosConfigrecord
  • version: byte; // upper nibble is major version number, lower is lower ;)
  • autorun: array [0..10] of char; // name of autorun file (default 'XAUTORUN')
  • xBiosAddress: byte; // MSB of xBios memory address (default $800)
  • bufferAddress: byte; // MSB of buffer memory address (default $700)
  • initAd: word; // INITAD vector address (default $02e2)
  • runAd: word; // RUNAD vector address (default $02e0)
  • aosv: word; // I/O module adress (at run AtariOS; default xSIOV)
  • aosv_reloc: word; // relocate AtariOS I/O module variables
  • portb: byte; // PORTB value at start (default $ff)
  • nmien: byte; // NMIEN value at start (default $40)
  • irqen: byte; // IRQEN value at start (default $c0)

end;
Structured type used to store and represent xBios configuration file.

Register Variables:

name:address:type:description:
xDIRSIZExBIOS_ADDRESS + $3e5bytecurrent directory size in sectors (1 byte)
xSPEEDxBIOS_ADDRESS + $3e6byteSTD SPEED
xHSPEEDxBIOS_ADDRESS + $3e7byteULTRA SPEED
xIRQENxBIOS_ADDRESS + $3e8byteUser IRQ (1 byte)
xAUDCTLxBIOS_ADDRESS + $3e9byteAUDCTL
xFILExBIOS_ADDRESS + $3eawordFile handle (2 bytes)
xDIRxBIOS_ADDRESS + $3ecwordRoot directory handle (2 bytes)
xIOVxBIOS_ADDRESS + $3eewordI/O module entry (2 bytes)
xBUFFERHxBIOS_ADDRESS + $3f0byteBuffer adr hi byte (1 byte)
xBUFSIZExBIOS_ADDRESS + $3f1byteBuffer size lo byte $100-SIZE (1 byte)
xDAUX3xBIOS_ADDRESS + $3f2byteBuffer offset (1 byte)
xSEGMENTxBIOS_ADDRESS + $3f3wordBytes to go in binary file segment (2 bytes)
xNOTExBIOS_ADDRESS + $3f5wordFile pointer (2 lower bytes)
xNOTEHxBIOS_ADDRESS + $3f7byteFile pointer (highest byte)
xDEVICExBIOS_ADDRESS + $3fcbyteDevice ID
xDCMDxBIOS_ADDRESS + $3fdbyteCMD (1 byte)
xDAUX1xBIOS_ADDRESS + $3febyteSector lo byte (1 byte)
xDAUX2xBIOS_ADDRESS + $3ffbyteSector hi byte (1 byte)

Global Variables:

name:type:description:
xBiosIOresultbyte = 0contains result of last IO operation ( 0 = OK, 1 = KO )
xBiosIOerrorbyte = 0contains register X value after last error (for debuging purposes)
xBiosDirEntryIndexbyte = 0contains index of last directory entry, after using xBiosFindEntry or xBiosGetEntry
xBiosDirEntryStatusbyte = 0contains status of last directory entry, after using xBiosGetEntry
xBiosDirEntrySectorword = 0contains starting sector of found directory entry, after using xBiosFindEntry

Interface:

name:description:
xBiosCheck

function xBiosCheck:byte;


Checks for the presence of xBios in memory. Looks at address defined as xBiosAddress.
    returns:
  • (byte) - returns 0 for no xBios loaded,if xBios is present - returns two nibbles of xBios version
xBiosRenameEntry

procedure xBiosRenameEntry(var filename:TString); assembler;


This function allows you to rename a file or directory. There is no limit to the characters used in the filename apart from that they must fit a case insensitive “8.3” format without the dot. If your filename is not 8 characters long, pad it out with spaces.
    parameters:
  • filename - string containing both names, source and destination, padded with spaces.Must be 22 characters long.
    example: filename := 'INFILE TXTOUTFILE TXT';
xBiosLoadFile

procedure xBiosLoadFile(var filename:TString); assembler;


Loads and runs the file, INIT and RUN headers are supported. In the case the file does not have a defined block RUN will be launched from the beginning of the first block.
    parameters:
  • filename - string containing file name (8.3 format without dot) padded with spaces.Must be 11 characters long.
    example: filename := 'INFILE TXT';
xBiosOpenFile

procedure xBiosOpenFile(var filename:TString); assembler;


Opens a file in order to carry out subsequent IO operations.
    parameters:
  • filename - string containing file name (8.3 format without dot) padded with spaces.Must be 11 characters long.
    example: filename := 'INFILE TXT';
xBiosLoadData

procedure xBiosLoadData(dest: pointer); assembler;


Loads data from file to a specified destination address. You can set the file offset (xBiosSetFileOffset) and the amount of data to be loaded (xBiosSetLength). If you do not define these values, data will be loaded from the current position of the file pointer to the end of the file.
    parameters:
  • dest - data destination pointer.
xBiosLoadLz4Data

procedure xBiosLoadLz4Data(dest: pointer); assembler;


Loads and decompres data from compressed lz4 file to a specified destination address. Based on xxl & fox routine from here: https://xxl.atari.pl/lz4-decompressor/
    parameters:
  • dest - data destination pointer.
xBiosWriteData

procedure xBiosWriteData(src: pointer); assembler;


Saves data from memory to a file, starting from the current position in the file. You can set the file pointer offset current (xBiosSetFileOffset) and the amount of data to be saved (xBiosSetLength). If you do not define these values, data from the current file position to the end of the file is written to the file.
    parameters:
  • src - pointer to source of data.
xBiosOpenCurrentDir

procedure xBiosOpenCurrentDir; assembler;


Opens the current directory.
    xBiosGetByte

    function xBiosGetByte:byte; assembler;


    Reads one byte from opened file.
      returns:
    • (byte) - byte readed from file
    xBiosPutByte

    procedure xBiosPutByte(b:byte); assembler;


    Writes one byte into opened file.
      parameters:
    • b - byte to be written into file
    xBiosFlushBuffer

    procedure xBiosFlushBuffer; assembler;


    All write operations are cached, use this to flush the buffer to the current file.
      xBiosSetLength

      procedure xBiosSetLength(len: word); assembler;


      Defines the amount of data to process while reading or writing.
        parameters:
      • len - amount of data
      xBiosSetInitAd

      procedure xBiosSetInitAd(adr: word); assembler;


      Allows you to change the init address vector INITAD ($2E2) for loaded binary files.
        parameters:
      • adr - new address vector for INITAD
      xBiosSetFileOffset

      procedure xBiosSetFileOffset(pos: cardinal); assembler;


      Sets the current read/write position in the current file with a value stored in parameter. This item is calculated relative to the beginning of the file. In DOS speak, the operation is called "POINT". You can only move this pointer forward.
        parameters:
      • pos - new position in the current file
      xBiosSetRunAd

      procedure xBiosSetRunAd(adr: word); assembler;


      Allows you to change the run address vector RUNAD ($2E0) for loaded binary files.
        parameters:
      • adr - new address vector for RUNAD
      xBiosSetDefaultDevice

      procedure xBiosSetDefaultDevice; assembler;


      Restores the standard IO device.
        xBiosOpenDir

        procedure xBiosOpenDir(var filename:TString); assembler;


        Allows you to change the current directory.
          parameters:
        • filename - string containing directory name (8.3 format without dot) padded with spaces.Must be 11 characters long.
          example: filename := 'SUBDIR ';
        xBiosLoadBinaryFile

        procedure xBiosLoadBinaryFile; assembler;


        Loads and runs the binary file from the current read/write position. INIT and RUN headers are supported.
          xBiosOpenDefaultDir

          procedure xBiosOpenDefaultDir; assembler;


          Opens the default directory.
            xBiosSetDevice

            procedure xBiosSetDevice(dev: word); assembler;


            Changes the IO device.
              parameters:
            • dev - device address
            xBiosRelocateBuffer

            procedure xBiosRelocateBuffer(adr: word;c:byte); assembler;


            Changes address of IO buffer. If c = 1, the relocation can be carried out even during IO. The data will not be lost. If c = 0, buffer contents will not be copied to a new location.
              parameters:
            • adr - new buffer address
            • c - dynamic relocation flag
            xBiosGetEntry

            procedure xBiosGetEntry; assembler;


            Gets another entry in the directory. The xBiosDirEntryIndex returns the index to the filename or folder (byte of buffer address is stored in the variable xBUFFERH). The xBiosDirEntryStatus is set with the status. The xBiosIOresult is set to 1 when the end of the directory is found.
              xBiosOpenDefaultFile

              procedure xBiosOpenDefaultFile; assembler;


              Opens the default file. The function does not search the directory, the file handle is derived from the variable 'xFILE'.
                xBiosReadSector

                procedure xBiosReadSector(sector: word); assembler;


                Loads an sector into a buffer.
                  parameters:
                • sector - sector number
                xBiosFindEntry

                procedure xBiosFindEntry(var filename:TString); assembler;


                This function allows you to find the specified directory entry. The xBiosDirEntryIndex returns the index to the filename or folder (byte of buffer address is stored in the variable xBUFFERH). The xBiosDirEntrySector returns starting sector number of found entry. If an entry is not found, the xBiosIOresult is set to 1.
                  parameters:
                • filename - string containing file name (8.3 format without dot) padded with spaces.Must be 11 characters long.
                  example: filename := 'INFILE TXT';
                xBiosSetBufferSize

                procedure xBiosSetBufferSize(size: byte); assembler;


                This feature allows you to set the buffer size for IO operations. Buffer Size is also stored in the variable xBUFSIZE in bytes format.
                  DosGetEntryName

                  function DosGetEntryName:TString;


                  Reads and returns last directory entry name. Can be invoked only after xBiosGetEntry or xBiosFindEntry.
                    returns:
                  • (string) - returns last directory entry name
                  DosReadEntryName

                  procedure DosReadEntryName(ptr: pointer);overload;


                  Reads and stores last directory entry name at provided memory address. Can be invoked only after xBiosGetEntry or xBiosFindEntry.
                    parameters:
                  • ptr - pointer to memory location where entry name should be stored.
                  DosReadEntryName

                  procedure DosReadEntryName(var s: TString);overload;


                  Reads and stores last directory entry name in string provided. Can be invoked only after xBiosGetEntry or xBiosFindEntry.
                    parameters:
                  • s - string where entry name should be stored.
                  DosHasEntryExt

                  function DosHasEntryExt(ext: TString):boolean;


                  Checks if last entry extension matches extension provided as an parameter.
                    parameters:
                  • ext - string containing file extension (3 characters long).
                  • returns:
                  • (boolean) - returns true if extension matches param.
                  DosGetEntrySize

                  function DosGetEntrySize:word;


                  Reads and returns last directory entry size (in sectors). Can be invoked only after xBiosGetEntry or xBiosFindEntry.
                    returns:
                  • (word) - returns number of sectors occupied by last directory entry,
                  DosGetEntrySector

                  function DosGetEntrySector:word;


                  Returns first sector occupied by last directory entry. Can be invoked after xBiosGetEntry.
                    returns:
                  • (word) - returns starting sector number of last directory entry,
                  DosGetEntryStatus

                  function DosGetEntryStatus:byte;


                  Reads and returns last directory entry status byte. Can be invoked after xBiosFindEntry.
                    returns:
                  • (byte) - returns status byte of found directory entry
                  DosIsDir

                  function DosIsDir(status: byte):boolean;


                  Interprets directory entry status byte, returning true if entry is an directory.
                    returns:
                  • (boolean) - returns true if status describes directory entry
                  DosIsFile

                  function DosIsFile(status: byte):boolean;


                  Interprets directory entry status byte, returning true if entry is an file.
                    returns:
                  • (boolean) - returns true if status describes file entry
                  DosIsDeleted

                  function DosIsDeleted(status: byte):boolean;


                  Interprets directory entry status byte, returning true if entry has been deleted.
                    returns:
                  • (boolean) - returns true if status describes deleted entry
                  DosIsLocked

                  function DosIsLocked(status: byte):boolean;


                  Interprets directory entry status byte, returning true if entry has been locked.
                    returns:
                  • (boolean) - returns true if status describes locked entry
                  DosIsOpened

                  function DosIsOpened(status: byte):boolean;


                  Interprets directory entry status byte, returning true if entry has been opened for writing.
                    returns:
                  • (boolean) - returns true if status describes opened entry
                  DosFileExists

                  function DosFileExists(var filename:TString):boolean;


                  Checks if file exists in current directory.
                    parameters:
                  • filename - string containing file name (8.3 format without dot) padded with spaces.Must be 11 characters long.
                  • returns:
                  • (boolean) - returns true if file exists
                  DosDirExists

                  function DosDirExists(var filename:TString):boolean;


                  Checks if subdirectory exists in current directory.
                    parameters:
                  • filename - string containing directory name (8.3 format without dot) padded with spaces.Must be 11 characters long.
                  • returns:
                  • (boolean) - returns true if directory exists
                  formatFilename

                  function formatFilename(s:TString; showExt:boolean):TString;


                  Formats xBIOS filenames into common dos, dot separated format.
                    parameters:
                  • s - string containing file name (8.3 format without dot) padded with spaces.
                  • showExt - defines if you want to show file extension in output string
                  • returns:
                  • (string) - returns formated file name with or without extension