io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
NAME
iobuffervector: ioaddtobuffervectorposition,
iocheckaccessandwirebuffervector, iogetbuffervectorioinfo,
iogetbuffervectorposition, iogetbuffervectorresidual,
iogetbuffervectorbytecount, ioinitbuffervector,
ioinitoneentrybuffervector, iomarkandunwirebuffervector,
ioreadfrombuffervector, ioresetbuffervectorposition,
iosetbuffervectorresidual, iowritetobuffervector - manipulate
buffer vectors
SYNOPSIS
#include "/usr/src/uts/aviion/ii/iio.h"
void ioaddtobuffervectorposition (buffervectorptr, count)
iobuffervectorptrtype buffervectorptr; /*READ ONLY*/
int32type count; /*READ ONLY*/
statustype iocheckaccessandwirebuffervector (
iobuffervectorptrtype buffervectorptr, READONLY
booleantype userbuffer, READONLY
uint32type count, READONLY
scaccessmodetype accessrequested READONLY )
uint32type iogetbuffervectorbytecount (buffervectorptr)
iobuffervectorptrtype buffervectorptr; /*READ ONLY*/
void iogetbuffervectorioinfo (buffervectorptr,
bufferptrptr, countptr)
iobuffervectorptrtype buffervectorptr; /*READ ONLY*/
genericpointerptrtype bufferptrptr; /*WRITE ONLY*/
uint32ptrtype countptr; /*WRITE ONLY*/
uint32type iogetbuffervectorposition (buffervectorptr)
iobuffervectorptrtype buffervectorptr; /*READ ONLY*/
uint32type iogetbuffervectorresidual (buffervectorptr)
iobuffervectorptrtype buffervectorptr; /*READ ONLY*/
void ioinitbuffervector (buffervectorptr, totalsize,
bufferdescriptors, count)
iobuffervectorptrtype buffervectorptr; /*READ/WRITE*/
uint32type totalsize; /*READ ONLY*/
iobufferdescriptorptrtype bufferdescriptors; /*READ ONLY*/
uint16type count; /*READ ONLY*/
void ioinitoneentrybuffervector (buffervectorptr,
bufferptr, size)
iobuffervectorptrtype buffervectorptr; /*READ/WRITE*/
pointertoanytype bufferptr; /*READ ONLY*/
uint32type size; /*READ ONLY*/
Licensed material--property of copyright holder(s) 1
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
void iomarkandunwirebuffervector (
iobuffervectorptrtype buffervectorptr, READONLY
booleantype userbuffer, READONLY
uint32type count, READONLY
scaccessmodetype accessperformed READONLY )
statustype ioreadfrombuffervector (buffervectorptr,
bufferptr, countptr)
iobuffervectorptrtype buffervectorptr; /*READ/WRITE*/
pointertoanytype bufferptr; /*READ/WRITE*/
uint32ptrtype countptr; /*READ/WRITE*/
void ioresetbuffervectorposition (buffervectorptr)
iobuffervectorptrtype buffervectorptr; /*READ ONLY*/
void iosetbuffervectorresidual (buffervectorptr, count)
iobuffervectorptrtype buffervectorptr; /*READ ONLY*/
uint32type count; /*READ ONLY*/
statustype iowritetobuffervector (bufferptr, buffervectorptr,
countptr)
pointertoanytype bufferptr; /*READ ONLY*/
iobuffervectorptrtype buffervectorptr; /*READ/WRITE*/
uint32ptrtype countptr; /*READ/WRITE*/
where:
accessperformed The type of access(es) that the caller made to the
memory: SC_READ_ACCESS and/or SC_WRITE_ACCESS.
accessrequested The type of access the caller needs on the memory
referenced by the buffer vector: SC_READ_ACCESS or
SC_WRITE_ACCESS.
bufferdescriptors
Pointer to the array of buffer descriptors to be
associated with the buffer vector.
bufferptr A pointer to the buffer that is to be the sole
entry in the bufferdescriptors array or from which
data is to be read.
buffervectorptr A pointer to a buffer vector.
count An integer specifying a number of bytes.
countptr A pointer to an address specifying a number of
bytes or to contain on return an integer specifying
a number of bytes.
size The size, in bytes, of the sole entry in the
bufferdescriptor array.
totalsize The sum of sizes from the buffer descriptors.
userbuffer A boolean value indicating whether the buffers
associated with the buffer vector are user
addresses (TRUE) or kernel addresses (FALSE).
DESCRIPTION
The following routines are described in this man page:
Licensed material--property of copyright holder(s) 2
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
ioaddtobuffervectorposition Add to current buffer vector
position
iocheckaccessandwirebuffervector
Conditionally wire buffer vector
into memory
iogetbuffervectorbytecount Get buffer vector byte count
iogetbuffervectorioinfo Return buffer pointer and the number
of contiguous bytes left in buffer
iogetbuffervectorposition Get current buffer vector position
iogetbuffervectorresidual Get number of bytes remaining in
buffer vector
ioinitbuffervector Initialize a buffer vector
ioinitoneentrybuffervector Initialize one-entry buffer vector
iomarkandunwirebuffervector Unwire and mark buffer vector bytes
ioreadfrombuffervector Read buffer vector data into buffer
ioresetbuffervectorposition Reset buffer vector position to zero
iosetbuffervectorresidual Set number of bytes remaining in
buffer vector
iowritetobuffervector Write buffer data into buffer vector
NOTE: STREAMS is a message-based system
that supplies its own mechanisms for
passing data and messages.
Therefore the buffer vector system
is not applicable to STREAMS modules
and drivers.
Overview to Using Buffer Vectors
Buffer vectors are data structures that help you manage user-data
buffers, especially buffers that are spread over non-contiguous
space. The "v" system calls (readv and writev) can specify non-
contiguous buffer space, while the read and write system calls
specify contiguous buffers. And though buffer vectoring is most
useful in the non-contiguous case, you can use the buffer vector
interface for either set of read or write system calls.
A buffer vector consists of a collection (an array) of individual
buffer descriptors with associated state variables. Each buffer
descriptor consists of a buffer pointer and a buffer size.
Individual buffer descriptors define a location from which data can
be read, or into which the data can be written. Buffer vectors for
contiguous space (the read and write system calls) will have a buffer
vector array with only one entry (see
ioinitoneentrybuffervector).
The current position within the buffer vector is maintained by the
associated state variable. The current position defines where the
next byte of data will be read from or written to. The current
position is initialized to the first byte of the first buffer
descriptor.
Buffer vector routines can be grouped into four categories:
initialization, reporting of state information, modifying state
information, and data transfer (reading from or writing to the
Licensed material--property of copyright holder(s) 3
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
buffer). All buffer vector routines take a pointer to the respective
buffer vector as a parameter.
Before you can use a buffer vector with non-contiguous space, you
must call ioinitbuffervector to initialize it. In initialization,
the buffer vector's current position is set to zero (0) and its
logical address and the buffer's total size are stored in the buffer
descriptor. You call ioinitoneentrybuffervector to perform the
same function for a buffer vector with contiguous space and only one
buffer descriptor.
There are a number of routines you can call to get information about
the buffer vector and its current state. You can call
iogetbuffervectorposition to get the current buffer vector
position and iogetbuffervectorresidual to get the bytes remaining
to be transferred to or from the buffer vector. You can also get the
total size of all the descriptors in the buffer vector by calling
iogetbuffervectorbytecount. The value returned will be equal to
the current position plus the bytes remaining. Finally, you can get
the address of the current buffer position and amount of contiguous
bytes remaining starting at that position by calling
iogetbuffervectorioinfo.
Several other routines allow you to change the state information
maintained in the buffer vector. You should use these routines only
for exception situations such as when the buffer vector state needs
to be changed due to a data transfer failure.
You call ioresetbuffervectorposition to set the buffer vector's
current position back to zero (0). You call
iosetbuffervectorresidual to set the residual variable that
contains the number of bytes remaining to be transferred. Similarly,
the ioaddtobuffervectorposition allows you to change the current
position value by a specified amount. Take care not to increase the
current position by more than the number of bytes remaining in the
buffer vector.
These functions perform the actual data transfer to and from the
buffer vector. The current position is updated in accordance with
the amount of data transferred.
You use ioreadfrombuffervector and iowritetobuffervector to
transfer data between a buffer vector and a specified user buffer.
However, you cannot use these routines for DMA transfers because they
don't update position information. Instead you use
iogetbuffervectorioinfo and ioaddtobuffervectorposition to
produce the effect of the regular read/write routines. To do this,
first get the current position and remaining bytes using
iogetbuffervectorioinfo, then perform the DMA, and finally
update the current position with ioaddtobuffervectorposition.
You repeat this process as necessary given the block size of the
transfer. Using iogetbuffervectorioinfo and
ioaddtobuffervectorposition allows you to transfer directly from
the device to or from the buffer vector without going though an
Licensed material--property of copyright holder(s) 4
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
intermediate memory buffer.
Constants and Data Structures
This subsection describes constants and data structures defined in
the include files cited in the SYNOPSIS section and used by the
routines documented in this man page.
Try to avoid dependencies on the specifics of these structures, such
as size or location of fields, because these specifics may change in
later releases of the software. You can verify exact variable
definitions in the appropriate include file. The best way to avoid
such dependencies is to use kernel-supplied routines to manipulate
these structures.
iobuffervectortype
typedef struct
{
union
{
iobuffervectorcontroltype many;
iobufferdescriptortype one;
} u;
uint16type descriptorcount;
uint16type currentdescriptor;
uint32type currentoffset;
uint32type totalremaining;
} iobuffervectortype ;
This structure defines a buffer vector, a collection of individual
buffer descriptors plus an associated state. A buffer vector may be
the source or destination of a single read or write operation; the
individual buffer descriptors define the locations from which the
data is being read or into which the data is being written.
The current position is where the next byte of data will be read from
or written to. The current position is initialized to the first byte
of the first buffer descriptor. The current position within the
buffer vector is maintained by the associated state.
The fields in this structure are as follows:
many A structure containing a pointer to the array of
buffer descriptors and the total of the sizes of
all the elements of the array. This field of the
union is used only when descriptorcount is non-
zero. See iobuffervectorcontroltype below.
one A structure containing the single buffer
descriptor when the buffer vector consists of a
single descriptor. This field of the union is
used only when descriptorcount is zero. See
iobufferdescriptortype below.
descriptorcount The number of entries in the many array of the
Licensed material--property of copyright holder(s) 5
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
iobuffervectorcontroltype. Not all of these
entries are presumed valid; the totalsize field
controls the number of entries that are used.
This field determines the actual amount of memory
allocated to the array. If this field is zero, no
memory is allocated to the array and a single
descriptor is stored in the union field one.
currentdescriptor The index of the descriptor that contains the
current position. See
iobuffervectorcontroltype below.
currentoffset The offset of the current position in the buffer
descriptor indexed by currentdescriptor.
totalremaining The total number of bytes remaining to be moved to
or from this buffer vector since it was
initialized.
iobufferdescriptortype
typedef struct
{
pointertoanytype bufferptr;
uint32type size;
} iobufferdescriptortype ;
This structure describes a buffer from which data is to be read or to
which data is to be written.
The fields in this structure are as follows:
bufferptr Pointer to the start of the buffer.
size The size of the buffer, in bytes.
iobuffervectorcontroltype
typedef struct
{
iobufferdescriptorptrtype descriptorsptr;
uint32type totalsize;
} iobuffervectorcontroltype ;
This structure is used in the many field of buffervectortype. The
fields in this structure are as follows:
descriptorsptr A pointer to an array of buffer descriptors.
The array may contain as many as UINT16MAX
entries. (See cgenerics.h for the definition
of UINT16MAX.)
totalsize The sum of the size fields in all the elements
of the array buffer descriptors.
ioaddtobuffervectorposition
This routine adds the given count to the current position associated
with the given buffer vector. The amount added can be positive or
Licensed material--property of copyright holder(s) 6
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
negative. If the new value of the current position would be less
than zero or greater than the byte count associated with the buffer
vector, the result is undefined. Note that changing the current
position changes the residual count by implication, so that the
relationship between the current position plus residual count and the
overall byte count remains true.
iocheckaccessandwirebuffervector
This routine wires the buffer vector into memory if the caller has
the necessary permissions to access the buffer in the requested way.
Data in the buffer vector is wired for count bytes starting at the
current position in the buffer vector. If an error occurs in wiring
any portion of the buffer vector, none of the buffer vector will be
wired.
The buffer vector itself is not modified; i.e., the size, current
position, and other attributes of the buffer vector remain unchanged.
iogetbuffervectorbytecount
This routine gets the byte count for the specified buffer vector.
This count is the number of bytes of data that this vector can hold.
The buffervectorptr is assumed to be valid.
iogetbuffervectorioinfo
This routine takes the current buffer descriptor and returns the
buffer pointer and the number of contiguous bytes left in the buffer
from that pointer. This permits DMA I/O operations to be performed
on the buffer.
Drivers can use this routine to produce the same effect as
ioreadbytesfrombuffervector or iowritebytestobuffervector,
but with the transfer going directly between the device and the
buffer vector instead of through an intermediate memory buffer. To
do this, the driver successively gets the I/O information for the
current position, performs DMA I/O, and updates the current position
with ioaddtobuffervectorposition.
NOTE: This routine must not be called when the buffer vector
residual is zero, as the returned count is defined to always
be strictly greater than zero.
iogetbuffervectorposition
This routine gets the current position of the specified buffer
vector.
iogetbuffervectorresidual
This routine gets the number of bytes remaining in the specified
buffer vector. This residual count is always equal to the byte count
of the buffer vector minus the current position. The
buffervectorptr is assumed to be valid.
ioinitbuffervector
This routine initializes a buffer vector. The buffervectorptr is
Licensed material--property of copyright holder(s) 7
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
assumed to be valid.
ioinitoneentrybuffervector
This routine initializes a buffer vector that will have only one
entry in the bufferdescriptors array.
This routine is called if a buffer vector structure is being created
with a single buffer descriptor entry. Using this routine to
initialize a single entry buffer vector allows optimizations to be
performed in buffer vector management.
iomarkandunwirebuffervector
Unwire count bytes of the specified buffer vector and mark the bytes
according to the access_performed parameter.
Data in the buffer vector is unwired for count bytes starting at the
current position in the buffer vector.
The buffer vector itself is not modified; i.e., the size, current
position, and other attributes of the buffer vector remain unchanged.
ioreadfrombuffervector
This routine reads data from the buffer vector into the specified
buffer.
Data is moved into the specified buffer starting at the current
position of the specified buffer vector until all the data in the
buffer vector has been exhausted or until countptr bytes have been
moved. countptr is set to the actual number of bytes moved.
ioresetbuffervectorposition
This routine resets the current position of the buffer vector to
zero.
iosetbuffervectorresidual
This routine sets the number of bytes remaining in the specified
buffer vector. The current position is unchanged.
Because the residual is always equal to the total size minus the
current position, and the current position is unchanged by this
routine, this routine changes the total size by implication.
iowritetobuffervector
This routine writes data from the specified buffer into the buffer
vector.
Data is moved into the buffer vector. The transfer starts at the
beginning of the specified buffer and goes until the end of the
buffer vector has been reached or until countptr bytes have been
moved. countptr is set to the actual number of bytes moved.
DIAGNOSTICS
Return Value
For iocheckaccessandwirebuffervector:
Licensed material--property of copyright holder(s) 8
io_buffer_vector(3K) DG/UX 5.4R3.00 io_buffer_vector(3K)
OK The first count bytes of the buffer vector were
successfully wired into memory.
other Status codes returned from
vmcheckaccessandwirememory.
For iogetbuffervectorbytecount:
count The byte count associated with the given buffer vector.
For iogetbuffervectorposition:
position
The current position associated with the given buffer
vector.
For iogetbuffervectorresidual:
count The residual bytes associated with the given buffer
vector
For ioreadfrombuffervector:
OK The bytes were successfully written to the buffer area.
other error statuses
The bytes could not be read because of an error. The
specific list of possible errors is too long to give
here. You can decode any status returned here using
the error status decoding methods described in the
statuscodemacros(3K) man page.
For iowritetobuffervector:
OK The bytes were successfully written to the buffer area.
other error statuses
An error terminated the write operation. The list of
possible errors is too long to give here. You can
decode any status returned here using the status
decoding methods described in the
statuscodemacros(3K) man page.
For the other routines: none.
Errors
None.
SEE ALSO
statuscodemacros(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s) 9