uio(D4)

uio -- virtual memory scatter/gather I/O request structure

Syntax

   #include <sys/types.h>
   #include <sys/file.h>
   #include <sys/uio.h>
   #include <sys/ddi.h>

Description

The uio structure describes an I/O request that can be broken up into different data storage areas (scatter/gather I/O). A request is a list of iovec(D4) structures (base/length pairs) indicating where in user space or kernel space the data are to be read/written.

Usage

The contents of the uio structure that is passed to the driver through the entry points in section D2 should not be changed directly by the driver. The uiomove(D3), ureadc(D3), and uwritec(D3) functions take care of maintaining the uio structure. A block driver may also use the physiock(D3) function to perform unbuffered I/O. physiock( ) also takes care of maintaining the uio structure.

A driver that creates its own uio structure for a data transfer is responsible for zeroing it prior to initializing members accessible to the driver. The driver must not change the uio structure afterwards; the functions take care of maintaining the uio structure.

Note that a separate interface does not currently exist for allocating uio and iovec structures when the driver needs to create them itself. Therefore, the driver may either use the kmem_zalloc(D3) routine to allocate them, or allocate them statically.

Structure definitions

The uio structure contains the following members:

   iovec_t   *uio_iov;
   int       uio_iovcnt;
   short     uio_segflg;
   int       uio_resid;
   short     uio_fmode;

The driver may only set uio structure members to initialize them for a data transfer for which the driver created the uio structure. The driver must not otherwise change uio structure members. However, drivers may read them. The uio structure members available for the driver to test or set are described below:

uio_iov

contains a pointer to the iovec(D4) array for the uio structure. If the driver creates a uio structure for a data transfer, the driver must also create an associated iovec array.

uio_iovcnt

contains the number of elements in the iovec array for the uio structure.

uio_segflg

identifies the virtual address space in which the transfer data areas reside. The following values are valid:

UIO_SYSSPACE: indicates that the data areas are within kernel space.
UIO_USERSPACE: indicates one data area is within kernel space and the other is within the user space of the current process context.

uio_resid

indicates the number of bytes that have not been transferred to or from the data area. If the driver creates a uio structure for a data transfer, uio_resid is initialized by the driver as the number of bytes to be transferred. This member is usually updated by the uiomove(D3), ureadc(D3), and uwritec(D3) functions.

uio_fmode

contains flags describing the file access mode for which the data transfer is to occur. Valid flags are:

FNONBLOCK: The driver should not wait if the requested data transfer cannot occur immediately; it should terminate the request, returning the EAGAIN error code as the completion status; see errnos(D5). The driver's implementation of the implied semantics of this flag are subject to device-dependent interpretation.

If the driver creates a uio structure for a data transfer, it may set this flag in uio_fmode.

Applicable hardware

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

Differences between versions

DDI versions prior to version 8 also support the following member for the uio structure:

   off_t	uio_offset;

uio_offset: Contains the starting logical byte address on the device where the data transfer is to occur. Applicability of this field to the driver is device-dependent. It applies to randomly accessed devices, but may not apply to all sequentially accessed devices.
For DDI 8 drivers, this member is replaced by the b_blkno and b_blkoff members of the buf(D4) structure to accomodate large file support. See ``Large device support'' in HDK Technical Reference.

For DDI versions prior to version 8, the uio_fmode member also supports the following flag:

FNDELAY: The driver should not wait if the requested data transfer cannot occur immediately; it should terminate the request without indicating an error occurred. The driver's implementation of this flag's implied semantics are subject to device-dependent interpretation.

References

iovec(D4), open(D2), physiock(D3), read(D2), uiomove(D3), ureadc(D3), uwritec(D3), write(D2)

``Large device support'' in HDK Technical Reference