DragonFly On-Line Manual Pages

Search: Section:  

MAKE_AUTOCLONE_DEV(9)                      DragonFly Kernel Developer's Manual


NAME

     make_autoclone_dev, destroy_autoclone_dev, devfs_clone_bitmap_init,
     devfs_clone_bitmap_uninit, devfs_clone_bitmap_chk,
     devfs_clone_bitmap_set, devfs_clone_bitmap_get, devfs_clone_bitmap_put,
     DEVFS_DECLARE_CLONE_BITMAP, DEVFS_DEFINE_CLONE_BITMAP, DEVFS_CLONE_BITMAP
     - device clone functions


SYNOPSIS

     #include <sys/types.h>
     #include <sys/conf.h>
     #include <sys/devfs.h>

     cdev_t
     make_autoclone_dev(struct dev_ops *ops, struct devfs_bitmap *bitmap,
         d_clone_t *nhandler, uid_t uid, gid_t gid, int perms,
         const char *fmt, ...);

     void
     destroy_autoclone_dev(cdev_t dev, struct devfs_bitmap *bitmap);

     void
     devfs_clone_bitmap_init(struct devfs_bitmap *bitmap);

     void
     devfs_clone_bitmap_uninit(struct devfs_bitmap *bitmap);

     int
     devfs_clone_bitmap_chk(struct devfs_bitmap *bitmap, int unit);

     int
     devfs_clone_bitmap_set(struct devfs_bitmap *bitmap, int unit);

     int
     devfs_clone_bitmap_get(struct devfs_bitmap *bitmap, int limit);

     void
     devfs_clone_bitmap_put(struct devfs_bitmap *bitmap, int unit);

     DEVFS_DECLARE_CLONE_BITMAP(name);

     DEVFS_DEFINE_CLONE_BITMAP(name);

     DEVFS_CLONE_BITMAP(name);


DESCRIPTION

     make_autoclone_dev() creates a cdev_t with the default ops, visible in
     the devfs(5) namespace, that will invoke the clone handler specified by
     nhandler when it is opened.  If the bitmap argument is specified, it will
     be initialized using devfs_clone_bitmap_init().

     The clone handler must be defined as follows:

           d_clone_t mydev_clone;

           int
           mydev_clone(struct dev_clone_args *ap)
           {
           };

     When called, the handler is passed a pointer to a populated
     dev_clone_args structure, which is defined as follows:

           struct dev_clone_args {
                   struct dev_generic_args a_head;
                   struct cdev     *a_dev;
                   const char      *a_name;
                   size_t           a_namelen;
                   struct ucred    *a_cred;
                   int              a_mode;
           };

     The a_head.a_dev is the cdev_t of the accessed autoclone device.  The
     a_name and a_namelen are the registered clonable base name and its
     length, as specified to make_autoclone_dev().  The a_mode and a_cred
     contain the mode and credential passed to the open() of the autoclone
     device.

     The clone handler must set a_dev to a new cdev_t that is returned by a
     call to make_only_dev().  The new cdev_t will be automatically made
     visible and linked into devfs(5) namespace, as if it was created with
     make_dev().  Thus, destroy_dev() should be used to destroy the cloned
     cdev_t once it is no longer required, usually during close().

     destroy_autoclone_dev() destroys a cdev_t created by make_autoclone_dev()
     unregistering its clone handler and (if non-NULL) also uninitializes its
     bitmap using devfs_clone_bitmap_uninit().

     devfs_clone_bitmap_init() initializes the given clone bitmap so it is
     ready to use.

     devfs_clone_bitmap_uninit() frees the memory associated with the
     specified clone bitmap and leaves it unusable.

     devfs_clone_bitmap_chk() checks if unit is in use (set) and returns 1 if
     it is; otherwise 0 is returned.

     devfs_clone_bitmap_set() marks unit in the bitmap as used, so further
     calls to devfs_clone_bitmap_get() cannot retrieve it.  The function
     returns -1 if the unit is already allocated, otherwise 0.  If one intends
     to use a clone handler along with preallocated devices, it is recommended
     to block the unit numbers of the preallocated devices by calling
     devfs_clone_bitmap_set() on them.

     devfs_clone_bitmap_get() will return the first unused unit number and
     also mark it as used in the bitmap.  If the limit argument is greater
     than 0, the requested unit number cannot be greater than the given limit.
     The function returns -1 if no more units are available.

     devfs_clone_bitmap_put() marks unit in the bitmap as unused so further
     calls to devfs_clone_bitmap_get() can retrieve it again.  It is
     recommended that the associated device be destroyed prior to making the
     unit available in the bitmap again, to avoid racing against a new clone.

     The DEVFS_DEFINE_CLONE_BITMAP() macro defines a clone bitmap with the
     specified name.  As long as the name specified is unique, this macro can
     be used to define global variables.  Similarly,
     DEVFS_DECLARE_CLONE_BITMAP() declares a clone bitmap.

     The DEVFS_CLONE_BITMAP() is a macro which expands the specified name to
     the full name of a clone bitmap.  It is used in conjunction with
     DEVFS_DEFINE_CLONE_BITMAP() and DEVFS_DECLARE_CLONE_BITMAP(), as it uses
     the same name.


SEE ALSO

     devfs(5), destroy_dev(9), make_dev(9), make_only_dev(9)


HISTORY

     The devfs(5) clone facilities and the associated functions all appeared
     in DragonFly 2.3.


AUTHORS

     Alex Hornung

DragonFly 5.9-DEVELOPMENT        June 30, 2020       DragonFly 5.9-DEVELOPMENT

Search: Section: