Interface DeviceDriver
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 TypeMethodDescriptionvoid
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.String[]
getNames()
Gets the names of the native directories/files used for each drive of the device.int
getUsage()
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
setCpu
(MC68000Cpu cpu) 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
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 returntrue
, 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
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, elsefalse
.
-
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
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 filetrapKey
- 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
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.
-