From patchwork Wed Jul 25 18:15:13 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alan Tull X-Patchwork-Id: 10544559 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id BAD6D112E for ; Wed, 25 Jul 2018 18:15:25 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AC7462A9E5 for ; Wed, 25 Jul 2018 18:15:25 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9EBF82A9E9; Wed, 25 Jul 2018 18:15:25 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.8 required=2.0 tests=BAYES_00,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2FB7C2A9E5 for ; Wed, 25 Jul 2018 18:15:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729367AbeGYT2N (ORCPT ); Wed, 25 Jul 2018 15:28:13 -0400 Received: from mail.kernel.org ([198.145.29.99]:46264 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729337AbeGYT2I (ORCPT ); Wed, 25 Jul 2018 15:28:08 -0400 Received: from localhost.localdomain (unknown [192.55.54.58]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id AE2C520844; Wed, 25 Jul 2018 18:15:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1532542518; bh=uRauyaYBWk+7MwhDWR51ysz7M4nAzSvFGseMv2gE3ho=; h=From:To:Cc:Subject:Date:From; b=TbvujUBLNtkGCJxfMFYXXZ9xXSvwyPfVilXXY2EDJVH9mZvtgMFkoLqr9PHB9miMP ZAuNXJ+CqviSwWpuNz+dO/n1fvGt/gGMWs2jB6XggdYmxaIGiuWmf3MLy6KfkfyuNM 9BKCK3cetI8jkyZYQ4RLUaDk+rfKC54egk/YN3JM= From: Alan Tull To: Moritz Fischer Cc: Alan Tull , Florian Fainelli , Federico Vaga , linux-kernel@vger.kernel.org, linux-fpga@vger.kernel.org Subject: [PATCH 1/2] fpga: Document when fpga_blah_free functions should be used Date: Wed, 25 Jul 2018 13:15:13 -0500 Message-Id: <20180725181514.3501-1-atull@kernel.org> X-Mailer: git-send-email 2.16.2 Sender: linux-fpga-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fpga@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Clarify when fpga_(mgr|bridge|region)_free functions should be used. The class's dev_release will handle cleanup when the device is released so once the mgr/brige/region has been successfully registered, it would be a bug to call fpga_(mgr|bridge|region)_free. Signed-off-by: Alan Tull Suggested-by: Florian Fainelli Suggested-by: Federico Vaga --- drivers/fpga/fpga-bridge.c | 10 +++++++++- drivers/fpga/fpga-mgr.c | 10 +++++++++- drivers/fpga/fpga-region.c | 10 +++++++++- 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/drivers/fpga/fpga-bridge.c b/drivers/fpga/fpga-bridge.c index 24b8f98..528d2149 100644 --- a/drivers/fpga/fpga-bridge.c +++ b/drivers/fpga/fpga-bridge.c @@ -379,7 +379,11 @@ EXPORT_SYMBOL_GPL(fpga_bridge_create); /** * fpga_bridge_free - free a fpga bridge and its id - * @bridge: FPGA bridge struct created by fpga_bridge_create + * @bridge: FPGA bridge struct created by fpga_bridge_create() + * + * Free a FPGA bridge. This function should only be called for + * freeing a bridge that has not been registered yet (such as in error + * paths in a probe function). */ void fpga_bridge_free(struct fpga_bridge *bridge) { @@ -414,6 +418,10 @@ EXPORT_SYMBOL_GPL(fpga_bridge_register); /** * fpga_bridge_unregister - unregister and free a fpga bridge * @bridge: FPGA bridge struct created by fpga_bridge_create + * + * Unregister the bridge device. The class's dev_release will handle + * freeing the bridge struct when the device is released so don't + * call fpga_bridge_free() after calling fpga_bridge_unregister(). */ void fpga_bridge_unregister(struct fpga_bridge *bridge) { diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c index a41b07e..9632cbd 100644 --- a/drivers/fpga/fpga-mgr.c +++ b/drivers/fpga/fpga-mgr.c @@ -619,7 +619,11 @@ EXPORT_SYMBOL_GPL(fpga_mgr_create); /** * fpga_mgr_free - deallocate a FPGA manager - * @mgr: fpga manager struct created by fpga_mgr_create + * @mgr: fpga manager struct created by fpga_mgr_create() + * + * Free a FPGA manager struct. This function should only be called + * for freeing a manager that has not been registered yet (such as in + * error paths in a probe function). */ void fpga_mgr_free(struct fpga_manager *mgr) { @@ -663,6 +667,10 @@ EXPORT_SYMBOL_GPL(fpga_mgr_register); /** * fpga_mgr_unregister - unregister and free a FPGA manager * @mgr: fpga manager struct + * + * Unregister the manager device. The class's dev_release will handle + * freeing the manager struct when the device is released so don't + * call fpga_mgr_free() after calling fpga_mgr_unregister(). */ void fpga_mgr_unregister(struct fpga_manager *mgr) { diff --git a/drivers/fpga/fpga-region.c b/drivers/fpga/fpga-region.c index 0d65220..7335fa9 100644 --- a/drivers/fpga/fpga-region.c +++ b/drivers/fpga/fpga-region.c @@ -231,7 +231,11 @@ EXPORT_SYMBOL_GPL(fpga_region_create); /** * fpga_region_free - free a struct fpga_region - * @region: FPGA region created by fpga_region_create + * @region: FPGA region created by fpga_region_create() + * + * Free a FPGA region struct. This function should only be called for + * freeing a region that has not been registered yet (such as in error + * paths in a probe function). */ void fpga_region_free(struct fpga_region *region) { @@ -255,6 +259,10 @@ EXPORT_SYMBOL_GPL(fpga_region_register); /** * fpga_region_unregister - unregister and free a FPGA region * @region: FPGA region + * + * Unregister the region device. The class's dev_release will handle + * freeing the region so don't call fpga_region_free() after calling + * fpga_region_unregister(). */ void fpga_region_unregister(struct fpga_region *region) {