| Message ID | 20180516235007.3951-7-atull@kernel.org (mailing list archive) |
|---|---|
| State | Accepted, archived |
| Headers | show |
On Wed, May 16, 2018 at 06:49:59PM -0500, Alan Tull wrote: > 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 <atull@kernel.org> Acked-by: Moritz Fischer <mdf@kernel.org> > --- > 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) > -- > 2.7.4 > -- To unsubscribe from this list: send the line "unsubscribe linux-fpga" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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)
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 <atull@kernel.org> --- drivers/fpga/fpga-mgr.c | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-)