NAME

intro − general characteristics of standalone device drivers

SYNOPSIS

{
"name",init_routine,open_routine,
strat_routine,close_routine,ioctl_routine,
type_flags,
fs_type,"description"
}

DESCRIPTION

New devices are incorporated into the standalone library by writing a device driver and making a new entry to the configuration structure _device_table in saio/conf.c.  The format of a configuration table is shown above.  The fields of a configuration entry are:

name A character string by which the device is to be recognized.  "Name" is used in the context:
name(controller,unit,partition)path
Controller, unit, and partition are all passed to the device driver indicated by name via a struct iob.  Path is passed to file system or protocol code which may be layered on top of the raw device, see fs_type field. 

init_routine()
The init_routine is called when a program utilizing the standalone library is first invoked.  Its main purpose is to initialize global data of the driver; it generally does not affect the device itself.

open_routine(iop)
The open routine is called when an open(3spp) request is made on the device.  The open routine is passed a pointer to a structiob.  The open routine validates the parameters passed in the iob and initializes the device. 

strat_routine(iop, func)
The strategy routine is called when a read(3spp) or write(3spp) request is made on a descriptor open on the device. The strategy routine is passed a pointer to a struct iob and the parameter func which indicates whether a read or write is requested.  The strategy routine accomplishes the read or write operation as indicated by func and the parameters in the iob. 

close_routine(iop)
The close routine is called when a close(3spp) request is made on a descriptor open on the device.  The close routine is passed a pointer to a struct iob and is responsible for performing any "clean-up" activities necessary after i/o has completed on the device. 

ioctl_routine(iop, cmd, arg)
The ioctl routine is called when a ioctl(3spp) request is made on a descriptor open on the device.  The ioctl routine is passed a pointer to a struct iob and is responsible for carrying out the ioctl request indicated by cmd. Arg is passed to the ioctl unaltered from the value given on the user ioctl request; it’s interpretation is a function of the particular ioctl command. 

type_flags
The type flags may be or’ed together from the following possibilities:

DTTYPE_CHAR
The device is not block structured and may transfer information in arbitrary sized requests.  Excludes DTTYPE_BLOCK.

DTTYPE_BLOCK
The device is block structured and must transfer information in DEV_BSIZE (currently 512 byte) units.  Addressing on the device is restricted to multiples of DEV_BSIZE units.  Reads, writes, and lseeks on the raw version of these devices must follow these restrictions, most file systems layered on top of these devices buffer transfers and eliminate this restriction; see SPP manual section 5. 

DTTYPE_CONS
The device may be enable’ed(1spp) as a console device.  Console devices must be DTTYPE_CHAR devices. 

DTTYPE_RAW
The device always uses the file system routines for access even if no path component is specified when the file is open’ed. Normally, if layered file system is not used if no path component is specified; see fs_type field description.

fs_type
References to a raw device may have file system or protocol code layered between the user’s requests and requests of the device driver by specifying a file system type in this field.  Normally, the file system routines interpret the path component of the device specification and make suitable requests on the device driver entry points declared above.  Currently, the following file system types are supported:

DTFS_NONE -- no file systems, path component is illegal
DTFS_BFS -- boot file server protocol
DTFS_DVH -- disk volume header file system
DTFS_TPD -- tape directory file system
DTFS_NCP -- network console, not implemented
DTFS_BSD42 -- 4.2 and 4.3 BSD UNIX file systems
DTFS_SYSV -- System V file system
DTFS_AUTO -- file system type determined by driver open routine

If DTFS_AUTO is specified, the device driver open routine may system type after possibly reading information from the device. 

REGISTERS

The device drivers included with the standalone library have hardwired 1 or 2 base addresses for each device type.  These are described in this section. 

IOCTLS

The following ioctl’s are common to certain classes of devices:

ioctl(fd, TIOCPROTO, arg)

This ioctl applies to all devices which are declared as type DTTYPE_CONS.  If arg is non-zero, this ioctl declares that the device associated with descriptor fd is currently be used by a download protocol and should temporarily be disabled as an enabled console.  If arg is zero, the device should be re-instated as a console device. 

ioctl(fd, FIOCNBLOCK, arg)

This ioctl applies to all devices which may block waiting for input; e.g.  console, tty, and udp. For these devices, reads will not block until the requested amount of input has been satisfied, but will return only the amount immediately available.  The number of bytes read will be returned by the read(3spp) request; this may be zero if no input is currently available.

DIAGNOSTICS

The following diagnostics are common to all devices:

can’t open console(0) for input/output
This diagnostic indicates either an error in configuring the standalone i/o package or hardware failure.

out of io buffers
Too many files requiring buffers (generally those which need file system support) were opened.

iob_buf screwup
Internal error was detected in the allocation of i/o block buffers.

couldn’t determine fs type
The open routine for a device did not change a file system type from DTFS_AUTO.

file system type not supported
A file system type was specified by a configuration entry or a DTFS_AUTO open that is not configured in the standalone library.

no file system
A path component was specified for a device that does not sup