DRVCTL(4)

DRVCTL(4) | Device Drivers Manual | DRVCTL(4)

# NAME

`drvctl` —
driver control device

# SYNOPSIS

`pseudo-device drvctl`

# DESCRIPTION

The `drvctl` driver allows to control some autoconf(9) operations from userland through the /dev/drvctl device and the drvctl(8) command.

The driver supports the following ioctl(2) operations.

DRVSUSPENDDEV
DRVRESUMEDEV
  Invoke power management functions for a named driver that has registered itself with the pmf(9) framework. The ioctl argument specifies the driver name as:

      struct devpmargs {
              char devname[16];
              uint32_t flags;
      };

  The flag `DEVPM_F_SUBTREE` lets the function recurse over all children of that driver.

DRVLISTDEV
  Return a list of child devices attached to the named driver. The ioctl argument specifies the driver name as:

      struct devlistargs {
              char l_devname[16];
              char (*l_childname)[16];
              size_t l_children;
      };

  The names for up to `l_children` child devices are copied to the `l_childname` array. If there is no error, the ioctl returns the total number of children. Normally you would call `DRVLISTDEV` once with `l_children` set to zero, allocate a buffer for enough 16-character strings and call `DRVLISTDEV` again to fill the buffer.

DRVDETACHDEV
  Detach the named driver and all its autoconfigured children. The ioctl argument specifies the driver name as:

      struct devdetachargs {
              char devname[16];
      };

DRVSCANBUS
  Invoke the rescan method of the named driver to locate child devices. The ioctl argument specifies the driver name as:

      struct devrescanargs {
              char busname[16];
              char ifattr[16];
              unsigned int numlocators;
              int *locators;
      };

  Some device drivers attach children to specific interface attributes, a zero length `ifattr` represents that no interface attribute should be used. The rescan can also be limited to driver-specific locators.

DRVCTLCOMMAND
  Send a command formatted as a property list. The property list includes all arguments like the driver name, the result is again a property list. Currently the only supported command is "get-properties", the property list is constructed like:

      const char *device = "sd0";
      const char *command = "get-properties";

      prop_string_t s;
      prop_dictionary_t c, a;

      c = prop_dictionary_create();
      a = prop_dictionary_create();

      s = prop_string_create_cstring_nocopy(command);
      prop_dictionary_set(c, "drvctl-command", s);
      prop_object_release(s);

      s = prop_string_create_cstring(device);
      prop_dictionary_set(a, "device-name", s);
      prop_object_release(s);

      prop_dictionary_set(c, "drvctl-arguments", a);
      prop_object_release(a);

  The command must be sent with prop_dictionary_sendrecv_ioctl(3). The resulting property list contains the numeric attribute `drvctl-error`, which corresponds to an `errno` value, and the dictionary `drvctl-result-data`. The contents of the dictionary depends on the queried driver.

DRVGETEVENT
  Return the next queued autoconfig event formatted as a property list. The request needs to be sent with prop_dictionary_recv_ioctl(3). The resulting property list contains the string attributes `event, device` and `parent`. Currently the events "device-attach" and "device-detach" are generated by the autoconf(9) framework.

  If /dev/drvctl was opened with `O_NONBLOCK` and there is no event queued, the call returns immediately with `EWOULDBLOCK`, otherwise it waits for the next event.

All names used in the ioctl arguments are zero-terminated strings. A driver name is the name of a driver instance with the appended unit number like `sd0`, `atabus3`, `...`

# FILES

/dev/drvctl
  `drvctl` access device

# SEE ALSO

ioctl(2), prop_send_ioctl(3), proplib(3), devpubd(8), drvctl(8), autoconf(9)

# HISTORY

The /dev/drvctl device appeared in NetBSD 3.0 but was only added to the GENERIC configuration in NetBSD 5.0.

May 13, 2015 | NetBSD 10.1