| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <1464147962-26650-21-git-send-email-david.kershner@unisys.com>
Date: Tue, 24 May 2016 23:45:58 -0400
From: David Kershner <david.kershner@...sys.com>
To: <corbet@....net>, <tglx@...utronix.de>, <mingo@...hat.com>,
<hpa@...or.com>, <david.kershner@...sys.com>,
<gregkh@...uxfoundation.org>, <erik.arfvidson@...sys.com>,
<timothy.sell@...sys.com>, <hofrat@...dl.org>,
<dzickus@...hat.com>, <jes.sorensen@...hat.com>,
<alexander.curtin@...sys.com>, <janani.rvchndrn@...il.com>,
<sudipm.mukherjee@...il.com>, <prarit@...hat.com>,
<david.binder@...sys.com>, <nhorman@...hat.com>,
<dan.j.williams@...el.com>, <linux-kernel@...r.kernel.org>,
<linux-doc@...r.kernel.org>,
<driverdev-devel@...uxdriverproject.org>,
<sparmaintainer@...sys.com>
Subject: [PATCH 20/24] staging: unisys: visorbus: Add kerneldoc-style comments for visorbus API
From: David Binder <david.binder@...sys.com>
Adds kerneldoc-style comments for those functions which may be used outside
of the visorbus driver.
Signed-off-by: David Binder <david.binder@...sys.com>
Signed-off-by: David Kershner <david.kershner@...sys.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
Powered by blists - more mailing lists