| Skip Navigation Links | |
| Exit Print View | |
|
Device Driver Tutorial Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Device Driver Tutorial Oracle Solaris 11.1 Information Library |
1. Introduction to Device Drivers
3. Reading and Writing Data in Kernel Memory
Displaying Data Stored in Kernel Memory
Writing Quote Of The Day Version 1
Building, Installing, and Using Quote Of The Day Version 1
Writing Quote Of The Day Version 2
Opening the Device, Closing the Device, and Getting Module Information
Modifying Data Stored in Kernel Memory
Writing Quote Of The Day Version 3
Attaching, Allocating Memory, and Initializing a Mutex and a Condition Variable
Checking for Changes, Cleaning Up, and Detaching
Allocating and Freeing Kernel Memory
Managing Thread Synchronization
Locking Rules for Quote Of The Day Version 3
Lock and Condition Variable Members of the State Structure
Creating and Destroying Locks and Condition Variables
Reporting and Setting Device Size and Re-initializing the Device
Quote Of The Day Version 3 Source
Building and Installing Quote Of The Day Version 3
Using Quote Of The Day Version 3
Exercising the Driver's I/O Controls
The sample code in this section creates a pseudo device that is controlled by the driver. The driver stores data in the device and makes the data available when the user accesses the device for reading.
This section first discusses the important code differences between these two versions of the Quote Of The Day driver. This section then shows you how you can access the device to cause the quotation to display.
The driver that controls the pseudo device is more complex than the driver shown in the previous section. This section first explains some important features of this version of the driver. This section then shows all the source for this driver.
The following list summarizes the differences between the two versions of the Quote Of The Day driver:
Version 2 of the driver defines a state structure that holds information about each instance of the device.
Version 2 defines a cb_ops(9S) structure and a more complete dev_ops(9S) structure.
Version 2 defines open(9E), close(9E), read(9E), getinfo(9E), attach(9E), and detach(9E) entry points.
Version 1 uses the cmn_err(9F) function to write a constant string to a system log in the _init(9E) entry point of the driver. The _init(9E) entry point is called when the driver is loaded. Version 2 uses the uiomove(9F) function to copy the quotation from kernel memory. The copied data is returned by the read(9E) entry point. The read(9E) entry point is called when the driver is accessed for reading.
Version 2 of the driver uses ASSERT(9F) statements to check the validity of data.
The following sections provide more detail about the additions and changes in Version 2 of the Quote Of The Day driver.
The _init(9E) and _fini(9E) entry points and all six new entry points defined in this driver maintain a soft state for the device. Most device drivers maintain state information with each instance of the device they control. An instance usually is a sub-device. For example, a disk driver might communicate with a hardware controller device that has several disk drives attached. See Retrieving Driver Soft State Information in Writing Device Drivers for more information about soft states.
This sample driver allows only one instance. The instance number is assigned in the configuration file. See Example 3-4. Most device drivers allow any number of instances of a device to be created. The system manages the device instance numbers, and the DDI soft state functions manage the instances.
The following flow gives an overview of how DDI soft state functions manage a state pointer and the state of a device instance:
The ddi_soft_state_init(9F) function initializes the state pointer. The state pointer is an opaque handle that enables allocation, deallocation, and tracking of a state structure for each instance of a device. The state structure is a user-defined type that maintains data specific to this instance of the device. In this example, the state pointer and state structure are declared after the entry point declarations. See qotd_state_head and qotd_state in Example 3-3.
The ddi_soft_state_zalloc(9F) function uses the state pointer and the device instance to create the state structure for this instance.
The ddi_get_soft_state(9F) function uses the state pointer and the device instance to retrieve the state structure for this instance of the device.
The ddi_soft_state_free(9F) function uses the state pointer and the device instance to free the state structure for this instance.
The ddi_soft_state_fini(9F) function uses the state pointer to destroy the state pointer and the state structures for all instances of this device.
The ddi_soft_state_zalloc(9F), ddi_get_soft_state(9F), and ddi_soft_state_free(9F) functions coordinate access to the underlying data structures in a way that is safe for multithreading. No additional locks should be necessary.
The _init(9E) entry point first calls the ddi_soft_state_init(9F) function to initialize the soft state. If the soft state initialization fails, that error code is returned. If the soft state initialization succeeds, the _init(9E) entry point calls the mod_install(9F) function to load a new module. If the module install fails, the _init(9E) entry point calls the ddi_soft_state_fini(9F) function and returns the error code from the failed module install.
Your code must undo everything that it does. You must call ddi_soft_state_fini(9F) if the module install fails because the _init(9E) call succeeded and created a state pointer.
The _fini(9E) entry point must undo everything the _init(9E) entry point did. The _fini(9E) entry point first calls the mod_remove(9F) function to remove the module that the _init(9E) entry point installed. If the module remove fails, that error code is returned. If the module remove succeeds, the _fini(9E) entry point calls the ddi_soft_state_fini(9F) function to destroy the state pointer and the state structures for all instances of this device.
The attach(9E) entry point first calls the ddi_get_instance(9F) function to retrieve the instance number of the device information node. The attach(9E) entry point uses this instance number to call the ddi_soft_state_zalloc(9F), ddi_get_soft_state(9F), and ddi_create_minor_node(9F) functions.
The attach(9E) entry point calls the ddi_soft_state_zalloc(9F) function to create a state structure for this device instance. If creation of the soft state structure fails, attach(9E) writes an error message to a system log and returns failure. This device instance is not attached. If creation of the soft state structure succeeds, attach(9E) calls the ddi_get_soft_state(9F) function to retrieve the state structure for this device instance.
If retrieval of the state structure fails, attach(9E) writes an error message to a system log, calls the ddi_soft_state_free(9F) function to destroy the state structure that was created by ddi_soft_state_zalloc(9F), and returns failure. This device instance is not attached. If retrieval of the state structure succeeds, attach(9E) calls the ddi_create_minor_node(9F) function to create the device node.
At the top of this driver source file, a constant named QOTD_NAME is defined that holds the string name of the device. This constant is one of the arguments that is passed to ddi_create_minor_node(9F). If creation of the device node fails, attach(9E) writes an error message to a system log, calls the ddi_soft_state_free(9F) function to destroy the state structure that was created by ddi_soft_state_zalloc(9F), calls the ddi_remove_minor_node(9F) function, and returns failure. This device instance is not attached.
If creation of the device node succeeds, this device instance is attached. The attach(9E) entry point assigns the instance number that was retrieved with ddi_get_instance(9F) to the instance member of the state structure for this instance. Then attach(9E) assigns the dev_info structure pointer that was passed in the attach(9E) call to the dev_info structure pointer member of the state structure for this instance. The ddi_report_dev(9F) function writes a message in the system log file when the device is added or when the system is booted. The message announces this device as shown in the following example:
% dmesg date time machine pseudo: [ID 129642 kern.info] pseudo-device: qotd_20 date time machine genunix: [ID 936769 kern.info] qotd_20 is /pseudo/qotd_2@0
The detach(9E) entry point first calls the ddi_get_instance(9F) function to retrieve the instance number of the device information node. The detach(9E) entry point uses this instance number to call the ddi_soft_state_free(9F) function to destroy the state structure that was created by ddi_soft_state_zalloc(9F) in the attach(9E) entry point. The detach(9E) entry point then calls the ddi_remove_minor_node(9F) function to remove the device that was created by ddi_create_minor_node(9F) in the attach(9E) entry point.
The open(9E) and close(9E) entry points are identical in this sample driver. In each case, the entry point first calls the getminor(9F) function to retrieve the minor number of the device. Then each entry point uses this instance number to call the ddi_get_soft_state(9F) function to retrieve the state structure for this device instance. If no state structure is retrieved, an error code is returned. If a state structure is retrieved, the open(9E) and close(9E) entry points both verify the type of this device. If this device is not a character device, the EINVAL (invalid) error code is returned.
If the user wants device information for this device instance, the getinfo(9E) entry point returns the device information from the state structure. If the user wants the instance number of this device instance, the getinfo(9E) entry point uses the getminor(9F) function to return the minor number.
The read(9E) entry point first calls the getminor(9F) function to retrieve the minor number of the device. The read(9E) entry point uses this instance number to call the ddi_get_soft_state(9F) function to retrieve the state structure for this device instance. If no state structure is retrieved, read(9E) returns an error code. If a state structure is retrieved, read(9E) calls the uiomove(9F) function to copy the quotation from the driver to the uio(9S) I/O request structure.
Version 2 of the driver uses ASSERT(9F) statements to check the validity of data. If the asserted expression is true, the ASSERT(9F) statement does nothing. If the asserted expression is false, the ASSERT(9F) statement writes an error message to the console and causes the system to panic.
To use ASSERT(9F) statements, include the sys/debug.h header file in your source and define the DEBUG preprocessor symbol. If you do not define the DEBUG preprocessor symbol, then the ASSERT(9F) statements do nothing. Simply recompile to activate or inactivate ASSERT(9F) statements.
Enter the source code shown in the following example into a text file named qotd_2.c.
Example 3-3 Quote Of The Day Version 2 Source File
#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/uio.h>
#include <sys/stat.h>
#include <sys/modctl.h>
#include <sys/conf.h>
#include <sys/devops.h>
#include <sys/debug.h>
#include <sys/cmn_err.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
#define QOTD_NAME "qotd"
#define QOTD_MAXLEN 128
static const char qotd[QOTD_MAXLEN]
= "You can't have everything. \
Where would you put it? - Steven Wright\n";
static void *qotd_state_head;
struct qotd_state {
int instance;
dev_info_t *devi;
};
static int qotd_getinfo(dev_info_t *, ddi_info_cmd_t, void *, void **);
static int qotd_attach(dev_info_t *, ddi_attach_cmd_t);
static int qotd_detach(dev_info_t *, ddi_detach_cmd_t);
static int qotd_open(dev_t *, int, int, cred_t *);
static int qotd_close(dev_t, int, int, cred_t *);
static int qotd_read(dev_t, struct uio *, cred_t *);
static struct cb_ops qotd_cb_ops = {
qotd_open, /* cb_open */
qotd_close, /* cb_close */
nodev, /* cb_strategy */
nodev, /* cb_print */
nodev, /* cb_dump */
qotd_read, /* cb_read */
nodev, /* cb_write */
nodev, /* cb_ioctl */
nodev, /* cb_devmap */
nodev, /* cb_mmap */
nodev, /* cb_segmap */
nochpoll, /* cb_chpoll */
ddi_prop_op, /* cb_prop_op */
(struct streamtab *)NULL, /* cb_str */
D_MP | D_64BIT, /* cb_flag */
CB_REV, /* cb_rev */
nodev, /* cb_aread */
nodev /* cb_awrite */
};
static struct dev_ops qotd_dev_ops = {
DEVO_REV, /* devo_rev */
0, /* devo_refcnt */
qotd_getinfo, /* devo_getinfo */
nulldev, /* devo_identify */
nulldev, /* devo_probe */
qotd_attach, /* devo_attach */
qotd_detach, /* devo_detach */
nodev, /* devo_reset */
&qotd_cb_ops, /* devo_cb_ops */
(struct bus_ops *)NULL, /* devo_bus_ops */
nulldev, /* devo_power */
ddi_quiesce_not_needed, /* devo_quiesce */
};
static struct modldrv modldrv = {
&mod_driverops,
"Quote of the Day 2.0",
&qotd_dev_ops};
static struct modlinkage modlinkage = {
MODREV_1,
(void *)&modldrv,
NULL
};
int
_init(void)
{
int retval;
if ((retval = ddi_soft_state_init(&qotd_state_head,
sizeof (struct qotd_state), 1)) != 0)
return retval;
if ((retval = mod_install(&modlinkage)) != 0) {
ddi_soft_state_fini(&qotd_state_head);
return (retval);
}
return (retval);
}
int
_info(struct modinfo *modinfop)
{
return (mod_info(&modlinkage, modinfop));
}
int
_fini(void)
{
int retval;
if ((retval = mod_remove(&modlinkage)) != 0)
return (retval);
ddi_soft_state_fini(&qotd_state_head);
return (retval);
}
/*ARGSUSED*/
static int
qotd_getinfo(dev_info_t *dip, ddi_info_cmd_t cmd, void *arg, void **resultp)
{
struct qotd_state *qsp;
int retval = DDI_FAILURE;
ASSERT(resultp != NULL);
switch (cmd) {
case DDI_INFO_DEVT2DEVINFO:
if ((qsp = ddi_get_soft_state(qotd_state_head,
getminor((dev_t)arg))) != NULL) {
*resultp = qsp->devi;
retval = DDI_SUCCESS;
} else
*resultp = NULL;
break;
case DDI_INFO_DEVT2INSTANCE:
*resultp = (void *)getminor((dev_t)arg);
retval = DDI_SUCCESS;
break;
}
return (retval);
}
static int
qotd_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
int instance = ddi_get_instance(dip);
struct qotd_state *qsp;
switch (cmd) {
case DDI_ATTACH:
if (ddi_soft_state_zalloc(qotd_state_head, instance)
!= DDI_SUCCESS) {
cmn_err(CE_WARN, "Unable to allocate state for %d",
instance);
return (DDI_FAILURE);
}
if ((qsp = ddi_get_soft_state(qotd_state_head, instance))
== NULL) {
cmn_err(CE_WARN, "Unable to obtain state for %d",
instance);
ddi_soft_state_free(dip, instance);
return (DDI_FAILURE);
}
if (ddi_create_minor_node(dip, QOTD_NAME, S_IFCHR, instance,
DDI_PSEUDO, 0) != DDI_SUCCESS) {
cmn_err(CE_WARN, "Cannot create minor node for %d",
instance);
ddi_soft_state_free(dip, instance);
ddi_remove_minor_node(dip, NULL);
return (DDI_FAILURE);
}
qsp->instance = instance;
qsp->devi = dip;
ddi_report_dev(dip);
return (DDI_SUCCESS);
case DDI_RESUME:
return (DDI_SUCCESS);
default:
return (DDI_FAILURE);
}
}
static int
qotd_detach(dev_info_t *dip, ddi_detach_cmd_t cmd)
{
int instance = ddi_get_instance(dip);
switch (cmd) {
case DDI_DETACH:
ddi_soft_state_free(qotd_state_head, instance);
ddi_remove_minor_node(dip, NULL);
return (DDI_SUCCESS);
case DDI_SUSPEND:
return (DDI_SUCCESS);
default:
return (DDI_FAILURE);
}
}
/*ARGSUSED*/
static int
qotd_open(dev_t *devp, int flag, int otyp, cred_t *credp)
{
int instance = getminor(*devp);
struct qotd_state *qsp;
if ((qsp = ddi_get_soft_state(qotd_state_head, instance)) == NULL)
return (ENXIO);
ASSERT(qsp->instance == instance);
if (otyp != OTYP_CHR)
return (EINVAL);
return (0);
}
/*ARGSUSED*/
static int
qotd_close(dev_t dev, int flag, int otyp, cred_t *credp)
{
struct qotd_state *qsp;
int instance = getminor(dev);
if ((qsp = ddi_get_soft_state(qotd_state_head, instance)) == NULL)
return (ENXIO);
ASSERT(qsp->instance == instance);
if (otyp != OTYP_CHR)
return (EINVAL);
return (0);
}
/*ARGSUSED*/
static int
qotd_read(dev_t dev, struct uio *uiop, cred_t *credp)
{
struct qotd_state *qsp;
int instance = getminor(dev);
if ((qsp = ddi_get_soft_state(qotd_state_head, instance)) == NULL)
return (ENXIO);
ASSERT(qsp->instance == instance);
return (uiomove((void *)qotd, min(uiop->uio_resid, strlen(qotd)),
UIO_READ, uiop));
}
Enter the configuration information shown in the following example into a text file named qotd_2.conf.
Example 3-4 Quote Of The Day Version 2 Configuration File
name="qotd_2" parent="pseudo" instance=0;
Version 2 of the driver uses ASSERT(9F) statements to check the validity of data. To use ASSERT(9F) statements, include the sys/debug.h header file in your source and define the DEBUG preprocessor symbol.
Compile and link the driver. If you use ASSERT(9F) statements to check the validity of data, you must define the DEBUG preprocessor symbol:
% cc -D_KERNEL -DDEBUG -c qotd_2.c % ld -r -o qotd_2 qotd_2.o
The following example shows compiling and linking for a 32-bit architecture if you are not using ASSERT(9F) statements:
% cc -D_KERNEL -c qotd_2.c % ld -r -o qotd_2 qotd_2.o
Make sure you are user root when you install the driver.
Copy the driver binary to the /tmp directory as discussed in Building and Installing the Template Driver.
# cp qotd_2 /tmp # ln -s /tmp/qotd_2 /usr/kernel/drv/qotd_2
Copy the configuration file to the kernel driver area of the system.
# cp qotd_2.conf /usr/kernel/drv
In a separate window, enter the following command:
% tail -f /var/adm/messages
Make sure you are user root when you load the driver. Use the add_drv(1M) command to load the driver:
# add_drv qotd_2
You should see the following messages in the window where you are viewing /var/adm/messages:
date time machine pseudo: [ID 129642 kern.info] pseudo-device: devinfo0 date time machine genunix: [ID 936769 kern.info] devinfo0 is /pseudo/devinfo@0 date time machine pseudo: [ID 129642 kern.info] pseudo-device: qotd_20 date time machine genunix: [ID 936769 kern.info] qotd_20 is /pseudo/qotd_2@0
When this version of the Quote Of The Day driver loads, it does not display its quotation. The qotd_1 driver wrote a message to a system log through its _init(9E) entry point. This qotd_2 driver stores its data and makes the data available through its read(9E) entry point.
You can use the modinfo(1M) command to display the module information for this version of the Quote Of The Day driver. The module name is the value you entered for the second member of the modldrv structure. The value 96 is the major number of this module.
% modinfo | grep qotd 182 ed115948 754 96 1 qotd_2 (Quote of the Day 2.0) % grep qotd /etc/name_to_major qotd_1 94 qotd_2 96
This driver also is the most recent module listed by prtconf(1M) in the pseudo device section:
% prtconf -P | grep qotd
qotd_1, instance #0 (driver not attached)
qotd_2, instance #0
When you access this qotd_2 device for reading, the command you use to access the device retrieves the data from the device node. The command then displays the data in the same way that the command displays any other input. To get the name of the device special file, look in the /devices directory:
% ls -l /devices/pseudo/qotd* crw------- 1 root sys 96, 0 date time /devices/pseudo/qotd_2@0:qotd
This output shows that qotd_2@0:qotd is a character device. This listing also shows that only the root user has permission to read or write this device. Make sure you are user root when you test this driver. To test the qotd_2 driver, you can use the more(1) command to access the device file for reading:
# more /devices/pseudo/qotd_2@0:qotd You can't have everything. Where would you put it? - Steven Wright You can't have everything. Where would you put it? - Steven Wright
|