Package drivers

Interface DeviceDriver

All Known Implementing Classes:
NfaDriver, SfaDriver, WinDriver, XfaDriver

public interface DeviceDriver
This is the interface template for device drivers.

Device drivers are responsible for handling all file I/O. A device driver must, of course, have a corresponding SMSQE device driver which is correctly linked into SMSQE. The NFA driver shows how this is done.

Device drivers must implement all of the methods set out herein some of which return a boolean value.

These methods MUST set the D0 register to signal success (or not) of the operation. In many cases (notably OPEN), the boolean returned by a method does NOT signal that an I/O operation succeeded (or not), but has some other meaning : See the individual methods for more information on the returned boolean.

ATM, device driver operations will always seem atomic to SMSQE, i.e. when the TRAP call returns, the operation in its entirety will have succeeded (or have failed, but it will ne still be going on). In other words, the timeout for the trap #3 calls is totally ignored. This has the unfortunate side effect that SMSQE will appear to be frozen whilst file i/o takes place.

In keeping with standard SMSQE practice, it is presumed throughout that each device may have 8 drives.

Each device driver must have a deviceID, which consists of one Java int. This device ID must also be the one that the SMSQE driver uses. The deviceID is normally a long word, containing the upper cased three letter word of the device, followed by ASCII 0. Thus, for the NFA driver, this is 0x0x4e464130, which translates to 'NFA0'.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Closes all files opened by all drives of this device driver.
    void
    closeFile(int driveNbr, int fileID)
    This closes an open file.
    boolean
    Check if the device is a (native) directory.
    boolean
    formatMedium(String formatName, inifile.IniFile inifile)
    Formats a medium.
    int
    Gets the device ID for this device, eg.
    getName(int drive)
    Gets the name of the native directory/file used for one drive of the device, or the current usage name of the device.
    Gets the names of the native directories/files used for each drive of the device.
    int
    This gets the usage name of the device.
    boolean
    openFile(int devDriverLinkageBlock, int channelDefinitionBlock, int openType, int driveNumber, byte[] filename, byte[] uncased)
    Opens a file.
    void
    Sets the cpu used by the device driver.
    void
    setFilenameChange(int change)
    Sets whether a filename's case should be changed (0 = unchanged, 1=all upper case, 2=all lower case.
    boolean
    setNames(String[] names, inifile.IniFile inifile, boolean forceRemoval, boolean suppressWarnings)
    Sets the names of the native directories to be used for each drive of the device.
    void
    setUsage(int usage)
    This sets the usage name of the device, eg.
    void
    trap3OK(int driveNumber, int trapKey, int channelDefinitionBlock, int fileNbr)
    Handles trap#3 calls (but should check first whether the trap#3 call is, indeed, for this device).
    void
    writeBack(int driveNbr)
    Writes the drive back to a native file
  • Method Details

    • openFile

      boolean openFile(int devDriverLinkageBlock, int channelDefinitionBlock, int openType, int driveNumber, byte[] filename, byte[] uncased)
      Opens a file.

      If the file is opened OK, D0 in the cpu is set to 0.

      If the file isn't OK, D0 is set to an error code.

      The device must first of all check whether the file is for itself (i.e. for this device). If the file isn't for this device, immediately return false. In that case, the value of register D0 doesn't matter. In all other cases (i.e. the file was, indeed, for this device) always return true, but previously set D0 to signal whether the open routine was successful or not. If the operation succeeds, the Driver should place a word sized file ID at offset 0x1e of the channel definition block (eg. this.cpu.writeMemoryWord(channelDefinitionBlock+0x1e, fileID)), or use any other convenient method to make size it can later identify the file when the file's I/O routines are called.

      Parameters:
      devDriverLinkageBlock - pointer to the SMSQE device driver linkage block (a3).
      channelDefinitionBlock - pointer to the SMSQE channel defintion block (a0).
      openType - which kind of open is requested?
      • 0 - old exclusive (r/w access to an already existing file)
      • 1 - old shared (read only access to an already existing file)
      • 2 - new exclusive (r/w access to a file to be created and which doesn't exist yet)
      • 3 - new overwrite (r/w access to a file to be created, will overwrite any previously existing file of the same name)
      • 4 - open directory
      driveNumber - number of drive on which to open the file.
      filename - the name of the file to open.
      uncased - the name of the file to open in all lower case.
      Returns:
      true if file was opened OK, false if not.
    • closeFile

      void closeFile(int driveNbr, int fileID)
      This closes an open file.
      Parameters:
      driveNbr - the number of the drive (0..7).
      fileID - the fileID.
    • formatMedium

      boolean formatMedium(String formatName, inifile.IniFile inifile)
      Formats a medium. This will probably fail in most cases as, e.g. the NFA driver does not allow formatting.
      Parameters:
      formatName - the name to give to the formatted drive.
      inifile - the ".ini" file object.
      Returns:
      true if deviceID corresponded to this device, false if not.

      This method MUST set the D0 register to signal success (or not) of the operation to SMSQE.

    • setNames

      boolean setNames(String[] names, inifile.IniFile inifile, boolean forceRemoval, boolean suppressWarnings)
      Sets the names of the native directories to be used for each drive of the device.

      In keeping with standard SMSQE practice, it is presumed throughout that each device may have 8 drives.

      Parameters:
      names - an 8 element String array with names for the drives.
      inifile - the initialization object.
      forceRemoval - true if files/drives should removed before being remounted.
      suppressWarnings - if true, don't show missing drives etc warning.
      Returns:
      true if names were set, else false.
    • getNames

      String[] getNames()
      Gets the names of the native directories/files used for each drive of the device.

      In keeping with standard SMSQE practice, it is presumed throughout that each device may have 8 drives.

      Returns:
      An 8 elements string array with the names. Individual elements may be null or empty if the corresponding drive isn't assigned.
    • getName

      String getName(int drive)
      Gets the name of the native directory/file used for one drive of the device, or the current usage name of the device.

      In keeping with standard SMSQE practice, it is presumed throughout that each device may have 8 drives.

      Parameters:
      drive - the drive (from 1 to 8) for which the name is to be obtained, or 0 if the current usage name is to be returned.
      Returns:
      A string with the name or "" if the drive name doesn't exist.
    • trap3OK

      void trap3OK(int driveNumber, int trapKey, int channelDefinitionBlock, int fileNbr)
      Handles trap#3 calls (but should check first whether the trap#3 call is, indeed, for this device).

      All device drivers get called in turn for this operation, until one signals that it has handled the trap call. "Handling" the trap call does not mean that the trap call was completed successfully, it only means that the device driver signals that this trap call concerned a file for which it was,indeed, the appropriate driver.

      Parameters:
      driveNumber - number of drive on which to open the file
      trapKey - what kind of trap #3 is it?
      channelDefinitionBlock - pointer to the SMSQE channel definition block (a0)
      fileNbr - the file number given by the ddd when file was opened (A0+0x1e)
    • setUsage

      void setUsage(int usage)
      This sets the usage name of the device, eg. "NFA_USE WIN"
      Parameters:
      usage - the usage name as an int
    • getUsage

      int getUsage()
      This gets the usage name of the device.
      Returns:
      the usage name as an int.
    • getDeviceID

      int getDeviceID()
      Gets the device ID for this device, eg. SFA0.
      Returns:
      the device ID as int.
    • setFilenameChange

      void setFilenameChange(int change)
      Sets whether a filename's case should be changed (0 = unchanged, 1=all upper case, 2=all lower case.
      Parameters:
      change - 0 = unchanged, 1=all upper case, 2=all lower case.
    • closeAllFiles

      void closeAllFiles()
      Closes all files opened by all drives of this device driver.
    • setCpu

      void setCpu(MC68000Cpu cpu)
      Sets the cpu used by the device driver.
      Parameters:
      cpu - the cpu to be set.
    • writeBack

      void writeBack(int driveNbr)
      Writes the drive back to a native file
      Parameters:
      driveNbr - the drive number (1...8)
    • deviceIsDir

      boolean deviceIsDir()
      Check if the device is a (native) directory.
      Returns:
      true if the device is a (native) directory.