Miscellaneous I/O Control
The ioctl(9E) routine is called when a user thread issues an ioctl(2) system
call on a file descriptor associated with the device. The I/O control mechanism
is a catchall for getting and setting device-specific parameters. This mechanism is frequently
used to set a device-specific mode, either by setting internal driver software flags or
by writing commands to the device. The control mechanism can also be used
to return information to the user about the current device state. In short,
the control mechanism can do whatever the application and driver need to have
done.
ioctl() Entry Point (Character Drivers)
int xxioctl(dev_t dev, int cmd, intptr_t arg, int mode,
cred_t *credp, int *rvalp);The cmd parameter indicates which command ioctl(9E) should perform. By convention, the driver
with which an I/O control command is associated is indicated in bits 8-15
of the command. Typically, the ASCII code of a character represents the
driver. The driver-specific command in bits 0-7. The creation of some I/O commands
is illustrated in the following example:
#define XXIOC (`x' << 8) /* `x' is a character that represents device xx */
#define XX_GET_STATUS (XXIOC | 1) /* get status register */
#define XX_SET_CMD (XXIOC | 2) /* send command */
The interpretation of arg depends on the command. I/O control commands should be
documented in the driver documentation or a man page. The command should also
be defined in a public header file, so that applications can determine the
name of the command, what the command does, and what the command accepts
or returns as arg. Any data transfer of arg into or out of
the driver must be performed by the driver.
Certain classes of devices such as frame buffers or disks must support standard
sets of I/O control requests. These standard I/O control interfaces are documented in
the Solaris 8 Reference Manual Collection. For example, fbio(7I) documents the I/O controls that frame buffers must support,
and dkio(7I) documents standard disk I/O controls. See Miscellaneous I/O Control for more information on I/O
controls.
Drivers must use ddi_copyin(9F) to transfer arg data from the user-level application to
the kernel level. Drivers must use ddi_copyout(9F) to transfer data from
the kernel to the user level. Failure to use ddi_copyin(9F) or ddi_copyout(9F)
can result in panics under two conditions. A panic occurs if the architecture
separates the kernel and user address spaces, or if the user address has
been swapped out.
ioctl(9E) is usually a switch statement with a case for each supported
ioctl(9E) request.
Example 15-12 ioctl(9E) Routine
static int
xxioctl(dev_t dev, int cmd, intptr_t arg, int mode,
cred_t *credp, int *rvalp)
{
uint8_t csr;
struct xxstate *xsp;
xsp = ddi_get_soft_state(statep, getminor(dev));
if (xsp == NULL) {
return (ENXIO);
}
switch (cmd) {
case XX_GET_STATUS:
csr = ddi_get8(xsp->data_access_handle, &xsp->regp->csr);
if (ddi_copyout(&csr, (void *)arg, sizeof (uint8_t), mode) != 0) {
return (EFAULT);
}
break;
case XX_SET_CMD:
if (ddi_copyin((void *)arg, &csr, sizeof (uint8_t), mode) != 0) {
return (EFAULT);
}
ddi_put8(xsp->data_access_handle, &xsp->regp->csr, csr);
break;
default:
/* generic "ioctl unknown" error */
return (ENOTTY);
}
return (0);
}The cmd variable identifies a specific device control operation. A problem can occur
if arg contains a user virtual address. ioctl(9E) must call ddi_copyin(9F) or ddi_copyout(9F) to
transfer data between the data structure in the application program pointed to by
arg and the driver. In Example 15-12, for the case of an XX_GET_STATUS request, the
contents of xsp->regp->csr are copied to the address in arg. ioctl(9E) can store
in *rvalp any integer value as the return value to the ioctl(2) system call
that makes a successful request. Negative return values, such as -1, should be
avoided. Many application programs assume that negative values indicate failure.
The following example demonstrates an application that uses the I/O controls discussed in
the previous paragraph.
Example 15-13 Using ioctl(9E)
#include <sys/types.h>
#include "xxio.h" /* contains device's ioctl cmds and args */
int
main(void)
{
uint8_t status;
/* ... */
/*
* read the device status
*/
if (ioctl(fd, XX_GET_STATUS, &status) == -1) {
/* error handling */
}
printf("device status %x\n", status);
exit(0);
}
I/O Control Support for 64-Bit Capable Device Drivers
The Solaris kernel runs in 64-bit mode on suitable hardware, supporting both 32-bit
applications and 64-bit applications. A 64-bit device driver is required to support I/O
control commands from programs of both sizes. The difference between a 32-bit program
and a 64-bit program is the C language type model. A 32-bit program
is ILP32, and a 64-bit program is LP64. See Appendix C, Making a Device Driver 64-Bit Ready for information on
C data type models.
If data that flows between programs and the kernel is not identical in
format, the driver must be able to handle the model mismatch. Handling a
model mismatch requires making appropriate adjustments to the data.
To determine whether a model mismatch exists, the ioctl(9E) mode parameter
passes the data model bits to the driver. As Example 15-14 shows, the mode
parameter is then passed to ddi_model_convert_from(9F) to determine whether any model conversion
is necessary.
A flag subfield of the mode argument is used to pass the
data model to the ioctl(9E) routine. The flag is set to one of the
following:
DATAMODEL_ILP32
DATAMODEL_LP64
FNATIVE is conditionally defined to match the data model of the kernel implementation.
The FMODELS mask should be used to extract the flag from the mode
argument. The driver can then examine the data model explicitly to determine how
to copy the application data structure.
The DDI function ddi_model_convert_from(9F) is a convenience routine that can assist some drivers
with their ioctl() calls. The function takes the data type model of the
user application as an argument and returns one of the following values:
DDI_MODEL_NONE is returned if no data conversion is necessary, as occurs when the
application and driver have the same data model. DDI_MODEL_ILP32 is returned to a
driver that is compiled to the LP64 model and that communicates with a
32-bit application.
In the following example, the driver copies a data structure that contains a
user address. The data structure changes size from ILP32 to LP64. Accordingly, the
64-bit driver uses a 32-bit version of the structure when communicating with a
32-bit application.
Example 15-14 ioctl(9E) Routine to Support 32-bit Applications and 64-bit Applications
struct args32 {
uint32_t addr; /* 32-bit address in LP64 */
int len;
}
struct args {
caddr_t addr; /* 64-bit address in LP64 */
int len;
}
static int
xxioctl(dev_t dev, int cmd, intptr_t arg, int mode,
cred_t *credp, int *rvalp)
{
struct xxstate *xsp;
struct args a;
xsp = ddi_get_soft_state(statep, getminor(dev));
if (xsp == NULL) {
return (ENXIO);
}
switch (cmd) {
case XX_COPYIN_DATA:
switch(ddi_model_convert_from(mode)) {
case DDI_MODEL_ILP32:
{
struct args32 a32;
/* copy 32-bit args data shape */
if (ddi_copyin((void *)arg, &a32,
sizeof (struct args32), mode) != 0) {
return (EFAULT);
}
/* convert 32-bit to 64-bit args data shape */
a.addr = a32.addr;
a.len = a32.len;
break;
}
case DDI_MODEL_NONE:
/* application and driver have same data model. */
if (ddi_copyin((void *)arg, &a, sizeof (struct args),
mode) != 0) {
return (EFAULT);
}
}
/* continue using data shape in native driver data model. */
break;
case XX_COPYOUT_DATA:
/* copyout handling */
break;
default:
/* generic "ioctl unknown" error */
return (ENOTTY);
}
return (0);
}
Handling copyout() Overflow
Sometimes a driver needs to copy out a native quantity that no
longer fits in the 32-bit sized structure. In this case, the driver should
return EOVERFLOW to the caller. EOVERFLOW serves as an indication that the data
type in the interface is too small to hold the value to be
returned, as shown in the following example.
Example 15-15 Handling copyout(9F) Overflow
int
xxioctl(dev_t dev, int cmd, intptr_t arg, int mode,
cred_t *cr, int *rval_p)
{
struct resdata res;
/* body of driver */
switch (ddi_model_convert_from(mode & FMODELS)) {
case DDI_MODEL_ILP32: {
struct resdata32 res32;
if (res.size > UINT_MAX)
return (EOVERFLOW);
res32.size = (size32_t)res.size;
res32.flag = res.flag;
if (ddi_copyout(&res32,
(void *)arg, sizeof (res32), mode))
return (EFAULT);
}
break;
case DDI_MODEL_NONE:
if (ddi_copyout(&res, (void *)arg, sizeof (res), mode))
return (EFAULT);
break;
}
return (0);
}
