From 6824f0ce38cb4b903a3cbf00dd528861f6c2ea7c Mon Sep 17 00:00:00 2001 From: Sudip Mukherjee Date: Fri, 3 Apr 2020 14:43:23 +0100 Subject: [PATCH] parport: Add comments for parport_register_dev_model() In preparation to remove parport_register_device(), copy the comments to parport_register_dev_model() and modify the parameters according to what parport_register_dev_model() has. Signed-off-by: Sudip Mukherjee Link: https://lore.kernel.org/r/20200403134325.11523-9-sudipm.mukherjee@gmail.com Signed-off-by: Greg Kroah-Hartman --- drivers/parport/share.c | 62 +++++++++++++++++++++++++++++++++++++++++++++++++ include/linux/parport.h | 4 ++++ 2 files changed, 66 insertions(+) diff --git a/drivers/parport/share.c b/drivers/parport/share.c index 3169fee..ee2892a 100644 --- a/drivers/parport/share.c +++ b/drivers/parport/share.c @@ -841,6 +841,68 @@ static void free_pardevice(struct device *dev) kfree(par_dev); } +/** + * parport_register_dev_model - register a device on a parallel port + * @port: port to which the device is attached + * @name: a name to refer to the device + * @par_dev_cb: struct containing callbacks + * @id: device number to be given to the device + * + * This function, called by parallel port device drivers, + * declares that a device is connected to a port, and tells the + * system all it needs to know. + * + * The struct pardev_cb contains pointer to callbacks. preemption + * callback function, @preempt, is called when this device driver + * has claimed access to the port but another device driver wants + * to use it. It is given, @private, as its parameter, and should + * return zero if it is willing for the system to release the port + * to another driver on its behalf. If it wants to keep control of + * the port it should return non-zero, and no action will be taken. + * It is good manners for the driver to try to release the port at + * the earliest opportunity after its preemption callback rejects a + * preemption attempt. Note that if a preemption callback is happy + * for preemption to go ahead, there is no need to release the + * port; it is done automatically. This function may not block, as + * it may be called from interrupt context. If the device driver + * does not support preemption, @preempt can be %NULL. + * + * The wake-up ("kick") callback function, @wakeup, is called when + * the port is available to be claimed for exclusive access; that + * is, parport_claim() is guaranteed to succeed when called from + * inside the wake-up callback function. If the driver wants to + * claim the port it should do so; otherwise, it need not take + * any action. This function may not block, as it may be called + * from interrupt context. If the device driver does not want to + * be explicitly invited to claim the port in this way, @wakeup can + * be %NULL. + * + * The interrupt handler, @irq_func, is called when an interrupt + * arrives from the parallel port. Note that if a device driver + * wants to use interrupts it should use parport_enable_irq(), + * and can also check the irq member of the parport structure + * representing the port. + * + * The parallel port (lowlevel) driver is the one that has called + * request_irq() and whose interrupt handler is called first. + * This handler does whatever needs to be done to the hardware to + * acknowledge the interrupt (for PC-style ports there is nothing + * special to be done). It then tells the IEEE 1284 code about + * the interrupt, which may involve reacting to an IEEE 1284 + * event depending on the current IEEE 1284 phase. After this, + * it calls @irq_func. Needless to say, @irq_func will be called + * from interrupt context, and may not block. + * + * The %PARPORT_DEV_EXCL flag is for preventing port sharing, and + * so should only be used when sharing the port with other device + * drivers is impossible and would lead to incorrect behaviour. + * Use it sparingly! Normally, @flags will be zero. + * + * This function returns a pointer to a structure that represents + * the device on the port, or %NULL if there is not enough memory + * to allocate space for that structure. + **/ + struct pardevice * parport_register_dev_model(struct parport *port, const char *name, const struct pardev_cb *par_dev_cb, int id) diff --git a/include/linux/parport.h b/include/linux/parport.h index 13932ce..36a0f62 100644 --- a/include/linux/parport.h +++ b/include/linux/parport.h @@ -337,6 +337,10 @@ struct pardevice *parport_register_device(struct parport *port, void (*irq_func)(void *), int flags, void *handle); +/* + * parport_register_dev_model declares that a device is connected to a + * port, and tells the kernel all it needs to know. + */ struct pardevice * parport_register_dev_model(struct parport *port, const char *name, const struct pardev_cb *par_dev_cb, int cnt); -- 2.7.4