/* SPDX-License-Identifier: GPL-2.0-only */
/*
* Copyright (c) 2019-2020 Intel Corporation
*
* Please see Documentation/driver-api/auxiliary_bus.rst for more information.
*/
#ifndef _AUXILIARY_BUS_H_
#define _AUXILIARY_BUS_H_
#include <linux/device.h>
#include <linux/mod_devicetable.h>
/**
* DOC: DEVICE_LIFESPAN
*
* The registering driver is the entity that allocates memory for the
* auxiliary_device and registers it on the auxiliary bus. It is important to
* note that, as opposed to the platform bus, the registering driver is wholly
* responsible for the management of the memory used for the device object.
*
* To be clear the memory for the auxiliary_device is freed in the release()
* callback defined by the registering driver. The registering driver should
* only call auxiliary_device_delete() and then auxiliary_device_uninit() when
* it is done with the device. The release() function is then automatically
* called if and when other code releases their reference to the devices.
*
* A parent object, defined in the shared header file, contains the
* auxiliary_device. It also contains a pointer to the shared object(s), which
* also is defined in the shared header. Both the parent object and the shared
* object(s) are allocated by the registering driver. This layout allows the
* auxiliary_driver's registering module to perform a container_of() call to go
* from the pointer to the auxiliary_device, that is passed during the call to
* the auxiliary_driver's probe function, up to the parent object, and then
* have access to the shared object(s).
*
* The memory for the shared object(s) must have a lifespan equal to, or
* greater than, the lifespan of the memory for the auxiliary_device. The
* auxiliary_driver should only consider that the shared object is valid as
* long as the auxiliary_device is still registered on the auxiliary bus. It
* is up to the registering driver to manage (e.g. free or keep available) the
* memory for the shared object beyond the life of the auxiliary_device.
*
* The registering driver must unregister all auxiliary devices before its own
* driver.remove() is completed. An easy way to ensure this is to use the
* devm_add_action_or_reset() call to register a function against the parent
* device which unregisters the auxiliary device object(s).
*
* Finally, any operations which operate on the auxiliary devices must continue
* to function (if only to return an error) after the registering driver
* unregisters the auxiliary device.
*/
/**
* struct auxiliary_device - auxiliary device object.
* @dev: Device,
* The release and parent fields of the device structure must be filled
* in
* @name: Match name found by the auxiliary device driver,
* @id: unique identitier if multiple devices of the same name are exported,
*
* An auxiliary_device represents a part of its parent device's functionality.
* It is given a name that, combined with the registering drivers
* KBUILD_MODNAME, creates a match_name that is used for driver binding, and an
* id that combined with the match_name provide a unique name to register with
* the bus subsystem. For example, a driver registering an auxiliary device is
* named 'foo_mod.ko' and the subdevice is named 'foo_dev'. The match name is
* therefore 'foo_mod.foo_dev'.
*
* Registering an auxiliary_device is a three-step process.
*
* First, a 'struct auxiliary_device' needs to be defined or allocated for each
* sub-device desired. The name, id, dev.release, and dev.parent fields of
* this structure must be filled in as follows.
*
* The 'name' field is to be given a name that is recognized by the auxiliary
* driver. If two auxiliary_devices with the same match_name, eg
* "foo_mod.foo_dev", are registered onto the bus, they must have unique id
* values (e.g. "x" and "y") so that the registered devices names are
* "foo_mod.foo_dev.x" and "foo_mod.foo_dev.y". If match_name + id are not
* unique, then the device_add fails and generates an error message.
*
* The auxiliary_device.dev.type.release or auxiliary_device.dev.release must
* be populated with a non-NULL pointer to successfully register the
* auxiliary_device. This release call is where resources associated with the
* auxiliary device must be free'ed. Because once the device is placed on the
* bus the parent driver can not tell what other code may have a reference to
* this data.
*
* The auxiliary_device.dev.parent should be set. Typically to the registering
* drivers device.
*
* Second, call auxiliary_device_init(), which checks several aspects of the
* auxiliary_device struct and performs a device_initialize(). After this step
* completes, any error state must have a call to auxiliary_device_uninit() in
* its resolution path.
*
* The third and final step in registering an auxiliary_device is to perform a
* call to auxiliary_device_add(), which sets the name of the device and adds
* the device to the bus.
*
* .. code-block:: c
*
* #define MY_DEVICE_NAME "foo_dev"
*
* ...
*
* struct auxiliary_device *my_aux_dev = my_aux_dev_alloc(xxx);
*
* // Step 1:
* my_aux_dev->name = MY_DEVICE_NAME;
* my_aux_dev->id = my_unique_id_alloc(xxx);
* my_aux_dev->dev.release = my_aux_dev_release;
* my_aux_dev->dev.parent = my_dev;
*
* // Step 2:
* if (auxiliary_device_init(my_aux_dev))
* goto fail;
*
* // Step 3:
* if (auxiliary_device_add(my_aux_dev)) {
* auxiliary_device_uninit(my_aux_dev);
* goto fail;
* }
*
* ...
*
*
* Unregistering an auxiliary_device is a two-step process to mirror the
* register process. First call auxiliary_device_delete(), then call
* auxiliary_device_uninit().
*
* .. code-block:: c
*
* auxiliary_device_delete(my_dev->my_aux_dev);
* auxiliary_device_uninit(my_dev->my_aux_dev);
*/
struct auxiliary_device {
struct device dev;
const char *name;
u32 id;
};
/**
* struct auxiliary_driver - Definition of an auxiliary bus driver
* @probe: Called when a matching device is added to the bus.
* @remove: Called when device is removed from the bus.
* @shutdown: Called at shut-down time to quiesce the device.
* @suspend: Called to put the device to sleep mode. Usually to a power state.
* @resume: Called to bring a device from sleep mode.
* @name: Driver name.
* @driver: Core driver structure.
* @id_table: Table of devices this driver should match on the bus.
*
* Auxiliary drivers follow the standard driver model convention, where
* discovery/enumeration is handled by the core, and drivers provide probe()
* and remove() methods. They support power management and shutdown
* notifications using the standard conventions.
*
* Auxiliary drivers register themselves with the bus by calling
* auxiliary_driver_register(). The id_table contains the match_names of
* auxiliary devices that a driver can bind with.
*
* .. code-block:: c
*
* static const struct auxiliary_device_id my_auxiliary_id_table[] = {
* { .name = "foo_mod.foo_dev" },
* {},
* };
*
* MODULE_DEVICE_TABLE(auxiliary, my_auxiliary_id_table);
*
* struct auxiliary_driver my_drv = {
* .name = "myauxiliarydrv",
* .id_table = my_auxiliary_id_table,
* .probe = my_drv_probe,
* .remove = my_drv_remove
* };
*/
struct auxiliary_driver {
int (*probe)(struct auxiliary_device *auxdev, const struct auxiliary_device_id *id);
void (*remove)(struct auxiliary_device *auxdev);
void (*shutdown)(struct auxiliary_device *auxdev);
int (*suspend)(struct auxiliary_device *auxdev, pm_message_t state);
int (*resume)(struct auxiliary_device *auxdev);
const char *name;
struct device_driver driver;
const struct auxiliary_device_id *id_table;
};
static inline void *auxiliary_get_drvdata(struct auxiliary_device *auxdev)
{
return dev_get_drvdata(&auxdev->dev);
}
static inline void auxiliary_set_drvdata(struct auxiliary_device *auxdev, void *data)
{
dev_set_drvdata(&auxdev->dev, data);
}
static inline struct auxiliary_device *to_auxiliary_dev(struct device *dev)
{
return container_of(dev, struct auxiliary_device, dev);
}
static inline struct auxiliary_driver *to_auxiliary_drv(struct device_driver *drv)
{
return container_of(drv, struct auxiliary_driver, driver);
}
int auxiliary_device_init(struct auxiliary_device *auxdev);
int __auxiliary_device_add(struct auxiliary_device *auxdev, const char *modname);
#define auxiliary_device_add(auxdev) __auxiliary_device_add(auxdev, KBUILD_MODNAME)
static inline void auxiliary_device_uninit(struct auxiliary_device *auxdev)
{
put_device(&auxdev->dev);
}
static inline void auxiliary_device_delete(struct auxiliary_device *auxdev)
{
device_del(&auxdev->dev);
}
int __auxiliary_driver_register(struct auxiliary_driver *auxdrv, struct module *owner,
const char *modname);
#define auxiliary_driver_register(auxdrv) \
__auxiliary_driver_register(auxdrv, THIS_MODULE, KBUILD_MODNAME)
void auxiliary_driver_unregister(struct auxiliary_driver *auxdrv);
/**
* module_auxiliary_driver() - Helper macro for registering an auxiliary driver
* @__auxiliary_driver: auxiliary driver struct
*
* Helper macro for auxiliary drivers which do not do anything special in
* module init/exit. This eliminates a lot of boilerplate. Each module may only
* use this macro once, and calling it replaces module_init() and module_exit()
*
* .. code-block:: c
*
* module_auxiliary_driver(my_drv);
*/
#define module_auxiliary_driver(__auxiliary_driver) \
module_driver(__auxiliary_driver, auxiliary_driver_register, auxiliary_driver_unregister)
struct auxiliary_device *auxiliary_find_device(struct device *start,
const void *data,
int (*match)(struct device *dev, const void *data));
#endif /* _AUXILIARY_BUS_H_ */
