Commit 0d058a20 authored by Ira Weiny's avatar Ira Weiny Committed by Greg Kroah-Hartman
Browse files

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: default avatarIra Weiny <ira.weiny@intel.com>
Link: https://lore.kernel.org/r/20211202044305.4006853-3-ira.weiny@intel.com


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent b2477038

Documentation/driver-api/auxiliary_bus.rst

+30 −3
Original line number Diff line number Diff line
@@ -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

=============