From: ira.weiny@intel.com
To: Dan Williams <dan.j.williams@intel.com>
Cc: Ira Weiny <ira.weiny@intel.com>,
Alison Schofield <alison.schofield@intel.com>,
Vishal Verma <vishal.l.verma@intel.com>,
Ben Widawsky <ben.widawsky@intel.com>,
linux-cxl@vger.kernel.org
Subject: [PATCH 1/9] Documentation/auxiliary_bus: Clarify auxiliary_device creation
Date: Wed, 27 Oct 2021 15:40:35 -0700 [thread overview]
Message-ID: <20211027224043.3551125-2-ira.weiny@intel.com> (raw)
In-Reply-To: <20211027224043.3551125-1-ira.weiny@intel.com>
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 changed into the rest of the
documentation.
Signed-off-by: Ira Weiny <ira.weiny@intel.com>
---
Documentation/driver-api/auxiliary_bus.rst | 78 +++++++++++++++++-----
1 file changed, 60 insertions(+), 18 deletions(-)
diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst
index ef902daf0d68..29b1322592ef 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,69 @@ 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.
+
+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 = alloc_unique_id(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;
+ }
+
+ /* manage the memory */
+ my_dev->my_aux_dev = my_aux_dev;
+
+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);
+ my_aux_dev_free(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
next prev parent reply other threads:[~2021-10-27 22:42 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-17 22:16 [PATCH V2 0/3] Query and use Partition Info ira.weiny
2021-06-17 22:16 ` [PATCH V2 1/3] cxl/pci: Store memory capacity values ira.weiny
2021-06-18 13:40 ` Jonathan Cameron
2021-06-17 22:16 ` [PATCH V2 2/3] cxl/mem: Account for partitionable space in ram/pmem ranges ira.weiny
2021-06-18 13:59 ` Jonathan Cameron
2021-06-18 16:30 ` Ira Weiny
2021-06-18 16:31 ` [PATCH V3] " ira.weiny
2021-06-18 16:58 ` Ben Widawsky
2021-06-18 18:48 ` Ira Weiny
2021-06-18 19:32 ` Ben Widawsky
2021-08-11 1:49 ` [PATCH v4 2/3] " Dan Williams
2021-06-17 22:16 ` [PATCH V2 3/3] cxl/mem: Adjust ram/pmem range to represent DPA ranges ira.weiny
2021-06-18 14:03 ` Jonathan Cameron
2021-06-21 19:54 ` [PATCH V3] " ira.weiny
2021-10-27 22:40 ` [PATCH 0/9] CDAT/DSMAS reading and cleanups ira.weiny
2021-10-27 22:40 ` ira.weiny [this message]
2021-10-27 22:40 ` [PATCH 2/9] Documentation/auxiliary_bus: Clarify match_name ira.weiny
2021-10-27 22:40 ` [PATCH 3/9] Documentation/auxiliary_bus: Update Auxiliary device lifespan ira.weiny
2021-10-27 22:43 ` [PATCH 0/9] CDAT/DSMAS reading and cleanups Ira Weiny
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211027224043.3551125-2-ira.weiny@intel.com \
--to=ira.weiny@intel.com \
--cc=alison.schofield@intel.com \
--cc=ben.widawsky@intel.com \
--cc=dan.j.williams@intel.com \
--cc=linux-cxl@vger.kernel.org \
--cc=vishal.l.verma@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.