VMB Hostdisk Device Specification

Host-Disk Device Specification

Memory Layout

Byte | Mode | Name | Description
00-03 | R | Status | Status register, is negativ if an error occured, 0 if idle, 1 if bussy.
04-07 | RW | Control | Controll register, write to initiate disk operations
08-0F | RW | Handle | Handle for the current operation
10-17 | R | Mode | Mode parameter
18-1F | RW | Position | Position parameter
20-27 | RW | DMA0.address | physical address of first buffer where the next transfer takes place
28-2F | RW | DMA0.size | size of first buffer where the next transfer takes place
... | RW | DMA1-14 | more DMA address and size registers
110-117 | RW | DMAf.address | physical address of 16th and last buffer where the next transfer takes place
118-11F | RW | DMAf.size | size of 16th and last buffer where the next transfer takes place

Operation Summary

The program will contact the motherboard at [host:]port and register itself with the given address and interrupt.

The disk simulates a kind of disk controller but is using the host file system.

The disk understands the following commands:

  • open a file
  • close a file
  • read data from a file
  • write data to a file
  • position the file (seek)
  • get the file position (tell)

Registers

Status Register

The status register is read only. Only two bit are significant, the first and the last.

  • The sign bit is set if any error prevented the successful completion of the last command. It makes the value in this register negative.
  • 0x01 BUSSY the lest significant bit is set by the hardware during command execution. When the command is completed (or cannot be completed due to an error), BUSSY is reset to zero. Comand completion also raises the disk interrupt if it is enabled.

Tesing the status register, there are three typical values: negative means error, 1 meand bussy, 0 means idle.

Control Register

The 2 low order bits of the control register are used to control the disk. These bits are from low order to high order:

  • 0x01 - GO As soon as a 1 is written to this bit, the next command is carried out.
  • 0x02 - IEN Enables (1) or disables (0) interrupts from the disk.

The next 6 bits of the control register contain the operation code. These are the following:

  • 1 (0x04) - Open a file
  • 2 (0x08) - Close a file
  • 3 (0x0C) - Read from a file
  • 4 (0x10) - Write to a file
  • 5 (0x14) - Seek
  • 6 (0x18)- Tell

Handle Register

Files are identified by Handles. A Handle is a one byte unsigned value. Al l operations have a handle as a parameter and it is stored in the low byte of this register.

Mode Register

The mode parameter of the open command is stored in the low byte of this register. See the open comand below for details.

Position Register

The position parameter of the seek command and the result of the tell command is stored here. See the commands for details.

DMA Registers

The memory buffers from where data is read in a write-to-disk operation or to where data is written in a read-from-disk operation is determined by the contents of the 16 DMA registers. Each DMA register consists of an address and a size register. It holds the physical address of the buffer and its size. Several buffers can be used in a scatter or gather IO operation. This means that the IO operations view the content of the 16 DMA buffers as one consecutive data area, as if the buffers would have been concatenated. For example a write operation will gather its data first from buffer number one then from buffer number two, and so forth until all the buffers are all written (or some error has occured). A read operation will scatter the data read from disk by filling the first buffer and then the second, until all buffers are filled or the end of the file has been reached.

Commands

In the following, each command is expalined. In general the commands are mapped to the file operations from the C Library: fopen, fclose, fread, fwrite, fseek, ftell. If the corresponding call from the C library fails, the error bit in the status register is set.

Open

This command has three parameters, the handle, the mode, and the filename. Handle and mode must be set in the respective registers. The address of the filename and its length must be given using the first DMA register. The given filename will be concatenated with the configured root directory to form a host filename. Then this host file is opened and associated with the given handle. It is an error to use a handle that is already associated with an open file. You must close the file before you can reuse the handle.

The mode can be a combination of

  • 0x01 - READ
  • 0x02 - WRITE
  • 0x04 - BINARY
  • 0x08 - APPEND

Not all combinations are, however possible. Vallid combinations and their corresponding mode strings of the UNIX fopen function are:

Value | Mode Bits | Mode String
1 | READ | rt
2 | WRITE | wt
3 | READ|WRITE | r+t
5 | READ|BINARY | rb
6 | WRITE|BINARY | wb
7 | READ|WRITE|BINARY | r+b
10 | WRITE|APPEND | at
11 | READ|WRITE|APPEND | a+t
14 | WRITE|BINARY|APPEND | ab
15 | READ|WRITE|BINARY|APPEND | a+b

Close

This command has just one parameter, the handle. The handle must have been opened before with the open command.

Read

This command needs a handle and at least one of the DMA registers. When the command has completed, the size values in the DMA registers reflect the anount of data actually read.

Write

The command needs a handle and at least one of the DMA registers. When the command has completed, the size values in the DMA registers reflect the anount of data actually written.

Seek

The command needs a handle and a position parameter specifying the location of the next read or write operation. If the command is successful. the new location will be determined as follows:

  • If the position parameter is positive or zero, the new location is position bytes after the begin of the file.
  • If the position parameter is negative, the new location is -position-1 bytes before the end of the file.

Tell

The command needs a handle and sets the position register to the current file position measured in bytes from the beginning of the file.

Configuration

The host-disk has the following configurable parameters:
host | localhost | the host where the bus is located
port | 9002 | the port where the bus is located
address | default | address where the resource is located
interrupt | not set | interrupt sent when operation has completed
file | not set | Name of the directory where the root is located
x | 0 | the x position of the window
y | 0 | the y position of the window
minimized | false | start with a minimized window
debug | false | to generate debug output
debugmask | 0xFFF0 | set mask to hide debug output
verbose | false | make debugging verbose, sets debug mask to zero
define | not set | to define a name for conditionals
config | not set | filename for a configuration file
help | false | to print information

These can be set in default.vmb