The echo_write function acquires a character string from user space and stores it. Here is its function definition (again):

static int
echo_write(struct cdev *dev, struct uio *uio, int ioflag)
{
        int error = 0;

        error = copyin(uio->uio_iov->iov_base,
 echo_message->buffer,
            MIN(uio->uio_iov->iov_len, BUFFER_SIZE - 1));
        if (error != 0) {
                uprintf("Write failed.
");
                return (error);
        }

      *(echo_message->buffer +
            MIN(uio->uio_iov->iov_len, BUFFER_SIZE - 1)) = 0;

      echo_message->length = MIN(uio->uio_iov->iov_len, BUFFER_SIZE - 1);

        return (error);
}

Here, struct uio describes a character string in motion—the variables iov_base and iov_len specify the character string’s base address and length, respectively.

So, this function starts by copying a character string from user space to kernel space. At most, 'BUFFER_SIZE - 1' bytes of data are copied. Once this is done, the character string is null-terminated, and its length (minus the null terminator) is recorded.

The echo_read function returns the stored character string to user space. Here is its function definition (again):

static int
echo_read(struct cdev *dev, struct uio *uio, int ioflag)
{
        int error = 0;
        int amount;

        amount = MIN(uio->uio_resid,
            (echo_message->length - uio->uio_offset > 0) ?
            echo_message->length - uio->uio_offset : 0);

        error = uiomove(echo_message->buffer + uio->uio_offset,
 amount,
            uio);
        if (error != 0)
                uprintf("Read failed.
");

        return (error);
}

Here, the variables uio_resid and uio_offset specify the amount of data remaining to be transferred and an offset into the character string, respectively.

So, this function first determines the number of characters to return—either the amount the user requests or all of it. Then echo_read transfers that number from kernel space to user space.

The echo_modevent function is the module event handler for this character driver. Here is its function definition (again):

static int
echo_modevent(module_t mod __unused, int event, void *arg __unused)
{
        int error = 0;

        switch (event) {
        case MOD_LOAD:
              echo_message = malloc(sizeof(echo_t), M_TEMP, M_WAITOK);
                echo_dev = make_dev(&echo_cdevsw, 0, UID_ROOT, GID_WHEEL,
                    0600, "echo");
                uprintf("Echo driver loaded.
");
                break;
        case MOD_UNLOAD:
              destroy_dev(echo_dev);
              free(echo_message, M_TEMP);
                uprintf("Echo driver unloaded.
");
                break;
        default:
                error = EOPNOTSUPP;
                break;
        }

        return (error);
}

On module load, this function first calls malloc to allocate sizeof(echo_t) bytes of memory. Then it calls make_dev to create a character device node named echo under /dev. Note that when make_dev returns, the character device is “live” and its d_foo functions can be executed. Consequently, if I had called make_dev ahead of malloc, echo_write or echo_read could be executed before echo_message points to valid memory, which would be disastrous. The point is: Unless your driver is completely ready, don’t call make_dev.

On module unload, this function first calls destroy_dev to destroy the echo device node. Then it calls free to release the allocated memory.

The DEV_MODULE macro is defined in the <sys/conf.h> header as follows:

#define DEV_MODULE(name, evh, arg)                                      
  static moduledata_t name##_mod = {                                      
      #name,                                                              
      evh,                                                                
      arg                                                                 
  };                                                                      
 DECLARE_MODULE(name, name##_mod, SI_SUB_DRIVERS, SI_ORDER_MIDDLE)

As you can see, DEV_MODULE merely wraps DECLARE_MODULE. So Example 1-2 could have called DECLARE_MODULE, but DEV_MODULE is cleaner (and it saves you some keystrokes).

Now that we’ve walked through Example 1-2, let’s give it a try:

$ sudo kldload ./echo.ko
Echo driver loaded.
$ ls -l /dev/echo
crw-------  1 root  wheel    0,  95 Jun  4 23:23 /dev/echo
$ su
Password:
# echo "DON'T PANIC" > /dev/echo
Opening echo device.
Closing echo device.
# cat /dev/echo
Opening echo device.
DON'T PANIC
Closing echo device.

Unsurprisingly, it works. Before this chapter is concluded, a crucial topic bears mentioning.