[PATCH 0/3] Improve Auxiliary Device documentation

[PATCH 0/3] Improve Auxiliary Device documentation

[ira.weiny]

From: Ira Weiny <ira.weiny@intel.com>

The auxiliary device documentation was not wrong but it was a bit difficult to
follow.  Add clarifications to ensure that details are not missed.


Ira Weiny (3):
  Documentation/auxiliary_bus: Clarify auxiliary_device creation
  Documentation/auxiliary_bus: Clarify match_name
  Documentation/auxiliary_bus: Update Auxiliary device lifespan

 Documentation/driver-api/auxiliary_bus.rst | 136 ++++++++++++++++-----
 1 file changed, 107 insertions(+), 29 deletions(-)

-- 
2.28.0.rc0.12.gb6a658bd00c9

[PATCH 1/3] Documentation/auxiliary_bus: Clarify auxiliary_device creation

[ira.weiny]

From: Ira Weiny <ira.weiny@intel.com>

The documentation for creating an auxiliary device is a 3 step not a 2
step process.  Specifically the requirements of setting the name, id,
dev.release, and dev.parent fields was not clear as a precursor to the '2
step' process documented.

Clarify by declaring this a 3 step process starting with setting the
fields of struct auxiliary_device correctly.

Also add some sample code and tie the change into the rest of the
documentation.

Reviewed-by: Dave Jiang <dave.jiang@intel.com>
Signed-off-by: Ira Weiny <ira.weiny@intel.com>
---
 Documentation/driver-api/auxiliary_bus.rst | 77 +++++++++++++++++-----
 1 file changed, 59 insertions(+), 18 deletions(-)

diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst
index ef902daf0d68..8b3e795f3691 100644
--- a/Documentation/driver-api/auxiliary_bus.rst
+++ b/Documentation/driver-api/auxiliary_bus.rst
@@ -79,18 +79,6 @@ 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.
 
-Registering an auxiliary_device is a two-step process.  First 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 second step in registering an auxiliary_device is to perform a call to
-auxiliary_device_add(), which sets the name of the device and add the device to
-the bus.
-
-Unregistering an auxiliary_device is also a two-step process to mirror the
-register process.  First call auxiliary_device_delete(), then call
-auxiliary_device_uninit().
-
 .. code-block:: c
 
 	struct auxiliary_device {
@@ -99,15 +87,68 @@ auxiliary_device_uninit().
 		u32 id;
 	};
 
-If two auxiliary_devices both with a match_name "mod.foo" 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 and generates an error message.
+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
+"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
+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.
+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
+
+	struct axiliary_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);
 
-The auxiliary_device.dev.parent must also be populated.
 
 Auxiliary Device Memory Model and Lifespan
 ------------------------------------------
-- 
2.28.0.rc0.12.gb6a658bd00c9

Re: [PATCH 1/3] Documentation/auxiliary_bus: Clarify auxiliary_device creation

[Jonathan Corbet]

ira.weiny@intel.com writes:

> From: Ira Weiny <ira.weiny@intel.com>
>
> The documentation for creating an auxiliary device is a 3 step not a 2
> step process.  Specifically the requirements of setting the name, id,
> dev.release, and dev.parent fields was not clear as a precursor to the '2
> step' process documented.
>
> Clarify by declaring this a 3 step process starting with setting the
> fields of struct auxiliary_device correctly.
>
> Also add some sample code and tie the change into the rest of the
> documentation.
>
> Reviewed-by: Dave Jiang <dave.jiang@intel.com>
> Signed-off-by: Ira Weiny <ira.weiny@intel.com>

Looks generally good but ...

>  Documentation/driver-api/auxiliary_bus.rst | 77 +++++++++++++++++-----
>  1 file changed, 59 insertions(+), 18 deletions(-)
>
> diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst
> index ef902daf0d68..8b3e795f3691 100644
> --- a/Documentation/driver-api/auxiliary_bus.rst
> +++ b/Documentation/driver-api/auxiliary_bus.rst
> @@ -79,18 +79,6 @@ 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.
>  
> -Registering an auxiliary_device is a two-step process.  First 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 second step in registering an auxiliary_device is to perform a call to
> -auxiliary_device_add(), which sets the name of the device and add the device to
> -the bus.
> -
> -Unregistering an auxiliary_device is also a two-step process to mirror the
> -register process.  First call auxiliary_device_delete(), then call
> -auxiliary_device_uninit().
> -
>  .. code-block:: c
>  
>  	struct auxiliary_device {
> @@ -99,15 +87,68 @@ auxiliary_device_uninit().
>  		u32 id;
>  	};
>  
> -If two auxiliary_devices both with a match_name "mod.foo" 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 and generates an error message.
> +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
> +"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
> +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.
> +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
> +
> +	struct axiliary_device *my_aux_dev = my_aux_dev_alloc(xxx);

This ----------^  would appear to be a typo...

Thanks,

jon

[PATCH v2] Documentation/auxiliary_bus: Clarify auxiliary_device creation

[ira.weiny]

From: Ira Weiny <ira.weiny@intel.com>

The documentation for creating an auxiliary device is a 3 step not a 2
step process.  Specifically the requirements of setting the name, id,
dev.release, and dev.parent fields was not clear as a precursor to the '2
step' process documented.

Clarify by declaring this a 3 step process starting with setting the
fields of struct auxiliary_device correctly.

Also add some sample code and tie the change into the rest of the
documentation.

Reviewed-by: Dave Jiang <dave.jiang@intel.com>
Signed-off-by: Ira Weiny <ira.weiny@intel.com>

---
Changes from V1:
	From Jonathan
		Fix auxiliary spelling
---
 Documentation/driver-api/auxiliary_bus.rst | 77 +++++++++++++++++-----
 1 file changed, 59 insertions(+), 18 deletions(-)

diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst
index ef902daf0d68..cecfa2db46e6 100644
--- a/Documentation/driver-api/auxiliary_bus.rst
+++ b/Documentation/driver-api/auxiliary_bus.rst
@@ -79,18 +79,6 @@ 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.
 
-Registering an auxiliary_device is a two-step process.  First 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 second step in registering an auxiliary_device is to perform a call to
-auxiliary_device_add(), which sets the name of the device and add the device to
-the bus.
-
-Unregistering an auxiliary_device is also a two-step process to mirror the
-register process.  First call auxiliary_device_delete(), then call
-auxiliary_device_uninit().
-
 .. code-block:: c
 
 	struct auxiliary_device {
@@ -99,15 +87,68 @@ auxiliary_device_uninit().
 		u32 id;
 	};
 
-If two auxiliary_devices both with a match_name "mod.foo" 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 and generates an error message.
+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
+"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
+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.
+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
+
+	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);
 
-The auxiliary_device.dev.parent must also be populated.
 
 Auxiliary Device Memory Model and Lifespan
 ------------------------------------------
-- 
2.28.0.rc0.12.gb6a658bd00c9

Re: [PATCH v2] Documentation/auxiliary_bus: Clarify auxiliary_device creation

[Greg Kroah-Hartman]

On Tue, Nov 02, 2021 at 03:53:10PM -0700, ira.weiny@intel.com wrote:
> From: Ira Weiny <ira.weiny@intel.com>
> 
> The documentation for creating an auxiliary device is a 3 step not a 2
> step process.  Specifically the requirements of setting the name, id,
> dev.release, and dev.parent fields was not clear as a precursor to the '2
> step' process documented.
> 
> Clarify by declaring this a 3 step process starting with setting the
> fields of struct auxiliary_device correctly.
> 
> Also add some sample code and tie the change into the rest of the
> documentation.
> 
> Reviewed-by: Dave Jiang <dave.jiang@intel.com>
> Signed-off-by: Ira Weiny <ira.weiny@intel.com>
> 
> ---
> Changes from V1:
> 	From Jonathan
> 		Fix auxiliary spelling
> ---
>  Documentation/driver-api/auxiliary_bus.rst | 77 +++++++++++++++++-----
>  1 file changed, 59 insertions(+), 18 deletions(-)

Can you please resend the whole series, trying to just resend one patch
in the middle is horrible for our tools and to try to figure this out.

Would you like to have to unwind this?  Please make it simple for
maintainers to review and if ok, apply your changes.

thanks,

greg k-h

Re: [PATCH v2] Documentation/auxiliary_bus: Clarify auxiliary_device creation

[Ira Weiny]

On Fri, Nov 26, 2021 at 05:16:54PM +0100, Greg Kroah-Hartman wrote:
> On Tue, Nov 02, 2021 at 03:53:10PM -0700, ira.weiny@intel.com wrote:
> > From: Ira Weiny <ira.weiny@intel.com>
> > 
> > The documentation for creating an auxiliary device is a 3 step not a 2
> > step process.  Specifically the requirements of setting the name, id,
> > dev.release, and dev.parent fields was not clear as a precursor to the '2
> > step' process documented.
> > 
> > Clarify by declaring this a 3 step process starting with setting the
> > fields of struct auxiliary_device correctly.
> > 
> > Also add some sample code and tie the change into the rest of the
> > documentation.
> > 
> > Reviewed-by: Dave Jiang <dave.jiang@intel.com>
> > Signed-off-by: Ira Weiny <ira.weiny@intel.com>
> > 
> > ---
> > Changes from V1:
> > 	From Jonathan
> > 		Fix auxiliary spelling
> > ---
> >  Documentation/driver-api/auxiliary_bus.rst | 77 +++++++++++++++++-----
> >  1 file changed, 59 insertions(+), 18 deletions(-)
> 
> Can you please resend the whole series, trying to just resend one patch
> in the middle is horrible for our tools and to try to figure this out.

Sorry I did not realize this was an issue.  Other maintainers have been ok with
this because I think B4 works fine with this?

> 
> Would you like to have to unwind this?  Please make it simple for
> maintainers to review and if ok, apply your changes.

Regardless, I was planning on resending this as part of the c files as you
requested before.  Did you still want me to make that conversion?

Or I can resend this and make the c conversion as a follow on patch?

Ira

> 
> thanks,
> 
> greg k-h

Re: [PATCH v2] Documentation/auxiliary_bus: Clarify auxiliary_device creation

[Greg Kroah-Hartman]

On Sat, Nov 27, 2021 at 09:32:24PM -0800, Ira Weiny wrote:
> On Fri, Nov 26, 2021 at 05:16:54PM +0100, Greg Kroah-Hartman wrote:
> > On Tue, Nov 02, 2021 at 03:53:10PM -0700, ira.weiny@intel.com wrote:
> > > From: Ira Weiny <ira.weiny@intel.com>
> > > 
> > > The documentation for creating an auxiliary device is a 3 step not a 2
> > > step process.  Specifically the requirements of setting the name, id,
> > > dev.release, and dev.parent fields was not clear as a precursor to the '2
> > > step' process documented.
> > > 
> > > Clarify by declaring this a 3 step process starting with setting the
> > > fields of struct auxiliary_device correctly.
> > > 
> > > Also add some sample code and tie the change into the rest of the
> > > documentation.
> > > 
> > > Reviewed-by: Dave Jiang <dave.jiang@intel.com>
> > > Signed-off-by: Ira Weiny <ira.weiny@intel.com>
> > > 
> > > ---
> > > Changes from V1:
> > > 	From Jonathan
> > > 		Fix auxiliary spelling
> > > ---
> > >  Documentation/driver-api/auxiliary_bus.rst | 77 +++++++++++++++++-----
> > >  1 file changed, 59 insertions(+), 18 deletions(-)
> > 
> > Can you please resend the whole series, trying to just resend one patch
> > in the middle is horrible for our tools and to try to figure this out.
> 
> Sorry I did not realize this was an issue.  Other maintainers have been ok with
> this because I think B4 works fine with this?
> 
> > 
> > Would you like to have to unwind this?  Please make it simple for
> > maintainers to review and if ok, apply your changes.
> 
> Regardless, I was planning on resending this as part of the c files as you
> requested before.  Did you still want me to make that conversion?

Yes.

> Or I can resend this and make the c conversion as a follow on patch?

That is up to you.

[PATCH 2/3] Documentation/auxiliary_bus: Clarify match_name

[ira.weiny]

From: Ira Weiny <ira.weiny@intel.com>

Provide example code for how the match name is formed and where it is
supposed to be set.

Reviewed-by: Dave Jiang <dave.jiang@intel.com>
Signed-off-by: Ira Weiny <ira.weiny@intel.com>
---
 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 8b3e795f3691..41ec9aed059f 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 axiliary_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.28.0.rc0.12.gb6a658bd00c9

[PATCH 3/3] Documentation/auxiliary_bus: Update Auxiliary device lifespan

[ira.weiny]

From: Ira Weiny <ira.weiny@intel.com>

It was unclear when the auxiliary device objects were to be free'ed by
the parent (registering) driver.

Also there are some patterns like using devm_add_action_or_reset() which
are helpful to mention to those using the interface to ensure they don't
double free or miss freeing the auxiliary devices.

Reviewed-by: Dave Jiang <dave.jiang@intel.com>
Signed-off-by: Ira Weiny <ira.weiny@intel.com>
---
 Documentation/driver-api/auxiliary_bus.rst | 32 ++++++++++++++--------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst
index 41ec9aed059f..77c1a39e38d5 100644
--- a/Documentation/driver-api/auxiliary_bus.rst
+++ b/Documentation/driver-api/auxiliary_bus.rst
@@ -164,9 +164,15 @@ Auxiliary Device Memory Model and Lifespan
 ------------------------------------------
 
 The registering driver is the entity that allocates memory for the
-auxiliary_device and register it on the auxiliary bus.  It is important to note
+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 for the memory used for the driver object.
+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 drivers release 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
@@ -177,18 +183,22 @@ 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 auxiliary_device is freed only in its release() callback
-flow as defined by its registering driver.
-
 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 this 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.
+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.
+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.
+
 
 Auxiliary Drivers
 =================
-- 
2.28.0.rc0.12.gb6a658bd00c9

Re: [PATCH 0/3] Improve Auxiliary Device documentation

[Greg Kroah-Hartman]

On Tue, Nov 02, 2021 at 02:53:14PM -0700, ira.weiny@intel.com wrote:
> From: Ira Weiny <ira.weiny@intel.com>
> 
> The auxiliary device documentation was not wrong but it was a bit difficult to
> follow.  Add clarifications to ensure that details are not missed.
> 
> 
> Ira Weiny (3):
>   Documentation/auxiliary_bus: Clarify auxiliary_device creation
>   Documentation/auxiliary_bus: Clarify match_name
>   Documentation/auxiliary_bus: Update Auxiliary device lifespan
> 
>  Documentation/driver-api/auxiliary_bus.rst | 136 ++++++++++++++++-----

Any chance that we can move this documentation into the .c file itself
to make it easier to maintain and keep up to date over time?  I think
the v4l2 and drm subsystems do this pretty well, right?

thanks,

greg k-h