From patchwork Wed Oct 27 22:40:35 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ira Weiny X-Patchwork-Id: 12588941 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id DCE8CC433F5 for ; Wed, 27 Oct 2021 22:42:06 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id C0640600D3 for ; Wed, 27 Oct 2021 22:42:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229705AbhJ0Woc (ORCPT ); Wed, 27 Oct 2021 18:44:32 -0400 Received: from mga17.intel.com ([192.55.52.151]:50708 "EHLO mga17.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229987AbhJ0Wob (ORCPT ); Wed, 27 Oct 2021 18:44:31 -0400 X-IronPort-AV: E=McAfee;i="6200,9189,10150"; a="211054948" X-IronPort-AV: E=Sophos;i="5.87,188,1631602800"; d="scan'208";a="211054948" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2021 15:40:51 -0700 X-IronPort-AV: E=Sophos;i="5.87,188,1631602800"; d="scan'208";a="447414149" Received: from iweiny-desk2.sc.intel.com (HELO localhost) ([10.3.52.147]) by orsmga006-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2021 15:40:51 -0700 From: ira.weiny@intel.com To: Dan Williams Cc: Ira Weiny , Alison Schofield , Vishal Verma , Ben Widawsky , 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 Message-Id: <20211027224043.3551125-2-ira.weiny@intel.com> X-Mailer: git-send-email 2.28.0.rc0.12.gb6a658bd00c9 In-Reply-To: <20211027224043.3551125-1-ira.weiny@intel.com> References: <20210617221620.1904031-4-ira.weiny@intel.com> <20211027224043.3551125-1-ira.weiny@intel.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-cxl@vger.kernel.org From: Ira Weiny 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 --- 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 ------------------------------------------ From patchwork Wed Oct 27 22:40:36 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ira Weiny X-Patchwork-Id: 12588937 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id A78EDC433FE for ; Wed, 27 Oct 2021 22:42:06 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8715460234 for ; Wed, 27 Oct 2021 22:42:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229989AbhJ0Wob (ORCPT ); Wed, 27 Oct 2021 18:44:31 -0400 Received: from mga17.intel.com ([192.55.52.151]:50708 "EHLO mga17.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229705AbhJ0Wob (ORCPT ); Wed, 27 Oct 2021 18:44:31 -0400 X-IronPort-AV: E=McAfee;i="6200,9189,10150"; a="211054951" X-IronPort-AV: E=Sophos;i="5.87,188,1631602800"; d="scan'208";a="211054951" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2021 15:40:53 -0700 X-IronPort-AV: E=Sophos;i="5.87,188,1631602800"; d="scan'208";a="447414179" Received: from iweiny-desk2.sc.intel.com (HELO localhost) ([10.3.52.147]) by orsmga006-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2021 15:40:53 -0700 From: ira.weiny@intel.com To: Dan Williams Cc: Ira Weiny , Alison Schofield , Vishal Verma , Ben Widawsky , linux-cxl@vger.kernel.org Subject: [PATCH 2/9] Documentation/auxiliary_bus: Clarify match_name Date: Wed, 27 Oct 2021 15:40:36 -0700 Message-Id: <20211027224043.3551125-3-ira.weiny@intel.com> X-Mailer: git-send-email 2.28.0.rc0.12.gb6a658bd00c9 In-Reply-To: <20211027224043.3551125-1-ira.weiny@intel.com> References: <20210617221620.1904031-4-ira.weiny@intel.com> <20211027224043.3551125-1-ira.weiny@intel.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-cxl@vger.kernel.org From: Ira Weiny Provide example code for how the match name is formed and where it is supposed to be set. Signed-off-by: Ira Weiny --- 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 29b1322592ef..498b9ad4b6ff 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 @@ -118,6 +121,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. /* 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(). @@ -206,6 +216,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 ============= From patchwork Wed Oct 27 22:40:37 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ira Weiny X-Patchwork-Id: 12588939 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 22192C4332F for ; Wed, 27 Oct 2021 22:42:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 0BFD260F9B for ; Wed, 27 Oct 2021 22:42:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229987AbhJ0Woc (ORCPT ); Wed, 27 Oct 2021 18:44:32 -0400 Received: from mga17.intel.com ([192.55.52.151]:50708 "EHLO mga17.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229993AbhJ0Woc (ORCPT ); Wed, 27 Oct 2021 18:44:32 -0400 X-IronPort-AV: E=McAfee;i="6200,9189,10150"; a="211054957" X-IronPort-AV: E=Sophos;i="5.87,188,1631602800"; d="scan'208";a="211054957" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2021 15:40:57 -0700 X-IronPort-AV: E=Sophos;i="5.87,188,1631602800"; d="scan'208";a="447414200" Received: from iweiny-desk2.sc.intel.com (HELO localhost) ([10.3.52.147]) by orsmga006-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2021 15:40:56 -0700 From: ira.weiny@intel.com To: Dan Williams Cc: Ira Weiny , Alison Schofield , Vishal Verma , Ben Widawsky , linux-cxl@vger.kernel.org Subject: [PATCH 3/9] Documentation/auxiliary_bus: Update Auxiliary device lifespan Date: Wed, 27 Oct 2021 15:40:37 -0700 Message-Id: <20211027224043.3551125-4-ira.weiny@intel.com> X-Mailer: git-send-email 2.28.0.rc0.12.gb6a658bd00c9 In-Reply-To: <20211027224043.3551125-1-ira.weiny@intel.com> References: <20210617221620.1904031-4-ira.weiny@intel.com> <20211027224043.3551125-1-ira.weiny@intel.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-cxl@vger.kernel.org From: Ira Weiny 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. Signed-off-by: Ira Weiny --- 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 498b9ad4b6ff..5635845313be 100644 --- a/Documentation/driver-api/auxiliary_bus.rst +++ b/Documentation/driver-api/auxiliary_bus.rst @@ -165,9 +165,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 @@ -178,18 +184,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 =================