INTRO(4spp) RISC/os Reference Manual INTRO(4spp)
NAME
intro - general characteristics of standalone device drivers
SYNOPSIS
{
"name", initroutine, openroutine,
stratroutine, closeroutine, ioctlroutine,
typeflags,
fstype, "description"
}
DESCRIPTION
New devices are incorporated into the standalone library by
writing a device driver and making a new entry to the confi-
guration structure devicetable 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 fstype 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 rou-
tine is passed a pointer to a struct 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 stra-
tegy 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)
Printed 1/6/92 Page 1
INTRO(4spp) RISC/os Reference Manual INTRO(4spp)
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; its interpretation is
a function of the particular ioctl command.
type_flags The type flags can be or'ed together from the
following possibilities:
DTTYPE_CHAR The device is not block struc-
tured and can transfer infor-
mation in arbitrary sized
requests. Excludes
DTTYPE_BLOCK.
DTTYPE_BLOCK The device is block structured
and must transfer information
in DEVBSIZE (currently 512
byte) units. Addressing on
the device is restricted to
multiples of DEVBSIZE units.
Reads, writes, and lseeks on
the raw version of these dev-
ices must follow these res-
trictions, most file systems
layered on top of these dev-
ices buffer transfers and
eliminate this restriction.
DTTYPE_CONS The device can be enabled as a
console device. Console dev-
ices must be DTTYPECHAR dev-
ices.
DTTYPE_RAW The device always uses the
file system routines for
access even if no path com-
ponent is specified when the
file is opened.
Page 2 Printed 1/6/92
INTRO(4spp) RISC/os Reference Manual INTRO(4spp)
fs_type References to a raw device can have file sys-
tem 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 rou-
tines 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:
DTFSNONE -- no file systems, path component is illegal
DTFSBFS -- boot file server protocol
DTFSDVH -- disk volume header file system
DTFSTP 15D -- tape directory file system
DTFSNCP -- network console, not implemented
DTFSBSD42 -- 4.2 and 4.3 BSD UNIX file systems
DTFSSYSV -- System V file system
DTFSAUTO -- file system type determined by driver open routine
If DTFSAUTO is specified, the device driver open routine
can set the struct iob field ifstype to a particular file
system type after possibly reading information from the dev-
ice.
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 ioctls are common to certain classes of dev-
ices:
ioctl(fd, TIOCPROTO, arg)
This ioctl applies to all devices declared as type
DTTYPECONS. If arg is non-zero, this ioctl declares that
the device associated with descriptor fd is used by a down-
load protocol and must be temporarily 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 that can block whle wait-
ing for input; e.g. console, tty, and udp. For these dev-
ices, 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 can be zero if no
input is currently available.
Printed 1/6/92 Page 3
INTRO(4spp) RISC/os Reference Manual INTRO(4spp)
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 that 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 confi-
guration 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 support file systems.
offset not on block boundry
An attempt was made to read or write from a
non-block offset on a block device.
out of file descriptors
Too many files are concurrently open.
bad filename: %s
A file name was specified that was not of the
format:
device(controller,unit,partition)path
dropped char Input from a character device had to be
dropped due to buffer overflow. Input must
be read faster by program or sent slower by
source.
SEE ALSO
intro(5spp), filesys(4spp)
Page 4 Printed 1/6/92