Osprey DOS File Access Device

PRELIMINARY

Version 1.1 -- April 14, 1994

Introduction

This document describes the low level mechanism by which programs running on the Osprey can access files in the host (DOS for now) system's directory structure.

Access to host files is accomplished through a "hardware" device which performs the various file access functions.

For now all data transfers are in binary--any record handling or line terminator fixup must be done by the PDP program. The PDP program is also responsible for dealing with problems resulting from DOS's 8.3 filename limitation. As other host environments are supported, commands will be added to allow the PDP program to determine the filename formats supported by the host.

The device is enabled by adding a line to the Osprey configuration file:

DosDevice = DosDevice [Options]

The following table lists the supported options:

The device interrupt vector can also be programmed at run time through the CSR register.

To control the DSF device, PDP program sets up command and data buffers in memory, then initiates the command by passing the command buffer address to the device and setting the START bit in the device's CSR register. The remainder of this document defines the device registers and command buffer layout.

DOS File Device

All commands to the DSF device follow the same sequence:

1. Fill in the command definition block
2. Fill in the command data block if required
3. Give the address of command definition block to the device
4. Set the START bit the CSR to start the command
5. Wait for the command to complete by polling the CSR or waiting for device to interrupt
6. Check the command block status word for possible errors

Dos File Device Register Definitions

DSF CSR Bit Definitions

DSF Command Block Format

DSF Command Definitions

Command code 0 -- Open DOS File

• File Number:Returned by Host on successful file open
• Parameter:File open mode, see below
• Buffer Addr:Points to zero terminated Host file name to be opened
• Buffer Size:Length of filename, including terminating zero (max 128 bytes)

   

  The device will read in the filename, and attempt to open the file in the appropriate mode. Data buffer may contain any valid Host filename. Upon success, the device will return a file number to be used to reference the file in later commands such read and write data.

  The file open mode parameter contains several fields:

  DSF Open command parameter word fields

  Bit	Function
  0-1	Requested access mode
  2-4	DOS Sharing mode

  The following octal field values are supported:

  Read/Write Access Mode:READ_WRITE0000

  READ_ONLY0001

  WRITE_ONLY0002

  Sharing Mode:COMPATIBILITY0000

  DENY_NONE0004

  DENY_READ0010

  DENY_WRITE0014

  EXCLUSIVE0020

  For now, all data transferred is strictly binary byte-stream; no data formatting is performed by the host. It the future, the open-mode parameter my be also contain re-formatting information.

Command code 1 -- Create DOS File

• File Number:Unused
• Parameter:Unused
• Buffer Addr:Points to zero terminated Host file name to be created
• Buffer Size:Length of filename, including terminating zero (max 128 bytes)

Command code 2 -- Delete DOS File

• File Number:Unused
• Parameter:Unused
• Buffer Addr:Points to zero terminated Host file name to be deleted
• Buffer Size:Length of filename, including terminating zero (max 128 bytes)

Command code 3 -- Read DOS File

• File Number:As returned by the OPEN command
• Parameter:Unused
• Buffer Addr:Address of area to receive the file data
• Buffer Size:Number of bytes requested. Host returns number of bytes actually read; will never be more than requested length. On end of file error status, a the read count returned will be less than the requested count.

Command code 4 -- Write DOS File

• File Number:As returned by the OPEN command
• Parameter:Unused
• Buffer Addr:Address of actual file data buffer
• Buffer Size:Number of bytes to write. Host returns number of bytes actually written.

Command code 5 -- Set File Position

• File Number:As returned by the OPEN command
• Parameter:Position relative to: 0 = Front, 1 = Current position, 2 = End
• Buffer Addr:32 bit signed number. Host returns actual file position
• Buffer Size:Unused

Command code 6 -- Find first matching file

• File Number:Unused
• Parameter:Unused
• Buffer Addr:Points to zero terminated host file name template
• Buffer Size:Length of file name buffer (max 128 bytes)

Command code 7 -- Find next matching file

• File Number:Unused
• Parameter:Unused
• Buffer Addr:Points to buffer to receive next filename
• Buffer Size:Length of file name buffer (max 128 bytes)

  These commands allow scanning of a host directory. The host returns the first/next filename from the directory which matches the input pattern. Only one "first,next,...,next" sequence is valid at a time--i.e. it is not possible to intermix scanning of two host directories.

Command code 8 -- Close DOS file

• File Number:As returned by the OPEN command
• Parameter:Unused
• Buffer Addr:Unused
• Buffer Size:Unused

After each command, the PDP driver code should check the status word to make sure the command completed correctly. The following table defines the current error codes possible from the DSF device:

DSF Device Status Codes