Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1406603
| From | David Kershner <david.kershner@unisys.com> |
|---|---|
| Newsgroups | linux.kernel |
| Subject | [PATCH 20/24] staging: unisys: visorbus: Add kerneldoc-style comments for visorbus API |
| Date | 2016-05-25 06:00 +0200 |
| Message-ID | <rCy9c-4pG-23@gated-at.bofh.it> (permalink) |
| References | <rCxZv-4k1-3@gated-at.bofh.it> |
| Organization | linux.* mail to news gateway |
From: David Binder <david.binder@unisys.com>
Adds kerneldoc-style comments for those functions which may be used outside
of the visorbus driver.
Signed-off-by: David Binder <david.binder@unisys.com>
Signed-off-by: David Kershner <david.kershner@unisys.com>
---
drivers/staging/unisys/include/visorbus.h | 127 ++++++++++++++++++++++++
drivers/staging/unisys/visorbus/visorbus_main.c | 42 --------
2 files changed, 127 insertions(+), 42 deletions(-)
diff --git a/drivers/staging/unisys/include/visorbus.h b/drivers/staging/unisys/include/visorbus.h
index 2c103e8..99c7beb 100644
--- a/drivers/staging/unisys/include/visorbus.h
+++ b/drivers/staging/unisys/include/visorbus.h
@@ -177,22 +177,149 @@ struct visor_device {
#define to_visor_device(x) container_of(x, struct visor_device, device)
+/**
+ * visorbus_register_visor_driver() - registers the provided driver
+ * @struct visor_driver *: the driver to register
+ *
+ * A particular type of visor driver calls this function to register
+ * the driver. The caller MUST fill in the following fields within the
+ * #drv structure:
+ * name, version, owner, channel_types, probe, remove
+ *
+ * Here's how the whole Linux bus / driver / device model works.
+ *
+ * At system start-up, the visorbus kernel module is loaded, which registers
+ * visorbus_type as a bus type, using bus_register().
+ *
+ * All kernel modules that support particular device types on a
+ * visorbus bus are loaded. Each of these kernel modules calls
+ * visorbus_register_visor_driver() in their init functions, passing a
+ * visor_driver struct. visorbus_register_visor_driver() in turn calls
+ * register_driver(&visor_driver.driver). This .driver member is
+ * initialized with generic methods (like probe), whose sole responsibility
+ * is to act as a broker for the real methods, which are within the
+ * visor_driver struct. (This is the way the subclass behavior is
+ * implemented, since visor_driver is essentially a subclass of the
+ * generic driver.) Whenever a driver_register() happens, core bus code in
+ * the kernel does (see device_attach() in drivers/base/dd.c):
+ *
+ * for each dev associated with the bus (the bus that driver is on) that
+ * does not yet have a driver
+ * if bus.match(dev,newdriver) == yes_matched ** .match specified
+ * ** during bus_register().
+ * newdriver.probe(dev) ** for visor drivers, this will call
+ * ** the generic driver.probe implemented in visorbus.c,
+ * ** which in turn calls the probe specified within the
+ * ** struct visor_driver (which was specified by the
+ * ** actual device driver as part of
+ * ** visorbus_register_visor_driver()).
+ *
+ * The above dance also happens when a new device appears.
+ * So the question is, how are devices created within the system?
+ * Basically, just call device_add(dev). See pci_bus_add_devices().
+ * pci_scan_device() shows an example of how to build a device struct. It
+ * returns the newly-created struct to pci_scan_single_device(), who adds it
+ * to the list of devices at PCIBUS.devices. That list of devices is what
+ * is traversed by pci_bus_add_devices().
+ *
+ * Return: integer indicating success (zero) or failure (non-zero)
+ */
int visorbus_register_visor_driver(struct visor_driver *);
+
+/**
+ * visorbus_unregister_visor_driver() - unregisters the provided driver
+ * @struct visor_driver *: the driver to unregister
+ */
void visorbus_unregister_visor_driver(struct visor_driver *);
+
+/**
+ * visorbus_read_channel() - reads from the designated channel into
+ * the provided buffer
+ * @dev: the device whose channel is read from
+ * @offset: the offset into the channel at which reading starts
+ * @dest: the destination buffer that is written into from the channel
+ * @nbytes: the number of bytes to read from the channel
+ *
+ * If receiving a message, use the visorchannel_signalremove()
+ * function instead.
+ *
+ * Return: integer indicating success (zero) or failure (non-zero)
+ */
int visorbus_read_channel(struct visor_device *dev,
unsigned long offset, void *dest,
unsigned long nbytes);
+
+/**
+ * visorbus_write_channel() - writes the provided buffer into the designated
+ * channel
+ * @dev: the device whose channel is written to
+ * @offset: the offset into the channel at which writing starts
+ * @src: the source buffer that is written into the channel
+ * @nbytes: the number of bytes to write into the channel
+ *
+ * If sending a message, use the visorchannel_signalinsert()
+ * function instead.
+ *
+ * Return: integer indicating success (zero) or failure (non-zero)
+ */
int visorbus_write_channel(struct visor_device *dev,
unsigned long offset, void *src,
unsigned long nbytes);
+/**
+ * visorbus_enable_channel_interrupts() - enables interrupts on the
+ * designated device
+ * @dev: the device on which to enable interrupts
+ */
void visorbus_enable_channel_interrupts(struct visor_device *dev);
+
+/**
+ * visorbus_disable_channel_interrupts() - disables interrupts on the
+ * designated device
+ * @dev: the device on which to disable interrupts
+ */
void visorbus_disable_channel_interrupts(struct visor_device *dev);
+/**
+ * visorchannel_signalremove() - removes a message from the designated
+ * channel/queue
+ * @channel: the channel the message will be removed from
+ * @queue: the queue the message will be removed from
+ * @msg: the message to remove
+ *
+ * Return: boolean indicating whether the removal succeeded or failed
+ */
bool visorchannel_signalremove(struct visorchannel *channel, u32 queue,
void *msg);
+
+/**
+ * visorchannel_signalinsert() - inserts a message into the designated
+ * channel/queue
+ * @channel: the channel the message will be added to
+ * @queue: the queue the message will be added to
+ * @msg: the message to insert
+ *
+ * Return: boolean indicating whether the insertion succeeded or failed
+ */
bool visorchannel_signalinsert(struct visorchannel *channel, u32 queue,
void *msg);
+
+/**
+ * visorchannel_signalempty() - checks if the designated channel/queue
+ * contains any messages
+ * @channel: the channel to query
+ * @queue: the queue in the channel to query
+ *
+ * Return: boolean indicating whether any messages in the designated
+ * channel/queue are present
+ */
bool visorchannel_signalempty(struct visorchannel *channel, u32 queue);
+
+/**
+ * visorchannel_get_uuid() - queries the UUID of the designated channel
+ * @channel: the channel to query
+ *
+ * Return: the UUID of the provided channel
+ */
uuid_le visorchannel_get_uuid(struct visorchannel *channel);
#define BUS_ROOT_DEVICE UINT_MAX
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c b/drivers/staging/unisys/visorbus/visorbus_main.c
index 850998e..0a537c7 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -616,48 +616,6 @@ visordriver_remove_device(struct device *xdev)
return 0;
}
-/**
- * A particular type of visor driver calls this function to register
- * the driver. The caller MUST fill in the following fields within the
- * #drv structure:
- * name, version, owner, channel_types, probe, remove
- *
- * Here's how the whole Linux bus / driver / device model works.
- *
- * At system start-up, the visorbus kernel module is loaded, which registers
- * visorbus_type as a bus type, using bus_register().
- *
- * All kernel modules that support particular device types on a
- * visorbus bus are loaded. Each of these kernel modules calls
- * visorbus_register_visor_driver() in their init functions, passing a
- * visor_driver struct. visorbus_register_visor_driver() in turn calls
- * register_driver(&visor_driver.driver). This .driver member is
- * initialized with generic methods (like probe), whose sole responsibility
- * is to act as a broker for the real methods, which are within the
- * visor_driver struct. (This is the way the subclass behavior is
- * implemented, since visor_driver is essentially a subclass of the
- * generic driver.) Whenever a driver_register() happens, core bus code in
- * the kernel does (see device_attach() in drivers/base/dd.c):
- *
- * for each dev associated with the bus (the bus that driver is on) that
- * does not yet have a driver
- * if bus.match(dev,newdriver) == yes_matched ** .match specified
- * ** during bus_register().
- * newdriver.probe(dev) ** for visor drivers, this will call
- * ** the generic driver.probe implemented in visorbus.c,
- * ** which in turn calls the probe specified within the
- * ** struct visor_driver (which was specified by the
- * ** actual device driver as part of
- * ** visorbus_register_visor_driver()).
- *
- * The above dance also happens when a new device appears.
- * So the question is, how are devices created within the system?
- * Basically, just call device_add(dev). See pci_bus_add_devices().
- * pci_scan_device() shows an example of how to build a device struct. It
- * returns the newly-created struct to pci_scan_single_device(), who adds it
- * to the list of devices at PCIBUS.devices. That list of devices is what
- * is traversed by pci_bus_add_devices().
- */
int visorbus_register_visor_driver(struct visor_driver *drv)
{
int rc = 0;
--
1.9.1
Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
[PATCH 00/24] Fixes comments made by tglx, then move visorbus to drivers/virt David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 11/24] staging: unisys: visorbus: Remove unnecessary EXPORT_SYMBOL statements David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 18/24] staging: unisys: visorbus: make visorchipset function descriptions more kerneldoc-like David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 24/24] drivers: Add visorbus to the drivers directory David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 14/24] staging: unisys: visorbus: vbusdeviceinfo function descriptions more kerneldoc-like David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 22/24] include: linux: visorbus: Add visorbus to include/linux directory David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 01/24] staging: unisys: visorbus: remove unused module parameters David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 10/24] staging: unisys: visorbus: Make visordriver_callback_lock a mutex David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 09/24] staging: unisys: visorbus: remove periodic_work.h/.c David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 04/24] staging: unisys: visornic: Correct comment spelling mistake David Kershner <david.kershner@unisys.com> - 2016-05-25 05:50 +0200 [PATCH 08/24] staging: unisys: visorbus: use kernel timer instead of workqueue David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 17/24] staging: unisys: visorbus: make visorchannel function descriptions more kerneldoc-like David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 19/24] staging: unisys: visorbus: Move visorbus-unique functions to private header David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 16/24] staging: unisys: visorbus: make visorbus_private.h function descriptions more kerneldoc-like David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 06/24] staging: unisys: visorbus: removed unused periodic_test_workqueue David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 20/24] staging: unisys: visorbus: Add kerneldoc-style comments for visorbus API David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 07/24] staging: unisys: visorinput: remove unnecessary locking David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 13/24] staging: unisys: Remove reference to unused STANDALONE_CLIENT David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 15/24] staging: unisys: visorbus: make function descriptions more kerneldoc-like David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 05/24] staging: unisys: include: Remove thread-related enum members David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 23/24] Documentation: Move visorbus documentation from staging to Documentation/ David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 02/24] staging: unisys: visorbus: remove unused struct David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 12/24] staging: unisys: visorbus: Remove unused functions David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200 [PATCH 03/24] staging: unisys: visorbus: modify format string to match argument David Kershner <david.kershner@unisys.com> - 2016-05-25 06:00 +0200
csiph-web