Reads in data from a character device.
#include <sys/device.h> #include <sys/types.h> int ddread (devno, uiop, chan, ext) dev_t devno; struct uio *uiop; chan_t chan; int ext;
| devno | Specifies the major and minor device numbers. |
| uiop | Points to a uio structure describing the data area or areas in which to be written. |
| chan | Specifies the channel number. |
| ext | Specifies the extension parameter. |
When a program issues a read or readx subroutine call or when the fp_rwuio kernel service is used, the kernel calls the ddread entry point.
This entry point receives a pointer to a uio structure that provides variables used to specify the data transfer operation.
Character device drivers can use the ureadc and uiomove kernel services to transfer data into and out of the user buffer area during a read subroutine call. These services receive a pointer to the uio structure and update the fields in the structure by the number of bytes transferred. The only fields in the uio structure that cannot be modified by the data transfer are the uio_fmode and uio_segflg fields.
For most devices, the ddread routine sends the request to the device handler and then waits for it to finish. The waiting can be accomplished by calling the e_sleep kernel service. This service suspends the driver and the process that called it and permits other processes to run until a specified event occurs.
When the I/O operation completes, the device usually issues an interrupt, causing the device driver's interrupt handler to be called. The interrupt handler then calls the e_wakeup kernel service specifying the awaited event, thus allowing the ddread routine to resume.
The uio_resid field initially contains the total number of bytes to read from the device. If the device driver supports it, the uio_offset field indicates the byte offset on the device from which the read should start.
The uio_offset field is a 64 bit integer (offset_t) ; this allows the file system to send I/O requests to a device driver's read & write entry points which have logical offsets beyond 2 gigabytes. Device drivers must use care not to cause a loss of significance by assigning the offset to a 32 bit variable or using it in calculations that overflow a 32 bit variable.
If no error occurs, the uio_resid field should be 0 on return from the ddread routine to indicate that all requested bytes were read. If an error occurs, this field should contain the number of bytes remaining to be read when the error occurred.
If a read request starts at a valid device offset but extends past the end of the device's capabilities, no error should be returned. However, the uio_resid field should indicate the number of bytes not transferred. If the read starts at the end of the device's capabilities, no error should be returned. However, the uio_resid field should not be modified, indicating that no bytes were transferred. If the read starts past the end of the device's capabilities, an ENXIO return code should be returned, without modifying the uio_resid field.
When the ddread entry point is provided for raw I/O to a block device, this routine usually translates requests into block I/O requests using the uphysio kernel service.
The ddread routine is executed only in the process environment. It should provide the required serialization of its data structures by using the locking kernel services in conjunction with a private lock word defined in the driver.
The ddread entry point can indicate an error condition to the caller by returning a nonzero return code. This causes the subroutine call to return a value of -1. It also makes the return code available to the user-mode program in the errno global variable. The error code used should be one of the values defined in the /usr/include/sys/errno.h file.
When applicable, the return values defined in the POSIX 1003.1 standard for the read subroutine should be used.
The ddwrite device driver entry point.
The e_sleep kernel service, e_wakeup kernel service, fp_rwuio kernel service, uiomove kernel service, uphysio kernel service, ureadc kernel service.
The uio structure.
The read, readx subroutines.
Select/Poll Logic for ddwrite and ddread Routines.
Device Driver Kernel Extension Overview in AIX Kernel Extensions and Device Support Programming Concepts.
Programming in the Kernel Environment Overview in AIX Kernel Extensions and Device Support Programming Concepts.