devctl(),devctlv()

Use these macros to set up the device-control commands:

__DIOF(class, cmd, data)

Get information from the device.

__DION(class, cmd)

Send a command with no associated data.

__DIOT(class, cmd, data)

Pass information to the device.

__DIOTF(class, cmd, data)

Pass some information to the device, and get some from it.

The arguments to these macros are:

class

The major category for the command. The device-control commands are divided into the following classes to make organization easier:

• _DCMD_ALL — Common (all I/O servers).
• _DCMD_CAM — Low-level (Common Access Method) devices, such as disks or CD-ROMs.
• _DCMD_CHR — Character devices.
• _DCMD_FSYS, _DCMD_BLK — Filesystem/block I/O managers.
• _DCMD_INPUT — Input devices.
• _DCMD_IP — Internet Protocol.
• _DCMD_MEM — Memory card.
• _DCMD_MISC — Miscellaneous commands.
• _DCMD_MIXER — Mixer (Audio).
• _DCMD_NET — Network devices.
• _DCMD_PROC — Process manager.

cmd

The specific command in the class.

data

The type of data to pass to and/or from the device. The dev_data_ptr argument to devctl() must be a pointer to this type of data, and n_bytes is usually the size of this type of data.

Note:

The size of the structure that's passed as the last field to the __DIO* macros must be less than 2^14 == 16 KB. Anything larger than this interferes with the upper two directional bits.

Resource managers can use the following macros, which are defined in <devctl.h>, when handling commands:

get_device_command(cmd)

Extract the class and the specific device command from cmd (i.e., strip off the data type and the direction).

get_device_direction(cmd)

Get the direction of the command (DEVDIR_TO, DEVDIR_FROM, DEVDIR_TOFROM, or DEVDIR_NONE).

get_device_size(cmd)

Get the size of the device control structure used to define the dcmd.

Here's a quick example of setting and unsetting RTS (Request to Send) on a serial port:

/* For "devctl()" */
#include <devctl.h>
#include <sys/dcmd_chr.h>

/* For "open()" */
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

/* For "strerror()" */
#include <string.h>

/* For Errors */
#include <stdlib.h>
#include <stdio.h>

int check_RTS(int fd);

int main(void)
{
    int data = 0, fd, error;

    if((fd = open ("/dev/ser2", O_RDONLY)) == -1)
    {
     fprintf(stderr,
        "Error with open() on /dev/ser2.  Make sure it exists.\n");
     perror (NULL);
     exit(EXIT_FAILURE);
    }

    check_RTS(fd);

    /* Let's turn ON RTS now. */
    data = _CTL_RTS_CHG | _CTL_RTS;

    if (error = devctl (fd, DCMD_CHR_SERCTL, &data,
                   sizeof(data), NULL))
    {
    fprintf(stderr, "Error setting RTS: %s\n",
        strerror ( error ));
        exit(EXIT_FAILURE);
    }
    /* RTS should now be ON. */

    check_RTS(fd);

    sleep (2);


    /* Now let's turn RTS OFF. */
    data = _CTL_RTS_CHG | 0;

    if (error = devctl (fd, DCMD_CHR_SERCTL, &data,
                   sizeof(data), NULL))
    {
        fprintf(stderr, "Error setting RTS: %s\n",
            strerror ( error ));
        exit(EXIT_FAILURE);
    }
    /* RTS should now be OFF. */

    check_RTS(fd);

    close(fd);

    return (1);
}


int check_RTS(int fd)
{
    int data = 0, error;

    /*
     Let's see if RTS is set by using devctl() to get
     line status information.
    */
    if (error = devctl (fd, DCMD_CHR_LINESTATUS, &data,
                        sizeof(data), NULL))
    {
       fprintf(stderr, "Error getting RTS: %s\n",
           strerror ( error ));
       exit(EXIT_FAILURE);
    }

    if (data & _LINESTATUS_SER_RTS)
        printf("RTS is SET!\n");
    else
        printf("RTS is NOT set\n");

    return(1);
}

When setting RTS, data is assigned a value that's sent to the device via devctl().

The key lines in this example are the same as in the last example; they focus around the data variable. This value is just a simple integer value that's passed into the devctl() function. The data variable is assigned its values by simply performing a bitwise OR to the predefined values in the </usr/include/sys/dcmd_chr.h> header. Note the values used in the bitwise OR:

• _CONCTL_NUM_CHG (Console Control Num Lock Change) ORed together with _CONCTL_NUM (Console Control Num Lock) turns on Num Lock.
• _CONCTL_NUM_CHG on its own turns off Num Lock.

This also applies for the other either/or values in the <dcmd_chr.h> header.

/* For "devctl()" */
#include <devctl.h>
#include <sys/dcmd_chr.h>

/* For "open()" */
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

/* For "strerror()" */
#include <string.h>

/* For Errors */
#include <stdlib.h>
#include <stdio.h>


int main(void)
{
    int data, fd, toggle = 1, error;

    /* Open the device we wish to manipulate. */
    if((fd = open ("/dev/kbd", O_RDONLY)) == -1)
    {
     fprintf(stderr,
        "Error with open() on /dev/kbd.  Make sure it exists.\n");
     perror (NULL);
     exit(EXIT_FAILURE);
    }

    while(1)
    {
    switch(toggle)
    {
        case 1:
        {
          /*
           Turn on Num Lock and make sure that 
           Caps and Scroll lock are turned off.
          */
          data = (_CONCTL_NUM_CHG | _CONCTL_NUM) | _CONCTL_CAPS_CHG |
                 _CONCTL_SCROLL_CHG;
          break;
        }
        case 2:
        {
          /*
           Turn off Num Lock and now turn on Caps Lock 
           (Scroll lock is already off).
          */
          data = _CONCTL_NUM_CHG | (_CONCTL_CAPS_CHG | _CONCTL_CAPS);
          break;
        }
        case 3:
        {
          /*
           Turn off Caps lock and turn on Scroll lock 
           (Num lock is already off).
          */
          data = _CONCTL_CAPS_CHG | (_CONCTL_SCROLL_CHG | _CONCTL_SCROLL);
          toggle = 0;
          break;
        }
    }

    /* Explanation below. */
    if (error = devctl (fd, DCMD_CHR_SERCTL, &data,
                        sizeof(data), NULL))
    {
        fprintf(stderr, "Error setting KBD: %s\n",
            strerror ( error ));
        exit(EXIT_FAILURE);
    }

    sleep(1);
    toggle++;
    }

    return (1);
}

Here's a quick explanation of the above devctl() call:

devctl (fd, DCMD_CHR_SERCTL, &data, sizeof(data), NULL)

In this code, tcdropline(), which is used to disconnect a communications line, uses devctl() (this is the actual source code, tcdropline() is a standard library function):

#include <termios.h>
#include <devctl.h>
#include <errno.h>
#include <sys/dcmd_chr.h>

int tcdropline(int fd, int duration) {
    int error; 

    duration = ((duration ? duration : 300) << 16) | _SERCTL_DTR_CHG | 0;

    if ((error = devctl(fd, DCMD_CHR_SERCTL, &duration, 
                        sizeof duration, 0)) != EOK) {
       if (error == ENOSYS) {
          errno = ENOTTY;
       }
       return -1;
    }
    return 0;
}