io_buffer_vector(3K) SDK R4.11 io_buffer_vector(3K)
NAME
io_buffer_vector: io_add_to_buffer_vector_position,
io_check_access_and_wire_buffer_vector, io_get_buffer_vector_io_info,
io_get_buffer_vector_position, io_get_buffer_vector_residual,
io_get_buffer_vector_byte_count, io_init_buffer_vector,
io_init_one_entry_buffer_vector, io_mark_and_unwire_buffer_vector,
io_read_from_buffer_vector, io_reset_buffer_vector_position,
io_set_buffer_vector_residual, io_write_to_buffer_vector - manipulate
buffer vectors
SYNOPSIS
#include "/usr/src/uts/aviion/ii/i_io.h"
void io_add_to_buffer_vector_position (buffer_vector_ptr, count)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ ONLY*/
int32_type count; /*READ ONLY*/
status_type io_check_access_and_wire_buffer_vector (
io_buffer_vector_ptr_type buffer_vector_ptr, READ_ONLY
boolean_type user_buffer, READ_ONLY
uint32_type count, READ_ONLY
sc_access_mode_type access_requested READ_ONLY )
uint32_type io_get_buffer_vector_byte_count (buffer_vector_ptr)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ ONLY*/
void io_get_buffer_vector_io_info (buffer_vector_ptr,
buffer_ptr_ptr, count_ptr)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ ONLY*/
generic_pointer_ptr_type buffer_ptr_ptr; /*WRITE ONLY*/
uint32_ptr_type count_ptr; /*WRITE ONLY*/
uint32_type io_get_buffer_vector_position (buffer_vector_ptr)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ ONLY*/
uint32_type io_get_buffer_vector_residual (buffer_vector_ptr)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ ONLY*/
void io_init_buffer_vector (buffer_vector_ptr, total_size,
buffer_descriptors, count)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ/WRITE*/
uint32_type total_size; /*READ ONLY*/
io_buffer_descriptor_ptr_type buffer_descriptors; /*READ ONLY*/
uint16_type count; /*READ ONLY*/
void io_init_one_entry_buffer_vector (buffer_vector_ptr,
buffer_ptr, size)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ/WRITE*/
pointer_to_any_type buffer_ptr; /*READ ONLY*/
uint32_type size; /*READ ONLY*/
void io_mark_and_unwire_buffer_vector (
io_buffer_vector_ptr_type buffer_vector_ptr, READ_ONLY
boolean_type user_buffer, READ_ONLY
uint32_type count, READ_ONLY
sc_access_mode_type access_performed READ_ONLY )
status_type io_read_from_buffer_vector (buffer_vector_ptr,
buffer_ptr, count_ptr)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ/WRITE*/
pointer_to_any_type buffer_ptr; /*READ/WRITE*/
uint32_ptr_type count_ptr; /*READ/WRITE*/
void io_reset_buffer_vector_position (buffer_vector_ptr)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ ONLY*/
void io_set_buffer_vector_residual (buffer_vector_ptr, count)
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ ONLY*/
uint32_type count; /*READ ONLY*/
status_type io_write_to_buffer_vector (buffer_ptr, buffer_vector_ptr,
count_ptr)
pointer_to_any_type buffer_ptr; /*READ ONLY*/
io_buffer_vector_ptr_type buffer_vector_ptr; /*READ/WRITE*/
uint32_ptr_type count_ptr; /*READ/WRITE*/
where:
access_performed The type of access(es) that the caller made to the
memory: SC_READ_ACCESS and/or SC_WRITE_ACCESS.
access_requested The type of access the caller needs on the memory
referenced by the buffer vector: SC_READ_ACCESS or
SC_WRITE_ACCESS.
buffer_descriptors
Pointer to the array of buffer descriptors to be
associated with the buffer vector.
buffer_ptr A pointer to the buffer that is to be the sole
entry in the buffer_descriptors array or from which
data is to be read.
buffer_vector_ptr A pointer to a buffer vector.
count An integer specifying a number of bytes.
count_ptr 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
buffer_descriptor array.
total_size The sum of sizes from the buffer descriptors.
user_buffer 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:
io_add_to_buffer_vector_position Add to current buffer vector
position
io_check_access_and_wire_buffer_vector
Conditionally wire buffer vector
into memory
io_get_buffer_vector_byte_count Get buffer vector byte count
io_get_buffer_vector_io_info Return buffer pointer and the number
of contiguous bytes left in buffer
io_get_buffer_vector_position Get current buffer vector position
io_get_buffer_vector_residual Get number of bytes remaining in
buffer vector
io_init_buffer_vector Initialize a buffer vector
io_init_one_entry_buffer_vector Initialize one-entry buffer vector
io_mark_and_unwire_buffer_vector Unwire and mark buffer vector bytes
io_read_from_buffer_vector Read buffer vector data into buffer
io_reset_buffer_vector_position Reset buffer vector position to zero
io_set_buffer_vector_residual Set number of bytes remaining in
buffer vector
io_write_to_buffer_vector 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
io_init_one_entry_buffer_vector).
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
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 io_init_buffer_vector 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 io_init_one_entry_buffer_vector 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
io_get_buffer_vector_position to get the current buffer vector
position and io_get_buffer_vector_residual 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
io_get_buffer_vector_byte_count. 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
io_get_buffer_vector_io_info.
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 io_reset_buffer_vector_position to set the buffer vector's
current position back to zero (0). You call
io_set_buffer_vector_residual to set the residual variable that
contains the number of bytes remaining to be transferred. Similarly,
the io_add_to_buffer_vector_position 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 io_read_from_buffer_vector and io_write_to_buffer_vector 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
io_get_buffer_vector_io_info and io_add_to_buffer_vector_position to
produce the effect of the regular read/write routines. To do this,
first get the current position and remaining bytes using
io_get_buffer_vector_io_info, then perform the DMA, and finally
update the current position with io_add_to_buffer_vector_position.
You repeat this process as necessary given the block size of the
transfer. Using io_get_buffer_vector_io_info and
io_add_to_buffer_vector_position allows you to transfer directly from
the device to or from the buffer vector without going though an
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.
io_buffer_vector_type
typedef struct
{
union
{
io_buffer_vector_control_type many;
io_buffer_descriptor_type one;
} u;
uint16_type descriptor_count;
uint16_type current_descriptor;
uint32_type current_offset;
uint32_type total_remaining;
} io_buffer_vector_type ;
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 descriptor_count is non-
zero. See io_buffer_vector_control_type 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 descriptor_count is zero. See
io_buffer_descriptor_type below.
descriptor_count The number of entries in the many array of the
io_buffer_vector_control_type. Not all of these
entries are presumed valid; the total_size 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.
current_descriptor The index of the descriptor that contains the
current position. See
io_buffer_vector_control_type below.
current_offset The offset of the current position in the buffer
descriptor indexed by current_descriptor.
total_remaining The total number of bytes remaining to be moved to
or from this buffer vector since it was
initialized.
io_buffer_descriptor_type
typedef struct
{
pointer_to_any_type buffer_ptr;
uint32_type size;
} io_buffer_descriptor_type ;
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:
buffer_ptr Pointer to the start of the buffer.
size The size of the buffer, in bytes.
io_buffer_vector_control_type
typedef struct
{
io_buffer_descriptor_ptr_type descriptors_ptr;
uint32_type total_size;
} io_buffer_vector_control_type ;
This structure is used in the many field of buffer_vector_type. The
fields in this structure are as follows:
descriptors_ptr A pointer to an array of buffer descriptors.
The array may contain as many as UINT16_MAX
entries. (See c_generics.h for the definition
of UINT16_MAX.)
total_size The sum of the size fields in all the elements
of the array buffer descriptors.
io_add_to_buffer_vector_position
This routine adds the given count to the current position associated
with the given buffer vector. The amount added can be positive or
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.
io_check_access_and_wire_buffer_vector
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.
io_get_buffer_vector_byte_count
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 buffer_vector_ptr is assumed to be valid.
io_get_buffer_vector_io_info
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
io_read_bytes_from_buffer_vector or io_write_bytes_to_buffer_vector,
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 io_add_to_buffer_vector_position.
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.
io_get_buffer_vector_position
This routine gets the current position of the specified buffer
vector.
io_get_buffer_vector_residual
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
buffer_vector_ptr is assumed to be valid.
io_init_buffer_vector
This routine initializes a buffer vector. The buffer_vector_ptr is
assumed to be valid.
io_init_one_entry_buffer_vector
This routine initializes a buffer vector that will have only one
entry in the buffer_descriptors 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.
io_mark_and_unwire_buffer_vector
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.
io_read_from_buffer_vector
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 count_ptr bytes have been
moved. count_ptr is set to the actual number of bytes moved.
io_reset_buffer_vector_position
This routine resets the current position of the buffer vector to
zero.
io_set_buffer_vector_residual
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.
io_write_to_buffer_vector
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 count_ptr bytes have been
moved. count_ptr is set to the actual number of bytes moved.
DIAGNOSTICS
Return Value
For io_check_access_and_wire_buffer_vector:
OK The first count bytes of the buffer vector were
successfully wired into memory.
other Status codes returned from
vm_check_access_and_wire_memory.
For io_get_buffer_vector_byte_count:
count The byte count associated with the given buffer vector.
For io_get_buffer_vector_position:
position
The current position associated with the given buffer
vector.
For io_get_buffer_vector_residual:
count The residual bytes associated with the given buffer
vector
For io_read_from_buffer_vector:
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
status_code_macros(3K) man page.
For io_write_to_buffer_vector:
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
status_code_macros(3K) man page.
For the other routines: none.
Errors
None.
SEE ALSO
status_code_macros(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)