include/linux/auxiliary_bus.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * Copyright (c) 2019-2020 Intel Corporation
   4  *
   5  * Please see Documentation/driver-api/auxiliary_bus.rst for more information.
   6  */
   7
   8 #ifndef _AUXILIARY_BUS_H_
   9 #define _AUXILIARY_BUS_H_
  10
  11 #include <linux/device.h>
  12 #include <linux/mod_devicetable.h>
  13
  14 /**
  15  * DOC: DEVICE_LIFESPAN
  16  *
  17  * The registering driver is the entity that allocates memory for the
  18  * auxiliary_device and registers it on the auxiliary bus.  It is important to
  19  * note that, as opposed to the platform bus, the registering driver is wholly
  20  * responsible for the management of the memory used for the device object.
  21  *
  22  * To be clear the memory for the auxiliary_device is freed in the release()
  23  * callback defined by the registering driver.  The registering driver should
  24  * only call auxiliary_device_delete() and then auxiliary_device_uninit() when
  25  * it is done with the device.  The release() function is then automatically
  26  * called if and when other code releases their reference to the devices.
  27  *
  28  * A parent object, defined in the shared header file, contains the
  29  * auxiliary_device.  It also contains a pointer to the shared object(s), which
  30  * also is defined in the shared header.  Both the parent object and the shared
  31  * object(s) are allocated by the registering driver.  This layout allows the
  32  * auxiliary_driver's registering module to perform a container_of() call to go
  33  * from the pointer to the auxiliary_device, that is passed during the call to
  34  * the auxiliary_driver's probe function, up to the parent object, and then
  35  * have access to the shared object(s).
  36  *
  37  * The memory for the shared object(s) must have a lifespan equal to, or
  38  * greater than, the lifespan of the memory for the auxiliary_device.  The
  39  * auxiliary_driver should only consider that the shared object is valid as
  40  * long as the auxiliary_device is still registered on the auxiliary bus.  It
  41  * is up to the registering driver to manage (e.g. free or keep available) the
  42  * memory for the shared object beyond the life of the auxiliary_device.
  43  *
  44  * The registering driver must unregister all auxiliary devices before its own
  45  * driver.remove() is completed.  An easy way to ensure this is to use the
  46  * devm_add_action_or_reset() call to register a function against the parent
  47  * device which unregisters the auxiliary device object(s).
  48  *
  49  * Finally, any operations which operate on the auxiliary devices must continue
  50  * to function (if only to return an error) after the registering driver
  51  * unregisters the auxiliary device.
  52  */
  53
  54 /**
  55  * struct auxiliary_device - auxiliary device object.
  56  * @dev: Device,
  57  *       The release and parent fields of the device structure must be filled
  58  *       in
  59  * @name: Match name found by the auxiliary device driver,
  60  * @id: unique identitier if multiple devices of the same name are exported,
  61  *
  62  * An auxiliary_device represents a part of its parent device's functionality.
  63  * It is given a name that, combined with the registering drivers
  64  * KBUILD_MODNAME, creates a match_name that is used for driver binding, and an
  65  * id that combined with the match_name provide a unique name to register with
  66  * the bus subsystem.  For example, a driver registering an auxiliary device is
  67  * named 'foo_mod.ko' and the subdevice is named 'foo_dev'.  The match name is
  68  * therefore 'foo_mod.foo_dev'.
  69  *
  70  * Registering an auxiliary_device is a three-step process.
  71  *
  72  * First, a 'struct auxiliary_device' needs to be defined or allocated for each
  73  * sub-device desired.  The name, id, dev.release, and dev.parent fields of
  74  * this structure must be filled in as follows.
  75  *
  76  * The 'name' field is to be given a name that is recognized by the auxiliary
  77  * driver.  If two auxiliary_devices with the same match_name, eg
  78  * "foo_mod.foo_dev", are registered onto the bus, they must have unique id
  79  * values (e.g. "x" and "y") so that the registered devices names are
  80  * "foo_mod.foo_dev.x" and "foo_mod.foo_dev.y".  If match_name + id are not
  81  * unique, then the device_add fails and generates an error message.
  82  *
  83  * The auxiliary_device.dev.type.release or auxiliary_device.dev.release must
  84  * be populated with a non-NULL pointer to successfully register the
  85  * auxiliary_device.  This release call is where resources associated with the
  86  * auxiliary device must be free'ed.  Because once the device is placed on the
  87  * bus the parent driver can not tell what other code may have a reference to
  88  * this data.
  89  *
  90  * The auxiliary_device.dev.parent should be set.  Typically to the registering
  91  * drivers device.
  92  *
  93  * Second, call auxiliary_device_init(), which checks several aspects of the
  94  * auxiliary_device struct and performs a device_initialize().  After this step
  95  * completes, any error state must have a call to auxiliary_device_uninit() in
  96  * its resolution path.
  97  *
  98  * The third and final step in registering an auxiliary_device is to perform a
  99  * call to auxiliary_device_add(), which sets the name of the device and adds
 100  * the device to the bus.
 101  *
 102  * .. code-block:: c
 103  *
 104  *      #define MY_DEVICE_NAME "foo_dev"
 105  *
 106  *      ...
 107  *
 108  *      struct auxiliary_device *my_aux_dev = my_aux_dev_alloc(xxx);
 109  *
 110  *      // Step 1:
 111  *      my_aux_dev->name = MY_DEVICE_NAME;
 112  *      my_aux_dev->id = my_unique_id_alloc(xxx);
 113  *      my_aux_dev->dev.release = my_aux_dev_release;
 114  *      my_aux_dev->dev.parent = my_dev;
 115  *
 116  *      // Step 2:
 117  *      if (auxiliary_device_init(my_aux_dev))
 118  *              goto fail;
 119  *
 120  *      // Step 3:
 121  *      if (auxiliary_device_add(my_aux_dev)) {
 122  *              auxiliary_device_uninit(my_aux_dev);
 123  *              goto fail;
 124  *      }
 125  *
 126  *      ...
 127  *
 128  *
 129  * Unregistering an auxiliary_device is a two-step process to mirror the
 130  * register process.  First call auxiliary_device_delete(), then call
 131  * auxiliary_device_uninit().
 132  *
 133  * .. code-block:: c
 134  *
 135  *         auxiliary_device_delete(my_dev->my_aux_dev);
 136  *         auxiliary_device_uninit(my_dev->my_aux_dev);
 137  */
 138 struct auxiliary_device {
 139         struct device dev;
 140         const char *name;
 141         u32 id;
 142 };
 143
 144 /**
 145  * struct auxiliary_driver - Definition of an auxiliary bus driver
 146  * @probe: Called when a matching device is added to the bus.
 147  * @remove: Called when device is removed from the bus.
 148  * @shutdown: Called at shut-down time to quiesce the device.
 149  * @suspend: Called to put the device to sleep mode. Usually to a power state.
 150  * @resume: Called to bring a device from sleep mode.
 151  * @name: Driver name.
 152  * @driver: Core driver structure.
 153  * @id_table: Table of devices this driver should match on the bus.
 154  *
 155  * Auxiliary drivers follow the standard driver model convention, where
 156  * discovery/enumeration is handled by the core, and drivers provide probe()
 157  * and remove() methods. They support power management and shutdown
 158  * notifications using the standard conventions.
 159  *
 160  * Auxiliary drivers register themselves with the bus by calling
 161  * auxiliary_driver_register(). The id_table contains the match_names of
 162  * auxiliary devices that a driver can bind with.
 163  *
 164  * .. code-block:: c
 165  *
 166  *         static const struct auxiliary_device_id my_auxiliary_id_table[] = {
 167  *                 { .name = "foo_mod.foo_dev" },
 168  *                 {},
 169  *         };
 170  *
 171  *         MODULE_DEVICE_TABLE(auxiliary, my_auxiliary_id_table);
 172  *
 173  *         struct auxiliary_driver my_drv = {
 174  *                 .name = "myauxiliarydrv",
 175  *                 .id_table = my_auxiliary_id_table,
 176  *                 .probe = my_drv_probe,
 177  *                 .remove = my_drv_remove
 178  *         };
 179  */
 180 struct auxiliary_driver {
 181         int (*probe)(struct auxiliary_device *auxdev, const struct auxiliary_device_id *id);
 182         void (*remove)(struct auxiliary_device *auxdev);
 183         void (*shutdown)(struct auxiliary_device *auxdev);
 184         int (*suspend)(struct auxiliary_device *auxdev, pm_message_t state);
 185         int (*resume)(struct auxiliary_device *auxdev);
 186         const char *name;
 187         struct device_driver driver;
 188         const struct auxiliary_device_id *id_table;
 189 };
 190
 191 static inline void *auxiliary_get_drvdata(struct auxiliary_device *auxdev)
 192 {
 193         return dev_get_drvdata(&auxdev->dev);
 194 }
 195
 196 static inline void auxiliary_set_drvdata(struct auxiliary_device *auxdev, void *data)
 197 {
 198         dev_set_drvdata(&auxdev->dev, data);
 199 }
 200
 201 static inline struct auxiliary_device *to_auxiliary_dev(struct device *dev)
 202 {
 203         return container_of(dev, struct auxiliary_device, dev);
 204 }
 205
 206 static inline struct auxiliary_driver *to_auxiliary_drv(struct device_driver *drv)
 207 {
 208         return container_of(drv, struct auxiliary_driver, driver);
 209 }
 210
 211 int auxiliary_device_init(struct auxiliary_device *auxdev);
 212 int __auxiliary_device_add(struct auxiliary_device *auxdev, const char *modname);
 213 #define auxiliary_device_add(auxdev) __auxiliary_device_add(auxdev, KBUILD_MODNAME)
 214
 215 static inline void auxiliary_device_uninit(struct auxiliary_device *auxdev)
 216 {
 217         put_device(&auxdev->dev);
 218 }
 219
 220 static inline void auxiliary_device_delete(struct auxiliary_device *auxdev)
 221 {
 222         device_del(&auxdev->dev);
 223 }
 224
 225 int __auxiliary_driver_register(struct auxiliary_driver *auxdrv, struct module *owner,
 226                                 const char *modname);
 227 #define auxiliary_driver_register(auxdrv) \
 228         __auxiliary_driver_register(auxdrv, THIS_MODULE, KBUILD_MODNAME)
 229
 230 void auxiliary_driver_unregister(struct auxiliary_driver *auxdrv);
 231
 232 /**
 233  * module_auxiliary_driver() - Helper macro for registering an auxiliary driver
 234  * @__auxiliary_driver: auxiliary driver struct
 235  *
 236  * Helper macro for auxiliary drivers which do not do anything special in
 237  * module init/exit. This eliminates a lot of boilerplate. Each module may only
 238  * use this macro once, and calling it replaces module_init() and module_exit()
 239  *
 240  * .. code-block:: c
 241  *
 242  *      module_auxiliary_driver(my_drv);
 243  */
 244 #define module_auxiliary_driver(__auxiliary_driver) \
 245         module_driver(__auxiliary_driver, auxiliary_driver_register, auxiliary_driver_unregister)
 246
 247 struct auxiliary_device *auxiliary_find_device(struct device *start,
 248                                                const void *data,
 249                                                int (*match)(struct device *dev, const void *data));
 250
 251 #endif /* _AUXILIARY_BUS_H_ */