biodd
Purpose
Provides a programming interface for transmitting and
receiving data for adapters that are accessed through the
VRM Block I/O Device Manager.
Synopsis
#include <sys/biodd.h>
Description
The Block I/O AIX Device Driver provides support for
transmitting and receiving data for adapters that are
accessed through the VRM Block I/O Device Manager. This
driver is designed to be a multiplexed device driver that
permits multiple opens for those adapters allowed to have
multiple opens by VRM device driver.
The Block I/O AIX Device Driver can be used by any appli-
cation that is written to run above the kernel. The
/etc/biodd file contains the device names of the adapters
to be accessed and can be edited to add or remove device
names. After /etc/biodd has been edited, the device
driver must be configured for the adapters that the user
wishes to access by means of the Block I/O AIX Device
Driver using the biodd_cfg command. To configure these
adapters automatically each time the system is started,
uncomment the "/etc/biodd_cfg" line in the
/etc/rc.include file.
A process interfaces to the Block I/O AIX Device Driver
through the following system calls:
open Initializes the path to an adapter port for the
kernel process.
close Indicates the port will no longer be used and
deletes the path from the kernel process.
read Receives data from the adapter.
write Sends data to the adapter.
select Waits on file descriptors or message queue IDs
until one is ready.
ioctl Used for the device-dependent commands described
in "ioctl Operations."
ERROR HANDLING
There are two types of errors that the Block I/O AIX
Device Driver is unable to associate with a specific
command: write command errors and unsolicited interrupts
that are not related to a specific command. Write
command error information may be received after return
has already been made to the user. This condition occurs
because, for the block I/O write system call, return
simply means that the command has been enqueued to the
VRM and not that the command has actually been executed
by the VRM. Also, certain unsolicited interrupts occur
that are not related to a specific command. When the
Block I/O AIX Device Driver receives one of these inter-
rupts, the completion information is saved and a return
code of -1 and an errno value of EIO are returned to the
user on the next I/O request for that particular file
descriptor. The I/O request will not be acted upon and
must be reissued by the user.
Completion information returned to the user by the
BIOC_GET_PSB ioctl call indicates the error type. For
more information on the data returned from the program
status block (PSB), see Virtual Resource Manager Tech-
nical Reference. The PSB status flags field contains
bits that indicate this information pertains to a certain
interrupt type. If the interrupt type is a Send Command
I/O interrupt, the return information includes an opera-
tion options field that can be used to identify the spe-
cific command. See Virtual Resource Manager Technical
Reference for an explanation of the PSB status flags and
the operation options.
To receive notification at the time an error occurs,
rather than waiting until the next I/O request, use the
select system call to select exceptions for this file
descriptor. You can also use the BIOC_SET_SIGNAL ioctl
system call to set a signal value that is sent whenever
an exception condition occurs. The signal can then be
handled in the normal manner.
Once you are notified of an error, you are not notified
again of the same error. For example, if you are noti-
fied of an unsolicited interrupt by means of a signal or
in response to a select system call, you do not receive
an indication of that error on the next I/O request.
OPEN SUPPORT
The open system call opens a file descriptor for the file
named by the path parameter. The path specifies the
Block I/O AIX Device Driver (/dev/biodd). followed by a
slash and the device name (from the devices command).
The open system call has the following format:
int open (path, oflag)
char *path;
int oflag;
The value of oflag sets the file status flag. This value
is constructed by logically OR-ing flags from the fol-
lowing list:
O_RDWR Open for reading and writing.
O_RDONLY Open for reading only.
O_WRONLY Open for writing only.
O_NDELAY If set, a read system call returns imme-
diately either with or without data. If this
flag is not set, a read system call waits if
there is no data to return.
To complete the open process, the open system call must
be followed by a BIOC_START ioctl.
Upon successful completion, a file descriptor is
returned. If the open fails, a value of -1 is returned
and errno is set to indicate the error.
The open fails if one or more of the following are true:
ENOENT The named file does not exist.
ENOTDIR A component of the path prefix is not a direc-
tory.
EACCES A component of the path prefix denies search
permission, or permission is denied for the
named file.
EISDIR The named file is a directory and oflag is write
or read/write.
EROFS The named file resides on a read-only file
system and oflag is write or read/write.
EMFILE Maximum number of file descriptors are currently
open.
EFAULT The path parameter points outside the process's
allocated address space.
EINVAL Invalid parameter or stanza name too long
(greater than 32) or not supported.
Note: For an adapter card that allows only one
open per port, this error is returned if the
port is already open.
EINTR The open system call was interrupted.
ENODEV There is no such device.
EBUSY All of the available 256 ports are in use.
EPERM The open for device CONFIG requires superuser
authority.
ENOMEN The device driver was unable to allocate space
it needed.
ENXIO An attempt was made to open the device driver
before it was configured.
READ SUPPORT
The read system call is used to receive data from an
application. A pointer of buf points to a buffer area
into which the data is read. This buffer address must be
on a word boundary. The receive data area is preceded by
an 80-byte header containing the data length and offset
fields of the receive data. For a complete description
of the data buffer structure for a specific adapter, see
Virtual Resource Manager Technical Reference.
The value of nbyte specifies the maximum amount of data
the program receives. The value of nbyte should be
greater than or equal to the device buffer length. The
device buffer length is set by running the devices
command for the specified adapter and setting the lobibp
parameter. If the data to be received is larger than
nbyte, an error of EINVAL is returned.
The read system call has the following format:
int read (fildes, buf, nybte)
int fildes;
char *buf;
int nbyte;
Upon successful completion, a positive integer is
returned indicating the number of bytes read. An unsuc-
cessful read returns a value of -1 and errno is set to
indicate the error.
The read fails if one or more of the following are true:
EFAULT An invalid address was specified.
EIO An I/O error occurred. This error was out-
standing at the time the read was issued. A
BIOC_GET_PSB ioctl system call will supply more
information.
EBADF An invalid file descriptor was specified.
EINTR The read system call was interrupted.
EINVAL An invalid argument was specified.
ENODEV An attempt to read was made before the device
was started.
WRITE SUPPORT
The write system call sends data to an application. The
Write_Send_Command SVC is used by the Block I/O AIX
device driver to send the data to the VRM.
A pointer of buf points to the buffer area to send. This
buffer address must be on a word boundary. An 80-byte
buffer header must precede the data to be written. The
data length and data offset fields and, if present,
device-dependent information for the adapter, must be set
by the user. For a complete description of the data
buffer structure of a specific adapter, see Virtual
Resource Manager Technical Reference.
The value of nbyte specifies the buffer length, in bytes,
that the program is sending. The value of nbyte must be
less than the device buffer length. The device buffer
length is set with the lobibp parameter of the devices
command. If nbyte is larger than the device buffer
length, an error of EINVAL is returned.
The write system call has the following format:
int write (fildes, buf, nbyte)
int fildes;
char *buf;
int nbyte;
Upon successful completion, a positive integer is
returned indicating the number of bytes written. An
unsuccessful write returns a value of -1 and errno is set
to indicate the error.
The write fails if one or more of the following are true:
EBADF An invalid file descriptor was specified.
EFAULT An invalid address was specified.
EIO An I/O error occurred. This error was out-
standing at the time the write was issued. A
BIOC_GET_PSB ioctl system call will supply more
information.
EINVAL An invalid parameter was passed.
EINTR The write system call was interrupted.
ENODEV An attempt to write was made before the device
was started.
ENOSPC There is currently no space available in the VRM
buffer pool. Data cannot be enqueued to the VRM
at this time.
Note: The total number of buffers (in the VRM
buffer pool and available to the device) is set
with the nobibp parameter of the devices
command.
CLOSE AND SELECT SUPPORT
For a complete description of the close and select system
calls, see "close" and "select."
IOCTL OPERATIONS
The Block I/O AIX Device Driver performs the following
ioctl operations. For a complete description of the
ioctl system call, see "ioctl"
Four Block I/O AIX Device Driver ioctl calls have the
format:
int ioctl (fildes, command, arg)
int fildes;
int command;
char *arg;
The four commands using this format are:
BIOC_GET_PSB Returns completion information from the
Program Status Block about an exception
condition that has occurred. The program
is notified that the information is avail-
able either by receiving a negative return
code and an errno value of EIO from a
Block I/O AIX Device Driver system call,
or by a return from a select system call
that is waiting due to exceptions.
The arg parameter contains the address of
the buffer into which the completion
information returns. This buffer must be
at least 20 bytes in length and, on
return, contains the following general
information:
Reserved 2 bytes
Status flags 1 byte
Overrun count 1 byte
Status word Consists of the following
for this application:
Operation results (2
bytes)
Input/Output device
number or iodn (2
bytes)
Data word 1 4 bytes
Data word 2 4 bytes
Data word 3 4 bytes
For a description of the specific SVC
command completion information contained
in the above fields, see Virtual Resource
Manager Technical Reference
Upon successful completion, a value of 0
is returned. If the BIOC_GET_PSB ioctl
fails, a value of -1 is returned and errno
is set to indicate the error.
The BIOC_GET_PSB ioctl fails if one or
more of the following are true:
EBADF An invalid file descriptor was
specified.
EFAULT An invalid address was specified.
EINVAL There is no error PSB available
to send back.
BIOC_QUERYDEV Returns the Query Device Structure (QDS)
for the stated device. This structure is
returned from a Query_Device SVC to the
VRM. The arg parameter contains the
address of a user input structure con-
taining the following fields:
Reserved This field is 2 bytes
long.
Query options Defines the device infor-
mation to return. This is
a 2-byte field. The pos-
sible values are:
1 Returns the hardware
characteristics.
2 Returns the device
characteristics.
4 Returns the error log.
7 Returns all of the
above.
QDS length Contains the length, in
bytes, of the buffer in
which the QDS returns. If
the buffer is not large
enough to contain the
requested information, an
error returns. This is a
4-byte field.
QDS address Contains the address of
the buffer in which the
requested QDS information
returns. This is a 4-byte
field. The QDS returned
consists of Define Device
Structure (DDS) header
information, operation
completion information for
the last operation com-
pleted, and the device-
dependent information
requested by the query
options field. For more
information about the
device-dependent informa-
tion, see Virtual Resource
Manager Technical Refer-
ence.
If an error occurs, a value of -1 is
returned and errno is set to indicate the
error. A value of 0 is returned if there
is no error.
The BIOC_QUERYDEV ioctl fails if one or
more of the following are true:
EBADF An invalid file descriptor was
specified.
EINTR The ioctl system call was inter-
rupted.
EINVAL The length of the Query Device
Structure provided is not large
enough to contain the requested
data.
EFAULT An invalid address was specified.
ENOMEM The device driver was unable to
allocate needed space.
EIO An I/O error occurred. This
error was outstanding at the time
the query was issued. A
BIOC_GET_PSB ioctl system call
will supply more information.
BIOC_SEND_COMMAND
Issues a device-dependent send command.
This request is done by requiring the user
to provide all the needed information to
the Send_Command SVC to the VRM.
The arg parameter contains the address of
a 24-byte (6-word) buffer. This buffer is
used both for input data and to return
data to the user. On input, the 6-word
buffer should contain the data passed in
General Purpose Registers 2 through 7
(GPR2-GPR7). For more information on
device-dependent commands and the input
and return data for a specific adapter,
see Virtual Resource Manager Technical
Reference.
The contents of the input structure are
described as follows:
GPR2 Bits 0-15 of the first word are set
equal to the input/output device
number (IODN) of the device by the
Block I/O AIX Device Driver. Any
value put in this area by the user
will be overwritten.
Bits 16-31 contain the operation
options field. With the exception
of bits 19 and 24-31, this field is
set by the AIX device driver. Bits
19 and 24-31 are set by the user as
follows:
Bit 19 Sets the command
extension.
Bits 24-31 Sets the device option
for the device-
dependent command to a
value greater than 8.
The AIX device driver
checks that this field
is greater than 8 in
order to ensure that
this is a device-
dependent command.
GPR3 The second word must be set equal
to the command-specific data for
the device.
GPR4 The third word must be set equal to
the command-specific data for the
device.
GPR5 The fourth word must be set equal
to the address of the command
extension area, if one is required
for this device-dependent command;
otherwise, this word contains
command-specific data. If a
command extension area is required
for this command, the user must
also fill in the necessary fields
of this buffer.
GPR6 The fifth word must be set equal to
the length of the command extension
area, if one is required for this
device-dependent command; other-
wise, this word contains command-
specific data.
Note: Some device-dependent com-
mands may also return data in the
command extension area whose
address was passed on the call.
When this occurs, the command
extension area must be long enough
to include all returned data.
GPR7 The sixth word will be set equal to
the path identifier of the path to
the VRM device driver by the Block
I/O AIX Device Driver.
If the command completes successfully,
upon return, the buffer pointed to by the
arg parameter contains Program Status
Block completion information. For infor-
mation on this completion data, see
Virtual Resource Manager Technical Refer-
ence.
If an error occurs, a value of -1 is
returned and errno is set to indicate the
error. A successful completion returns a
value of 0.
The BIOC_SEND ioctl does not complete suc-
cessfully if one or more of the following
are true:
EBADF An invalid file descriptor was
specified.
EINVAL An invalid parameter was passed.
This command is not one of the
device-dependent commands. (The
device option specified is less
than or equal to 8.)
EFAULT An invalid address was specified.
EINTR The ioctl system call was inter-
rupted.
EIO An I/O error occurred. This
error may be an error obtained on
the execution of this system
call, or it may be an error that
was outstanding at the time this
call was issued. A BIOC_GET_PSB
ioctl system call will supply
more information.
ENOMEM The device driver was unable to
allocate needed space.
BIOC_START Requests the VRM device driver to start a
specified network ID. For the Token-Ring
Adapter, this is the service access point
(SAP) and for the Baseband Adapter, this
is the type field. Only one BIOC_START
ioctl system call is allowed per open.
The arg parameter contains the address of
a 24-byte (6-word) buffer. This buffer is
used both for input data and to return
data to the user. On input, the 6-word
buffer should contain the data passed in
General Purpose Registers 2 through 7
(GPR2-GPR7). For more information on the
Start Send SVC command and the input and
return data for a specific adapter, see
Virtual Resource Manager Technical Refer-
ence.
The contents of the structure are
described as follows:
GPR2 Bits 0-15 of the first word will be
set equal to the input/output
device number (IODN) of the device
by the Block I/O AIX Device Driver
Any value put in this area by the
user is overwritten.
Bits 16-31 contain the operation
options field. This field is set
by the AIX device driver.
GPR3 Reserved for system use.
GPR4 Reserved for system use.
GPR5 The fourth word must be set equal
to the address of the command
extension area.
GPR6 The fifth word must be set equal to
the length of the command extension
area.
Note: Some Start Send SVC commands
may also return data in the command
extension area whose address was
passed on the call. When this
occurs, the command extension area
must be long enough to include all
returned data.
GPR7 The sixth word is set equal to the
path identifier of the path to the
VRM device driver by the Block I/O
AIX Device Driver.
The following list describes the fields
within the command extension area that are
set by the AIX device driver or the user:
Level/sublevel The interrupt level
used to return
virtual interrupts to
the AIX device
driver. (Set by the
AIX device driver)
Ring correlator A 1-byte value
returned by the VRM
with all virtual
interrupts for the
following network ID.
(Set by the AIX
device driver)
device dependent An optional area used
to pass additional
device-dependent
information. For a
description of the
device-dependent area
of the command exten-
sion area, see the
Start_Device SVC
command for the spe-
cific VRM device
driver in Virtual
Resource Manager
Technical Reference.
If the command completes successfully,
upon return, the buffer pointed to by the
arg parameter contains Program Status
Block completion information. For infor-
mation on this completion data, see
Virtual Resource Manager Technical Refer-
ence.
If an error occurs, a value of -1 is
returned and errno is set to indicate the
error. A successful start returns a 0.
The completion information returned to the
user is only valid if the the user
receives a return code of 0.
The BIOC_START ioctl does not complete
successfully if one or more of the fol-
lowing are true:
EBADF An invalid file descriptor was
specified.
EINVAL An invalid parameter was
passed.
EFAULT An invalid address was speci-
fied.
EINTR The ioctl system call was
interrupted.
EBUSY A START has already been per-
formed for this file descriptor
and only one start command is
allowed per file descriptor.
EIO An I/O error occurred. This
error may be an error obtained
on the execution of this system
call, or it may be an error
that was outstanding at the
time this call was issued. A
BIOC_GET_PSB ioctl system call
will supply more information.
ENOMEM The device driver was unable to
allocate needed space.
The command, BIOC_SET_SIGNAL, has the ioctl system call
format:
int ioctl (fildes, BIOC_SET_SIGNAL, arg)
int fildes;
int BIOC_SET_SIGNAL;
int arg;
The command, BIOC_SET_SIGNAL sets a signal value of arg
that is to be sent whenever an exception condition is
encountered. A value of NO_SIG turns off signals. For
descriptions of signal values, see the
/usr/include/sys/signal.h file.
The command IOCCONFIG uses the ioctl system call format:
#include <sys/ioctl.h>
int ioctl (fildes, IOCCONFIG, arg)
int fildes;
int IOCCONFIG;
struct config *arg;
The command, IOCCONFIG, configures the device driver for
all devices that appear in the /etc/biodd file. An AIX
command that issues this call is installed with the
device driver. The command, /etc/biodd_cfg, is usually
called from the etc/rc.include file which runs at IPL.
This command copies the internal table, which ties the
stanza to the device IODN, into the device driver. A
pointer of arg, to a config structure, contains the
number of devices and the stanza name and IODN for each
device.
The command IOCINFO has the ioctl system call format:
int ioctl (fildes, IOCINFO, arg)
int fildes;
int IOCINFO;
struct devinfo *arg;
The command, IOCINFO, returns a devinfo structure that
describes the device type and its associated flags. The
file descriptor returned from an open is specified by
fildes. For the format of this structure, see
/usr/include/sys/devinfo.h.
If an error occurs, a value of -1 is returned and errno
is set to indicate the error. Otherwise, a devinfo
structure with the device type and flags is returned.
The value of flags will be zero.
The command, IOCTYPE, has the ioctl system call format:
int ioctl (fildes, IOCTYPE)
int fildes;
int IOCTYPE;
The command IOCTYPE, returns the device type associated
with the file descriptor fildes. If an error occurs, a
value of -1 is returned and errno is set to indicate the
error. If no errors occur, the device driver type
returns.
Files
/dev/biodd Device driver file
/etc/biodd Configuration file
Related Information
In this book: "close," "ioctl," "open," "read, readx,"
"select," "write, writex," and "system."
Virtual Resource Manager Technical Reference
The biodd_cfg command in AIX Operating System Communi-
cations Guide.