From 0d058a206adadf0c38f891b19dbdcb2963a1cd20 Mon Sep 17 00:00:00 2001 From: Ira Weiny Date: Wed, 1 Dec 2021 20:43:00 -0800 Subject: [PATCH] Documentation/auxiliary_bus: Clarify match_name Provide example code for how the match name is formed and where it is supposed to be set. Signed-off-by: Ira Weiny Link: https://lore.kernel.org/r/20211202044305.4006853-3-ira.weiny@intel.com Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/auxiliary_bus.rst | 33 +++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst index 7dbb4f1..b041a72 100644 --- a/Documentation/driver-api/auxiliary_bus.rst +++ b/Documentation/driver-api/auxiliary_bus.rst @@ -78,6 +78,9 @@ 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'. .. code-block:: c @@ -95,9 +98,9 @@ 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 -"mod.MY_DEVICE_NAME", are registered onto the bus, they must have unique id -values (e.g. "x" and "y") so that the registered devices names are "mod.foo.x" -and "mod.foo.y". If match_name + id are not unique, then the device_add fails +"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 @@ -121,6 +124,10 @@ 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: */ @@ -139,6 +146,9 @@ device to the bus. 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(). @@ -205,6 +215,23 @@ 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 + }; + + Example Usage ============= -- 2.7.4