man(1) Manual page archive


     DEVATTACH(9)                                         DEVATTACH(9)

     NAME
          devattach, devclone, devdir, devgen, devwalk, devdirread,
          devstat, devopen, devbread, devbwrite, devcreate, devremove,
          devwstat, devreset, devinit, devshutdown, openmode - common
          device driver support

     SYNOPSIS
          typedef int
          Devgen(Chan *c, char *name, Dirtab *tab, int ntab, int i, Dir *dp)

          Chan*  devattach(int tc, char *spec)

          Chan*  devclone(Chan *c)

          void   devdir(Chan *c, Qid qid, char *n, long length,
                           char *user, long perm, Dir *dp)

          int    devgen(Chan *c, char *name, Dirtab *tab, int ntab,
                           int i, Dir *dp)

          Walkqid* devwalk(Chan *c, Chan *nc, char **name, int nname,
                           Dirtab *tab, int ntab, Devgen *gen)

          void   devstat(Chan *c, uchar *db, int n, Dirtab *tab,
                           int ntab, Devgen *gen)

          long   devdirread(Chan *c, char *d, long n, Dirtab *tab,
                           int ntab, Devgen *gen)

          Chan*  devopen(Chan *c, int omode, Dirtab *tab,
                           int ntab, Devgen *gen)

          Block* devbread(Chan *c, long n, ulong offset)

          long   devbwrite(Chan *c, Block *bp, ulong offset)

          void   devcreate(Chan*, char*, int, ulong)

          void   devremove(Chan*)

          void   devwstat(Chan*, uchar*, int)

          void   devreset(void)

          void   devinit(void)

          void   devshutdown(void)

          int    openmode(ulong mode)

     DEVATTACH(9)                                         DEVATTACH(9)

     DESCRIPTION
          Device drivers call these functions to carry out essential
          tasks and default actions.  They do most of the name space
          management for a driver that serves a simple name space (eg,
          data and control files), leaving the driver to concentrate
          on the device-specific details of the I/O requests.  More
          complex drivers also make good use of them at the leaves of
          their name space, and to help manage the Chan structures
          correctly.

          A device has an associated type, represented as a Unicode
          character (`rune') that identifies the device inside and
          outside the kernel.  It appears as the value of the type
          field in the Dir resulting from a stat(2) of any file pro-
          vided by the device.  A device is named outside the kernel
          using a path name starting with # followed by the device
          character (eg, c in #c for the console).  Any subsequent
          characters before the next '/' or end of string is the
          `device specifier', interpreted solely by the device itself.

          Devattach returns a new channel representing the root of the
          file tree corresponding to device type tc, with device spec-
          ifier spec. It is normally called by a driver's attach func-
          tion (see dev(9)). The qid for the new channel is
          (Qid){0,0,QTDIR}, suitable for a root directory for many
          devices, but a device driver is free to change it (provided
          the QTDIR bit remains in the Qid.type).

          Devclone returns a new channel that is a copy of c. An
          attempt to clone an open channel causes a panic(9).

          The `Dir' structure is shown below:

               typedef
               struct Dir
               {
                   /* system-modified data */
                   ushort  type;   /* server type */
                   uint    dev;    /* server subtype */
                   /* file data */
                   Qid     qid;    /* unique id from server */
                   ulong   mode;   /* permissions */
                   ulong   atime;  /* last read time */
                   ulong   mtime;  /* last write time */
                   vlong   length; /* file length */
                   char    *name;  /* last element of path */
                   char    *uid;   /* owner name */
                   char    *gid;   /* group name */
                   char    *muid;  /* last modifier name */
               } Dir;

          This Dir structure corresponds directly to the Limbo Dir adt

     DEVATTACH(9)                                         DEVATTACH(9)

          described in stat(2).

          Given a channel and assorted other information, devdir ini-
          tialises a Dir structure at dp. Devdir supplies the follow-
          ing data itself:

               atime   last access time (set to current time)
               mtime   last modification time (set to kernel creation
                       date)
               gid     group name (set to eve(9))
               length  length in bytes (set to zero, which is normal
                       for most devices)

          Note that devdir assigns the values of name and user
          directly to fields of *dp, and consequently those values
          must remain valid until the last use of *dp.  (Sometimes
          that requires the use of an auxiliary buffer, such as
          up->genbuf.)  If channel c corresponds to a file descriptor
          on which Styx is served, devdir sets both the flag bit
          QTMOUNT in dp->qid.type and the flag bit DMMOUNT in dp->mode
          (see export in dial(2) and mount in bind(2)).

          A simple name space can be represented in a driver by an
          array of Dirtab structures.  The array is typically static
          when the names and permissions are static, but can be dynam-
          ically allocated and initialised if required.  The structure
          of Dirtab is shown below:

               typedef
               struct Dirtab
               {
                       char    name[KNAMELEN];
                       Qid     qid;
                       vlong   length;
                       long    perm;
               } Dirtab;

          The name `.'  must appear as the first entry in a Dirtab if
          the default devgen function is used.  On the other hand, the
          name `..'  must never appear in a Dirtab table.  Drivers
          that support a directory hierarchy must walk up the hierar-
          chy towards the root when their walk function receives `..'
          as a file name component.  The name `.'  is never seen by a
          driver.

          The devdirread, devopen, devstat, and devwalk functions all
          take a gen function argument, of type Devgen, which they
          invoke to retrieve the items in a Chan that represents a
          directory.  Gen takes a channel c (a directory), a file name
          (which is nil except during devwalk), an array of Dirtab
          structures tab of length ntab, and a table index i. The
          functions calling gen expect it to place the i'th entry in

     DEVATTACH(9)                                         DEVATTACH(9)

          the directory into *dp. It should return 1 if the call was
          successful, -1 if i is beyond the index of the last direc-
          tory entry, or 0 if there is no entry at i, but there are
          entries beyond it.  When i has the special value DEVDOTDOT
          then gen should set *dp to reflect the parent of c; if c is
          a one-level device directory, then `..' is equivalent to
          `.'.  Custom implementations of gen often ignore devtab, and
          instead return their own dynamically generated set of direc-
          tory entries from some other source.  Exceptionally, during
          devwalk a non-nil name is provided: it is the name being
          looked up, and a device-specific gen can short-circuit the
          search by returning -1 if the name does not exist, or fill-
          ing in *dp and returning 1 if it does exist.

          The function devgen is compatible with Devgen; it returns
          the i'th entry in devtab, and can be used to provide a sim-
          ple, static set of directory entries.

          Devwalk walks channel c to the file in the device named by
          the path encoded in name, which is an array of strings of
          length nname. It provides the interface to walk(5) within
          the kernel, and that specification must be well understood
          to appreciate all the nuances of its interface.  Fortu-
          nately, in nearly all device drivers, a device's walk func-
          tion typically passes its parameters on to devwalk (adding
          the device's own Dirtab array as the the value of tab), and
          simply returning the result of devwalk.

          Devwalk walks c using the given set of names, and if the
          walk is successful, the channel nc will refer to the result
          of the walk (specifically, nc->qid is set to the Qid for the
          file).  If nc is nil, devwalk will allocate a new channel
          itself, that is initially a clone of c. As in walk(5),
          devwalk can return a partial result, represented by a dynam-
          ically allocated value of the following structure:

               struct Walkqid
               {
                   Chan  *clone;
                   int   nqid;
                   Qid   qid[1];/* actually nname in length */
               };

          The value must be freed after use.  For each element of name
          , devwalk passes the tab parameter to gen together with the
          currently-sought element of name. If the first element is
          not found, devwalk returns nil; otherwise, it returns a
          Walkqid value in which nqid elements of the array qid are
          set to the qids (see intro(5)) of each valid element of
          name. If all nname elements were successfully traversed,
          then nqid will have the value nname, and clone will refer to
          the result of the walk, which is either nc if given, or the

     DEVATTACH(9)                                         DEVATTACH(9)

          new channel allocated by devwalk. Otherwise, at least one
          element succeeded and nqid is less than nname and clone is
          nil.  On an error or incomplete walk, the error string is
          set to the error that stopped the walk (eg, Enonexist or
          Enotdir).

          Devstat fills the array of bytes db with data in the format
          produced by stat(5) that describes the file referenced by
          channel c, which must have a corresponding entry returned by
          gen (ie, an entry with matching Qid.path).  If c is a commu-
          nications channel connecting a Styx server to a current
          mount point, the DMMOUNT bit is set in the resulting
          Dir.mode, and QTMOUNT is set in Dir.qid.type.  As in
          stat(5), the length of the data written to db varies; if
          more than n bytes are needed, devstat raises the error(9)
          Ebadarg.  Otherwise, it returns the number of bytes in db
          actually used.

          If an entry with the desired qid is not found in the table,
          but c corresponds to a directory (ie, QTDIR is set in c-
          >qid.type), it is taken to be a stat of a notional directory
          containing the files listed in tab. Dirstat then builds the
          corresponding Dir structure: its Dir.name is taken from c-
          >path->elem; the length is DIRLEN*nelem(tab); and Dir.perm
          is 0555 (read-execute for all).

          Devdirread calls gen to obtain successive Dir structures
          representing entries in the open directory c. These are con-
          verted to standard format (see convD2M in fcall(2)) and
          placed in the buffer b. It returns the number of bytes in
          the result.  At most n bytes will be returned, in multiples
          of DIRLEN.  Because the kernel maintains the current offset
          in c, successive calls to devdirread return successive
          directory components.

          Devopen is called to check and complete a request to open
          channel c for I/O according to omode (the open mode of
          open(2)). It calls gen to obtain successive directory
          entries which it searches for a Qid matching that of c, and
          ensures that the current user has permission to open c with
          the given mode, omode, and that the mode itself is valid
          (see openmode below).  Permission is checked against the
          permission in the matching entry.  If no matching Qid is
          found, it is assumed that the notional parent directory of
          the files represented in tab is to be opened.  Such a direc-
          tory is deemed to have mode 0555, allowing access by any
          user.  A directory can only be opened for reading (OREAD).
          Devopen returns the channel c on success.  Last, it sets the
          bit COPEN in Chan.flag to mark c as open.  This convention
          can always be relied upon by the driver's close function to
          tell if an open succeeded.  On the otherhand, if the open
          request was unsuccessful, devopen raises an appropriate

     DEVATTACH(9)                                         DEVATTACH(9)

          error(9) and does not return.

          Devbread returns a Block (see allocb(9)) containing up to n
          bytes read, using devtab[c->type]->read, from c starting at
          the given offset. The read pointer in the returned Block
          points to the start of the data; the write pointer points to
          the next available byte.

          Devbwrite writes the data in Block bp to the file c at the
          given offset, using the write function
          devtab[c->type]->write.  It then frees the block list bp
          before returning the number of bytes written.

          Most built-in devices do not allow create, remove or wstat
          on their files.  Devcreate, devremove and devwstat are stubs
          that raise an error(9), Eperm.  They can be named directly
          in a device driver's device switch (the Dev structure in
          /sys/src/9/port/portdat.h: see dev(9)).

          Devreset, devinit and devshutdown are also stubs; they do
          nothing.  A device driver puts them in its Dev structure
          when it need take no action on device reset, initialisation,
          or shut down.

          Openmode is used by a driver that does not use devopen, to
          check the open mode it receives in its open routine.
          Openmode returns mode o, the mode parameter to open(2) or
          sys-create, shorn of OTRUNC and similar options, and reduced
          to one of OREAD, OWRITE or ORDWR.  In particular, OEXEC
          becomes OREAD within the kernel.  Openmode raises an
          error(9) Ebadarg instead of returning, if o is an invalid
          mode (eg, reserved bits set).

     SOURCE
          /sys/src/9/port/dev.c

     SEE ALSO
          allocb(9), eve(9), qio(9)