From patchwork Wed May 16 23:49:59 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alan Tull X-Patchwork-Id: 10405125 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 218BA602C2 for ; Wed, 16 May 2018 23:53:03 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 122CA24BFE for ; Wed, 16 May 2018 23:53:03 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 070232874F; Wed, 16 May 2018 23:53:03 +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 9259E28671 for ; Wed, 16 May 2018 23:53:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752174AbeEPXxB (ORCPT ); Wed, 16 May 2018 19:53:01 -0400 Received: from mail.kernel.org ([198.145.29.99]:57862 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751620AbeEPXuU (ORCPT ); Wed, 16 May 2018 19:50:20 -0400 Received: from localhost.localdomain (user-0ccsrjt.cable.mindspring.com [24.206.110.125]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 9A5122075A; Wed, 16 May 2018 23:50:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1526514620; bh=LrIGpxCpCiiy/WoDPt7tp137qIomeGR6HfjGV1AKBKw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Pd8GsmsTKoyua+kf2wWBU2VqA6ySjugXUGyrqMsu/dVaU9DveMLUHE432GGbW/rgL T0ZAjvZROFkcgSGMu88L6A4DTC8MusAVmb1GC6pUQ2xRMnXnZKfdldWKdpf8GKB4JN 7x5gjRaPHHQz6r6tUu1je3j4psMka5LfnIeyOia0= From: Alan Tull To: Greg Kroah-Hartman , Jonathan Corbet , Moritz Fischer Cc: linux-kernel@vger.kernel.org, linux-fpga@vger.kernel.org, Alan Tull Subject: [PATCH 06/14] fpga: mgr: kernel-doc fixes Date: Wed, 16 May 2018 18:49:59 -0500 Message-Id: <20180516235007.3951-7-atull@kernel.org> X-Mailer: git-send-email 2.16.2 In-Reply-To: <20180516235007.3951-1-atull@kernel.org> References: <20180516235007.3951-1-atull@kernel.org> 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 Clean up the kernel-doc documentation in fpga-mgr.c and fix the following warnings when documentation is built: ./drivers/fpga/fpga-mgr.c:252: warning: Function parameter or member 'info' not described in 'fpga_mgr_buf_load' ./drivers/fpga/fpga-mgr.c:252: warning: Excess function parameter 'flags' description in 'fpga_mgr_buf_load' Signed-off-by: Alan Tull Acked-by: Moritz Fischer --- drivers/fpga/fpga-mgr.c | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c index 151ac36..5fffeef 100644 --- a/drivers/fpga/fpga-mgr.c +++ b/drivers/fpga/fpga-mgr.c @@ -21,6 +21,12 @@ static DEFINE_IDA(fpga_mgr_ida); static struct class *fpga_mgr_class; +/** + * fpga_image_info_alloc - Allocate a FPGA image info struct + * @dev: owning device + * + * Return: struct fpga_image_info or NULL + */ struct fpga_image_info *fpga_image_info_alloc(struct device *dev) { struct fpga_image_info *info; @@ -39,6 +45,10 @@ struct fpga_image_info *fpga_image_info_alloc(struct device *dev) } EXPORT_SYMBOL_GPL(fpga_image_info_alloc); +/** + * fpga_image_info_free - Free a FPGA image info struct + * @info: FPGA image info struct to free + */ void fpga_image_info_free(struct fpga_image_info *info) { struct device *dev; @@ -223,7 +233,7 @@ static int fpga_mgr_buf_load_mapped(struct fpga_manager *mgr, /** * fpga_mgr_buf_load - load fpga from image in buffer * @mgr: fpga manager - * @flags: flags setting fpga confuration modes + * @info: fpga image info * @buf: buffer contain fpga image * @count: byte count of buf * @@ -332,6 +342,16 @@ static int fpga_mgr_firmware_load(struct fpga_manager *mgr, return ret; } +/** + * fpga_mgr_load - load FPGA from scatter/gather table, buffer, or firmware + * @mgr: fpga manager + * @info: fpga image information. + * + * Load the FPGA from an image which is indicated in @info. If successful, the + * FPGA ends up in operating mode. + * + * Return: 0 on success, negative error code otherwise. + */ int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info) { if (info->sgt) @@ -418,11 +438,9 @@ static int fpga_mgr_dev_match(struct device *dev, const void *data) } /** - * fpga_mgr_get - get a reference to a fpga mgr + * fpga_mgr_get - Given a device, get a reference to a fpga mgr. * @dev: parent device that fpga mgr was registered with * - * Given a device, get a reference to a fpga mgr. - * * Return: fpga manager struct or IS_ERR() condition containing error code. */ struct fpga_manager *fpga_mgr_get(struct device *dev) @@ -442,10 +460,9 @@ static int fpga_mgr_of_node_match(struct device *dev, const void *data) } /** - * of_fpga_mgr_get - get a reference to a fpga mgr - * @node: device node + * of_fpga_mgr_get - Given a device node, get a reference to a fpga mgr. * - * Given a device node, get a reference to a fpga mgr. + * @node: device node * * Return: fpga manager struct or IS_ERR() condition containing error code. */ @@ -478,7 +495,10 @@ EXPORT_SYMBOL_GPL(fpga_mgr_put); * @mgr: fpga manager * * Given a pointer to FPGA Manager (from fpga_mgr_get() or - * of_fpga_mgr_put()) attempt to get the mutex. + * of_fpga_mgr_put()) attempt to get the mutex. The user should call + * fpga_mgr_lock() and verify that it returns 0 before attempting to + * program the FPGA. Likewise, the user should call fpga_mgr_unlock + * when done programming the FPGA. * * Return: 0 for success or -EBUSY */ @@ -494,7 +514,7 @@ int fpga_mgr_lock(struct fpga_manager *mgr) EXPORT_SYMBOL_GPL(fpga_mgr_lock); /** - * fpga_mgr_unlock - Unlock FPGA manager + * fpga_mgr_unlock - Unlock FPGA manager after done programming * @mgr: fpga manager */ void fpga_mgr_unlock(struct fpga_manager *mgr)