DEV(10.2)                                               DEV(10.2)

     NAME
          Dev - device driver interface

     SYNOPSIS
          struct Dev
          {
              int dc;
              char*   name;

              void    (*reset)(void);        /* native only */
              void    (*init)(void);
              void    (*shutdown)(void);     /* native */
              Chan*   (*attach)(char *spec);
              Walkqid*  (*walk)(Chan *c, Chan *nc, char **name, int nname);
              int     (*stat)(Chan *c, uchar *db, int dbsize);
              Chan*   (*open)(Chan *c, int mode);
              void    (*create)(Chan *c, char *name, int mode, ulong perm);
              void    (*close)(Chan *c);
              long    (*read)(Chan *c, void *buf, long nbytes, vlong offset);
              Block*  (*bread)(Chan *c, long nbytes, ulong offset);
              long    (*write)(Chan *c, void*, long, vlong offset);
              long    (*bwrite)(Chan *c, Block *b, ulong offset);
              void    (*remove)(Chan *c);
              int     (*wstat)(Chan *c, uchar *db, int dbsize);
              void    (*power)(int on);        /* native only */
              int     (*config)(int on, char *spec, DevConf *cf); /* native */
          };

     DESCRIPTION
          Every device driver serves a unique name space that
          represents to the corresponding device(s).  Applications act
          on the space using the operations of sys-bind(2), sys-
          open(2), sys-read(2), sys-stat(2), and other system calls.
          Within the kernel, the Dev structure defines the interface
          between the kernel and a device driver for all operations on
          that driver's name space.

          Dev identifies the driver, and lists a set of C functions
          that are the driver's operations.  Most are operations on
          the Chan type that is the kernel representation of a file or
          directory active in a name space.  The kernel converts sys-
          tem calls acting on file descriptors into calls to a
          device's Dev operations acting on channel values.  All chan-
          nel values presented through the Dev interface are associ-
          ated with the corresponding device driver: for channel c,
          c->type specifies that driver.  Within the driver, the
          c->qid.path of a channel c identifies a file in the driver's
          name space, or even a client-specific instance of a file
          (eg, for multiplexors such as ip(3)). The interpretation of
          the path is completely determined by the driver.

     DEV(10.2)                                               DEV(10.2)

          A device driver in the source file devx.c exports an ini-
          tialised instance of Dev xdevtab.  For instance, devcons.c
          contains the global initialiser:

               Dev consdevtab = {
                   'c',
                   "cons",

                   devreset,
                   consinit,
                   devshutdown,
                   consattach,
                   conswalk,
                   consstat,
                   consopen,
                   devcreate,
                   consclose,
                   consread,
                   devbread,
                   conswrite,
                   devbwrite,
                   devremove,
                   devwstat,
               };

          The kernel accesses the driver only through its Dev struc-
          ture, and consequently entry points such as consinit,
          consread, etc. can (and should) be declared static, and thus
          local to the file.

          The following elements of Dev identify the driver:

          dc   The device's type, represented by a Unicode character
               (`rune') that must be unique amongst those in a given
               kernel (and ideally for a given platform).  Its value
               is the value of Dir.dtype in the result of a sys-
               stat(2) applied to any file in the device.

          name The name that identifies the driver in a kernel config-
               uration file and in /dev/drivers (see cons(3)).

          All the other entries are functions.  In many cases, the
          values given in a device's Dev will be the default opera-
          tions provided by devattach(10.2).

          reset()
               Called once during system initialisation by the native
               kernel's main after initialising all supporting subsys-
               tems, including memory allocation, traps, screen, MMU
               (if used), but with interrupts disabled, and before any
               kernel process environment has been established.  Typi-
               cally used on some platforms to force some devices into

     DEV(10.2)                                               DEV(10.2)

               a sane state before interrupts are enabled.

          init()
               Called once during system initialisation in the context
               of the first kernel process, with interrupts enabled,
               before the virtual machine has been started.

          shutdown()
               Called once in native kernels during system shut down.
               Used on only a few platforms to force a device into a
               state that will allow it to function correctly during
               and after a soft reboot (eg, without doing a full sys-
               tem hardware reset).

          attach(spec)
               Called on each new attach to the device (eg, a refer-
               ence to #c by sys-bind(2)). Spec is the string follow-
               ing the device character and before a subsequent `/' in
               the bind request.  It is the empty string for most
               devies.  If the attach is successful, attach should
               return a Chan the refers to the root of the tree served
               by the device driver.  Normally, it will suffice to
               return the value of devattach(10.2).

          walk(c, nc, name, nname)
               Walks existing channel c from its current position in
               the device tree to that specified by the path repre-
               sented by name[0], ...  name[nname-1].  The driver must
               interpret `..'  as a walk from the current position one
               level up towards the root of the device tree.  The
               result is represented by a dynamically-allocated
               Walkqid value, with contents as described in
               devattach(10.2). Most drivers simply pass parameters on
               to devwalk in devattach(10.2) and return its result.

          stat(c, db, nbytes)
               Fill db with stat(5) data describing the file refer-
               enced by c. Nbytes gives the size of db; if the data
               will not fit, return the value specified for convD2M in
               styx(10.2). Most drivers simply pass parameters on to
               devstat in devattach(10.2); a few fill a local copy of
               a Dir structure, and call convD2M to store the
               machine-independent representation in db.

          open(c, mode)
               Open the file represented by Chan c, in the given mode
               (see sys-open(2)), and if successful, return a Chan
               value representing the result (usually c). Many drivers
               simply apply devopen of devattach(10.2). Exclusive use
               drivers might check and increment a reference count.

          create(c, name, mode, perm)

     DEV(10.2)                                               DEV(10.2)

               C should be a directory.  Create a new file name in
               that directory, with permissions perm, opened with the
               given mode. If successful, make c refer to the newly
               created file.  Most drivers return an error on all cre-
               ation attempts, by specifying devcreate of
               devattach(10.2) in the Dev table.

          close(c)
               Close channel c. This must be implemented by all
               drivers; there is no default, although the function
               often is a no-op.  Exclusive use drivers might decre-
               ment a reference count.

          read(c, buf, nbytes, offset)
               Implement a sys-read(2) of nbytes of data from the
               given offset in file c, and if successful, place the
               data in buf, and return the number of bytes read, which
               must be no greater than nbytes. Devices sometimes
               ignore the offset. All device drivers must implement
               read; there is no default.  Note that if c is a direc-
               tory, the data has an array of stat(5) data listing the
               directory contents, in the format prescribed by
               read(5). Most drivers have devdirread of
               devattach(10.2) do the work when c is the root direc-
               tory of the device's tree.

          bread(c, nbytes, offset)
               Implement a sys-read(2) of nbytes of data from the
               given offset in file c, and if successful return the
               data in a Block (see allocb(10.2) and qio(10.2)). Most
               drivers use the default devbread provided by
               devattach(10.2), and nearly all ignore the offset in
               any case.  Drivers that manipulate Blocks internally,
               such as ip(3), ssl(3) and similar protocol devices, and
               drivers that are likely to provide data to those
               devices, will provide a devbread implementation so as
               to reduce the number of times the data is copied.

          write(c, buf, nbytes, offset)
               Implement a write of nbytes of data from buf to file c,
               which must not be a directory, starting at the given
               byte offset. Return the number of bytes actually writ-
               ten.  There is no default, but drivers that do not
               implement writes to any of their files can simply call
               error(Eperm) to signal an error.

          bwrite(c, b, offset)
               Similar to the write entry point, but the data is con-
               tained in a Block b (see allocb(10.2)). B should be
               freed before return, whether the driver signals an
               error or not.  Most drivers use the default devbwrite
               from devattach(10.2), which calls the driver's write

     DEV(10.2)                                               DEV(10.2)

               entry point using the data in b. Drivers that manipu-
               late Blocks internally, such as ip(3), ssl(3) and simi-
               lar protocol devices, will provide a devbwrite imple-
               mentation so as to avoid copying the data needlessly.

          remove(c)
               Remove the file referenced by c. Most drivers raise an
               error by using the default devremove from
               devattach(10.2).

          wstat(c, db, dbsize)
               Change the attributes of file c, using the stat(5) data
               in buffer db, which is dbsize bytes long.  Usually a
               driver will use convM2D of styx(10.2) to convert the
               data to a Dir structure, then apply the rules of
               stat(5) to decide which attributes are to be changed
               (and whether the change is allowed).  Most drivers sim-
               ply return an error on all wstat requests by using the
               default devwstat from devattach(10.2).

          power(on)
               Reserved for use in native kernels, to allow the kernel
               to power the device on and off for power-saving; on is
               non-zero if the device is being powered up, and zero if
               it is being powered down.  The device driver should
               save the device state if necessary.  Leave the Dev
               entry null for now.

          config(on, spec, cf)
               Reserved for use in native kernels to allow a device to
               be configured on and off dynamically.  Leave the Dev
               entry null for now.

          The elements reset, shutdown, power, and config are cur-
          rently present only in the native kernels.

     SEE ALSO
          intro(2), intro(5), allocb(10.2), devattach(10.2),
          newchan(10.2), qio(10.2)