From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
Sudip Mukherjee <sudipm.mukherjee@gmail.com>,
linux-kernel@vger.kernel.org
Subject: [PATCH v5 03/16] parport: fix a kernel-doc markup
Date: Tue, 1 Dec 2020 13:08:56 +0100 [thread overview]
Message-ID: <77c8069df24d47ff970caad5dc7f989a2270f5f2.1606823973.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1606823973.git.mchehab+huawei@kernel.org>
The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().
So, fix the existing markup and add a new one.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
drivers/parport/share.c | 2 +-
include/linux/parport.h | 31 +++++++++++++++++++++++++++++++
2 files changed, 32 insertions(+), 1 deletion(-)
diff --git a/drivers/parport/share.c b/drivers/parport/share.c
index 7fec4fefe151..62f8407923d4 100644
--- a/drivers/parport/share.c
+++ b/drivers/parport/share.c
@@ -214,65 +214,65 @@ static void get_lowlevel_driver(void)
request_module("parport_lowlevel");
}
/*
* iterates through all the devices connected to the bus and sends the device
* details to the match_port callback of the driver, so that the driver can
* know what are all the ports that are connected to the bus and choose the
* port to which it wants to register its device.
*/
static int port_check(struct device *dev, void *dev_drv)
{
struct parport_driver *drv = dev_drv;
/* only send ports, do not send other devices connected to bus */
if (is_parport(dev))
drv->match_port(to_parport_dev(dev));
return 0;
}
/*
* Iterates through all the devices connected to the bus and return 1
* if the device is a parallel port.
*/
static int port_detect(struct device *dev, void *dev_drv)
{
if (is_parport(dev))
return 1;
return 0;
}
/**
- * parport_register_driver - register a parallel port device driver
+ * __parport_register_driver - register a parallel port device driver
* @drv: structure describing the driver
* @owner: owner module of drv
* @mod_name: module name string
*
* This can be called by a parallel port device driver in order
* to receive notifications about ports being found in the
* system, as well as ports no longer available.
*
* If devmodel is true then the new device model is used
* for registration.
*
* The @drv structure is allocated by the caller and must not be
* deallocated until after calling parport_unregister_driver().
*
* If using the non device model:
* The driver's attach() function may block. The port that
* attach() is given will be valid for the duration of the
* callback, but if the driver wants to take a copy of the
* pointer it must call parport_get_port() to do so. Calling
* parport_register_device() on that port will do this for you.
*
* The driver's detach() function may block. The port that
* detach() is given will be valid for the duration of the
* callback, but if the driver wants to take a copy of the
* pointer it must call parport_get_port() to do so.
*
*
* Returns 0 on success. The non device model will always succeeds.
* but the new device model can fail and will return the error code.
**/
int __parport_register_driver(struct parport_driver *drv, struct module *owner,
diff --git a/include/linux/parport.h b/include/linux/parport.h
index 1fb508c19e83..f981f794c850 100644
--- a/include/linux/parport.h
+++ b/include/linux/parport.h
@@ -268,64 +268,95 @@ struct parport_driver {
#define to_parport_driver(n) container_of(n, struct parport_driver, driver)
int parport_bus_init(void);
void parport_bus_exit(void);
/* parport_register_port registers a new parallel port at the given
address (if one does not already exist) and returns a pointer to it.
This entails claiming the I/O region, IRQ and DMA. NULL is returned
if initialisation fails. */
struct parport *parport_register_port(unsigned long base, int irq, int dma,
struct parport_operations *ops);
/* Once a registered port is ready for high-level drivers to use, the
low-level driver that registered it should announce it. This will
call the high-level drivers' attach() functions (after things like
determining the IEEE 1284.3 topology of the port and collecting
DeviceIDs). */
void parport_announce_port (struct parport *port);
/* Unregister a port. */
extern void parport_remove_port(struct parport *port);
/* Register a new high-level driver. */
int __must_check __parport_register_driver(struct parport_driver *,
struct module *,
const char *mod_name);
/*
* parport_register_driver must be a macro so that KBUILD_MODNAME can
* be expanded
*/
+
+/**
+ * parport_register_driver - register a parallel port device driver
+ * @driver: structure describing the driver
+ *
+ * This can be called by a parallel port device driver in order
+ * to receive notifications about ports being found in the
+ * system, as well as ports no longer available.
+ *
+ * If devmodel is true then the new device model is used
+ * for registration.
+ *
+ * The @driver structure is allocated by the caller and must not be
+ * deallocated until after calling parport_unregister_driver().
+ *
+ * If using the non device model:
+ * The driver's attach() function may block. The port that
+ * attach() is given will be valid for the duration of the
+ * callback, but if the driver wants to take a copy of the
+ * pointer it must call parport_get_port() to do so. Calling
+ * parport_register_device() on that port will do this for you.
+ *
+ * The driver's detach() function may block. The port that
+ * detach() is given will be valid for the duration of the
+ * callback, but if the driver wants to take a copy of the
+ * pointer it must call parport_get_port() to do so.
+ *
+ *
+ * Returns 0 on success. The non device model will always succeeds.
+ * but the new device model can fail and will return the error code.
+ **/
#define parport_register_driver(driver) \
__parport_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
/* Unregister a high-level driver. */
extern void parport_unregister_driver (struct parport_driver *);
void parport_unregister_driver(struct parport_driver *);
/* If parport_register_driver doesn't fit your needs, perhaps
* parport_find_xxx does. */
extern struct parport *parport_find_number (int);
extern struct parport *parport_find_base (unsigned long);
/* generic irq handler, if it suits your needs */
extern irqreturn_t parport_irq_handler(int irq, void *dev_id);
/* Reference counting for ports. */
extern struct parport *parport_get_port (struct parport *);
extern void parport_put_port (struct parport *);
void parport_del_port(struct parport *);
struct pardev_cb {
int (*preempt)(void *);
void (*wakeup)(void *);
void *private;
void (*irq_func)(void *);
unsigned int flags;
};
/*
* parport_register_dev_model declares that a device is connected to a
* port, and tells the kernel all it needs to know.
*/
--
2.28.0
next prev parent reply other threads:[~2020-12-01 12:10 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-12-01 12:08 [PATCH v5 00/16]Fix several bad kernel-doc markups Mauro Carvalho Chehab
2020-12-01 12:08 ` [PATCH v5 01/16] HSI: fix a kernel-doc markup Mauro Carvalho Chehab
2020-12-02 21:38 ` Sebastian Reichel
2020-12-01 12:08 ` [PATCH v5 02/16] IB: fix kernel-doc markups Mauro Carvalho Chehab
2020-12-07 19:46 ` Jason Gunthorpe
2020-12-01 12:08 ` Mauro Carvalho Chehab [this message]
2020-12-01 12:08 ` [PATCH v5 04/16] rapidio: fix kernel-doc a markup Mauro Carvalho Chehab
2020-12-01 12:08 ` [PATCH v5 05/16] fs: fix kernel-doc markups Mauro Carvalho Chehab
2020-12-01 12:43 ` Christoph Hellwig
2020-12-01 14:06 ` Mauro Carvalho Chehab
2020-12-01 12:08 ` [PATCH v5 06/16] pstore/zone: fix a kernel-doc markup Mauro Carvalho Chehab
2020-12-01 12:09 ` [PATCH v5 07/16] completion: drop init_completion define Mauro Carvalho Chehab
2020-12-01 12:54 ` Peter Zijlstra
2020-12-01 14:03 ` Mauro Carvalho Chehab
2020-12-02 8:13 ` Peter Zijlstra
2020-12-01 12:09 ` [PATCH v5 08/16] firmware: stratix10-svc: fix kernel-doc markups Mauro Carvalho Chehab
2020-12-01 12:09 ` [PATCH v5 09/16] connector: fix a kernel-doc markup Mauro Carvalho Chehab
2020-12-01 12:09 ` [PATCH v5 10/16] lib/crc7: " Mauro Carvalho Chehab
2020-12-01 12:09 ` [PATCH v5 11/16] memblock: fix kernel-doc markups Mauro Carvalho Chehab
2020-12-01 12:09 ` [PATCH v5 12/16] w1: fix a kernel-doc markup Mauro Carvalho Chehab
2020-12-01 12:09 ` [PATCH v5 13/16] sched: fix " Mauro Carvalho Chehab
2020-12-02 8:13 ` Peter Zijlstra
2020-12-02 14:10 ` Thomas Gleixner
2020-12-01 12:09 ` [PATCH v5 14/16] selftests: kselftest_harness.h: partially fix kernel-doc markups Mauro Carvalho Chehab
2020-12-01 21:17 ` Kees Cook
2020-12-01 12:09 ` [PATCH v5 15/16] refcount.h: fix a kernel-doc markup Mauro Carvalho Chehab
2020-12-01 21:17 ` Kees Cook
2020-12-02 8:14 ` Peter Zijlstra
2020-12-01 12:09 ` [PATCH v5 16/16] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
2020-12-01 15:06 ` kernel test robot
2020-12-01 15:25 ` kernel test robot
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=77c8069df24d47ff970caad5dc7f989a2270f5f2.1606823973.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=sudipm.mukherjee@gmail.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).