From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758327AbcFHVQI (ORCPT ); Wed, 8 Jun 2016 17:16:08 -0400 Received: from mail1.bemta8.messagelabs.com ([216.82.243.195]:58013 "EHLO mail1.bemta8.messagelabs.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1161816AbcFHVOr (ORCPT ); Wed, 8 Jun 2016 17:14:47 -0400 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFnrMIsWRWlGSWpSXmKPExsVywNY2U/doV0S 4wfR/ShYL25awWFzeNYfNgcnj8ya5AMYo1sy8pPyKBNaMh2frC359Zaz4eWUmawPj4SOMXYxc HEICuxglOl7PZINwDjFK/J96ixnOWb6wjQnCucQoMen2NXYIZy2jxIb1e6GcLYwSJ5YuBhrAy cEmYCAx885ddhBbROA8i8TTW7ldjBwczAJqEje+W4KEhQXCJM587mIGsVkEVCROXboNVs4r4C VxeMZTJhBbQkBO4uSxyawgNidQ/OGvtWBxIQFPiZZ3j9khbDWJw2cfsUHUB0sc+vyeFWKOoMT JmU9YQGxmAQmJgy9eME9gFJ6FJDULSWoBI9MqRo3i1KKy1CJdQwO9pKLM9IyS3MTMHCDPQi83 tbg4MT01JzGpWC85P3cTIzDAGYBgB+P6VudDjJIcTEqivGXuEeFCfEn5KZUZicUZ8UWlOanFh xhlODiUJHiTO4FygkWp6akVaZk5wFiDSUtw8CiJ8J4ESfMWFyTmFmemQ6ROMepyLNn1YC2TEE tefl6qlDjvYpAiAZCijNI8uBGwuL/EKCslzMsIdJQQT0FqUW5mCar8K0ZxDkYlYd5skCk8mXk lcJteAR3BBHTE8iPhIEeUJCKkpBoYC9va/iRcsI+YJi+1wH8S4/y1QuUN00SZXv6tO/kqiys8 2sAgbNOc2REx5qJ9HUl83ptVugvbrPySSizzwlS7V5Yfnzplr8+djG/fftZ0vvik6Przz1yXe 6Wrb234LbVRq6W52kHKq/Pt/fuGKZd1F7xkeK85t/Bh94bwF0qpqqyxxk/SvzApsRRnJBpqMR cVJwIAXnZv/vYCAAA= X-Env-Sender: David.Kershner@unisys.com X-Msg-Ref: server-12.tower-46.messagelabs.com!1465420483!29099597!9 X-Originating-IP: [192.61.61.105] X-StarScan-Received: X-StarScan-Version: 8.46; banners=-,-,- X-VirusChecked: Checked From: David Kershner To: , , , , , , , , , , , , , , , , , , , , , CC: Tim Sell Subject: [PATCH v4 18/29] staging: unisys: visorbus: fix commenting in visorbus_main.c Date: Wed, 8 Jun 2016 17:14:12 -0400 Message-ID: <1465420463-24982-19-git-send-email-david.kershner@unisys.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> References: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> X-OriginalArrivalTime: 08 Jun 2016 21:14:29.0037 (UTC) FILETIME=[BE478DD0:01D1C1CA] MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: David Binder This patch ONLY touches comment lines, i.e., NO executable code is affected. * All functions worthy of documenting now use standard kerneldoc formatting. * Improper uses of kerneldoc formatting were converted to standard multi-line comments. * Multi-line comments were tweaked so as to use appropriate conventions. Signed-off-by: David Binder Signed-off-by: Tim Sell Signed-off-by: David Kershner --- drivers/staging/unisys/visorbus/visorbus_main.c | 420 ++++++++++++++++-------- 1 file changed, 289 insertions(+), 131 deletions(-) diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c b/drivers/staging/unisys/visorbus/visorbus_main.c index 8c1754f9..2468264 100644 --- a/drivers/staging/unisys/visorbus/visorbus_main.c +++ b/drivers/staging/unisys/visorbus/visorbus_main.c @@ -44,11 +44,11 @@ static int visorbus_uevent(struct device *xdev, struct kobj_uevent_env *env); static int visorbus_match(struct device *xdev, struct device_driver *xdrv); static void fix_vbus_dev_info(struct visor_device *visordev); -/* BUS type attributes - * - * define & implement display of bus attributes under - * /sys/bus/visorbus. +/* + * BUS type attributes * + * define & implement display of bus attributes under + * /sys/bus/visorbus. */ static ssize_t version_show(struct bus_type *bus, char *buf) @@ -104,7 +104,8 @@ static const struct attribute_group *visorbus_dev_groups[] = { NULL, }; -/** This describes the TYPE of bus. +/* + * This describes the TYPE of bus. * (Don't confuse this with an INSTANCE of the bus.) */ struct bus_type visorbus_type = { @@ -115,8 +116,8 @@ struct bus_type visorbus_type = { .bus_groups = visorbus_bus_groups, }; -static long long bus_count; /** number of bus instances */ - /** ever-increasing */ +static long long bus_count; /* number of bus instances */ + /* ever-increasing */ static void chipset_bus_create(struct visor_device *bus_info); static void chipset_bus_destroy(struct visor_device *bus_info); @@ -125,8 +126,9 @@ static void chipset_device_destroy(struct visor_device *dev_info); static void chipset_device_pause(struct visor_device *dev_info); static void chipset_device_resume(struct visor_device *dev_info); -/** These functions are implemented herein, and are called by the chipset - * driver to notify us about specific events. +/* + * These functions are implemented herein, and are called by the chipset + * driver to notify us about specific events. */ static struct visorchipset_busdev_notifiers chipset_notifiers = { .bus_create = chipset_bus_create, @@ -137,8 +139,9 @@ static struct visorchipset_busdev_notifiers chipset_notifiers = { .device_resume = chipset_device_resume, }; -/** These functions are implemented in the chipset driver, and we call them - * herein when we want to acknowledge a specific event. +/* + * These functions are implemented in the chipset driver, and we call them + * herein when we want to acknowledge a specific event. */ static struct visorchipset_busdev_responders chipset_responders; @@ -147,9 +150,9 @@ static struct ultra_vbus_deviceinfo chipset_driverinfo; /* filled in with info about this driver, wrt it servicing client busses */ static struct ultra_vbus_deviceinfo clientbus_driverinfo; -/** list of visor_device structs, linked via .list_all */ +/* list of visor_device structs, linked via .list_all */ static LIST_HEAD(list_all_bus_instances); -/** list of visor_device structs, linked via .list_all */ +/* list of visor_device structs, linked via .list_all */ static LIST_HEAD(list_all_device_instances); static int @@ -166,9 +169,14 @@ visorbus_uevent(struct device *xdev, struct kobj_uevent_env *env) return 0; } -/* This is called automatically upon adding a visor_device (device_add), or - * adding a visor_driver (visorbus_register_visor_driver), and returns 1 iff the - * provided driver can control the specified device. +/** + * visorbus_match() - called automatically upon adding a visor_device + * (device_add), or adding a visor_driver + * (visorbus_register_visor_driver) + * @xdev: struct device for the device being matched + * @xdrv: struct device_driver for driver to match device against + * + * Return: 1 iff the provided driver can control the specified device */ static int visorbus_match(struct device *xdev, struct device_driver *xdrv) @@ -200,9 +208,11 @@ visorbus_match(struct device *xdev, struct device_driver *xdrv) return 0; } -/** This is called when device_unregister() is called for the bus device - * instance, after all other tasks involved with destroying the device - * are complete. +/** + * visorbus_releae_busdevice() - called when device_unregister() is called for + * the bus device instance, after all other tasks + * involved with destroying the dev are complete + * @xdev: struct device for the bus being released */ static void visorbus_release_busdevice(struct device *xdev) @@ -212,8 +222,10 @@ visorbus_release_busdevice(struct device *xdev) kfree(dev); } -/** This is called when device_unregister() is called for each child - * device instance. +/** + * visorbus_release_device() - called when device_unregister() is called for + * each child device instance + * @xdev: struct device for the visor device being released */ static void visorbus_release_device(struct device *xdev) @@ -227,9 +239,11 @@ visorbus_release_device(struct device *xdev) kfree(dev); } -/* begin implementation of specific channel attributes to appear under -* /sys/bus/visorbus/dev/channel -*/ +/* + * begin implementation of specific channel attributes to appear under + * /sys/bus/visorbus/dev/channel + */ + static ssize_t physaddr_show(struct device *dev, struct device_attribute *attr, char *buf) { @@ -334,15 +348,11 @@ static const struct attribute_group *visorbus_channel_groups[] = { /* end implementation of specific channel attributes */ -/* BUS instance attributes +/* + * BUS instance attributes * * define & implement display of bus attributes under - * /sys/bus/visorbus/busses/visorbus. - * - * This is a bit hoaky because the kernel does not yet have the infrastructure - * to separate bus INSTANCE attributes from bus TYPE attributes... - * so we roll our own. See businst.c / businst.h. - * + * /sys/bus/visorbus/devices/visorbus. */ static ssize_t partition_handle_show(struct device *dev, @@ -493,11 +503,11 @@ static const struct attribute_group *visorbus_groups[] = { NULL }; -/* DRIVER attributes +/* + * DRIVER attributes * * define & implement display of driver attributes under * /sys/bus/visorbus/drivers/. - * */ static ssize_t @@ -556,10 +566,20 @@ dev_stop_periodic_work(struct visor_device *dev) put_device(&dev->device); } -/** This is called automatically upon adding a visor_device (device_add), or - * adding a visor_driver (visorbus_register_visor_driver), but only after - * visorbus_match has returned 1 to indicate a successful match between - * driver and device. +/** + * visordriver_probe_device() - handle new visor device coming online + * @xdev: struct device for the visor device being probed + * + * This is called automatically upon adding a visor_device (device_add), or + * adding a visor_driver (visorbus_register_visor_driver), but only after + * visorbus_match() has returned 1 to indicate a successful match between + * driver and device. + * + * If successful, a reference to the device will be held onto via get_device(). + * + * Return: 0 if successful, meaning the function driver's probe() function + * was successful with this device, otherwise a negative errno + * value indicating failure reason */ static int visordriver_probe_device(struct device *xdev) @@ -588,9 +608,15 @@ visordriver_probe_device(struct device *xdev) return res; } -/** This is called when device_unregister() is called for each child device - * instance, to notify the appropriate visorbus_driver that the device is - * going away, and to decrease the reference count of the device. +/** + * visordriver_remove_device() - handle visor device going away + * @xdev: struct device for the visor device being removed + * + * This is called when device_unregister() is called for each child device + * instance, to notify the appropriate visorbus function driver that the device + * is going away, and to decrease the reference count of the device. + * + * Return: 0 iff successful */ static int visordriver_remove_device(struct device *xdev) @@ -611,47 +637,54 @@ 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 +/** + * visorbus_register_visor_driver() - registers the provided visor driver + * for handling one or more visor device + * types (channel_types) + * @drv: the driver to register * - * Here's how the whole Linux bus / driver / device model works. + * A visor function 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 * - * At system start-up, the visorbus kernel module is loaded, which registers - * visorbus_type as a bus type, using bus_register(). + * Here's how the whole Linux bus / driver / device model works. * - * 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): + * At system start-up, the visorbus kernel module is loaded, which registers + * visorbus_type as a bus type, using bus_register(). * - * 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()). + * 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): * - * 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(). + * 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 *drv) { @@ -666,7 +699,8 @@ int visorbus_register_visor_driver(struct visor_driver *drv) drv->driver.remove = visordriver_remove_device; drv->driver.owner = drv->owner; - /* driver_register does this: + /* + * driver_register does this: * bus_add_driver(drv) * ->if (drv.bus) ** (bus_type) ** * driver_attach(drv) @@ -688,8 +722,12 @@ int visorbus_register_visor_driver(struct visor_driver *drv) } EXPORT_SYMBOL_GPL(visorbus_register_visor_driver); -/** A particular type of visor driver calls this function to unregister - * the driver, i.e., within its module_exit function. +/** + * visorbus_unregister_visor_driver() - unregisters the provided driver + * @drv: the driver to unregister + * + * A visor function driver calls this function to unregister the driver, + * i.e., within its module_exit function. */ void visorbus_unregister_visor_driver(struct visor_driver *drv) @@ -699,6 +737,19 @@ visorbus_unregister_visor_driver(struct visor_driver *drv) } EXPORT_SYMBOL_GPL(visorbus_unregister_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) @@ -707,6 +758,19 @@ visorbus_read_channel(struct visor_device *dev, unsigned long offset, } EXPORT_SYMBOL_GPL(visorbus_read_channel); +/** + * 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) @@ -715,8 +779,13 @@ visorbus_write_channel(struct visor_device *dev, unsigned long offset, } EXPORT_SYMBOL_GPL(visorbus_write_channel); -/** We don't really have a real interrupt, so for now we just call the - * interrupt function periodically... +/** + * visorbus_enable_channel_interrupts() - enables interrupts on the + * designated device + * @dev: the device on which to enable interrupts + * + * Currently we don't yet have a real interrupt, so for now we just call the + * interrupt function periodically via a timer. */ void visorbus_enable_channel_interrupts(struct visor_device *dev) @@ -725,6 +794,11 @@ visorbus_enable_channel_interrupts(struct visor_device *dev) } EXPORT_SYMBOL_GPL(visorbus_enable_channel_interrupts); +/** + * 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) { @@ -732,19 +806,28 @@ visorbus_disable_channel_interrupts(struct visor_device *dev) } EXPORT_SYMBOL_GPL(visorbus_disable_channel_interrupts); -/** This is how everything starts from the device end. - * This function is called when a channel first appears via a ControlVM - * message. In response, this function allocates a visor_device to - * correspond to the new channel, and attempts to connect it the appropriate - * driver. If the appropriate driver is found, the visor_driver.probe() - * function for that driver will be called, and will be passed the new - * visor_device that we just created. +/** + * create_visor_device() - create visor device as a result of receiving the + * controlvm device_create message for a new device + * @dev: a freshly-zeroed struct visor_device, containing only filled-in values + * for chipset_bus_no and chipset_dev_no, that will be initialized + * + * This is how everything starts from the device end. + * This function is called when a channel first appears via a ControlVM + * message. In response, this function allocates a visor_device to + * correspond to the new channel, and attempts to connect it the appropriate + * driver. If the appropriate driver is found, the visor_driver.probe() + * function for that driver will be called, and will be passed the new + * visor_device that we just created. * - * It's ok if the appropriate driver is not yet loaded, because in that case - * the new device struct will just stick around in the bus' list of devices. - * When the appropriate driver calls visorbus_register_visor_driver(), the - * visor_driver.probe() for the new driver will be called with the new - * device. + * It's ok if the appropriate driver is not yet loaded, because in that case + * the new device struct will just stick around in the bus' list of devices. + * When the appropriate driver calls visorbus_register_visor_driver(), the + * visor_driver.probe() for the new driver will be called with the new + * device. + * + * Return: 0 if successful, otherwise the negative value returned by + * device_add() indicating the reason for failure */ static int create_visor_device(struct visor_device *dev) @@ -767,14 +850,16 @@ create_visor_device(struct visor_device *dev) dev->timer.data = (unsigned long)(dev); dev->timer.function = dev_periodic_work; - /* bus_id must be a unique name with respect to this bus TYPE + /* + * bus_id must be a unique name with respect to this bus TYPE * (NOT bus instance). That's why we need to include the bus * number within the name. */ dev_set_name(&dev->device, "vbus%u:dev%u", chipset_bus_no, chipset_dev_no); - /* device_add does this: + /* + * device_add does this: * bus_add_device(dev) * ->device_attach(dev) * ->for each driver drv registered on the bus that dev is on @@ -834,13 +919,19 @@ get_vbus_header_info(struct visorchannel *chan, return 0; } -/* Write the contents of to the struct - * spar_vbus_channel_protocol.chp_info. +/** + * write_vbus_chp_info() - write the contents of to the struct + * spar_vbus_channel_protocol.chp_info + * @chan: indentifies the s-Par channel that will be updated + * @hdr_info: used to find appropriate channel offset to write data + * @info: contains the information to write + * + * Writes chipset info into the channel memory to be used for diagnostic + * purposes. * - * Returns void since this is debug information and not needed for + * Returns no value since this is debug information and not needed for * device functionality. */ - static void write_vbus_chp_info(struct visorchannel *chan, struct spar_vbus_headerinfo *hdr_info, @@ -854,13 +945,19 @@ write_vbus_chp_info(struct visorchannel *chan, visorchannel_write(chan, off, info, sizeof(*info)); } -/* Write the contents of to the struct - * spar_vbus_channel_protocol.bus_info. +/** + * write_vbus_bus_info() - write the contents of to the struct + * spar_vbus_channel_protocol.bus_info + * @chan: indentifies the s-Par channel that will be updated + * @hdr_info: used to find appropriate channel offset to write data + * @info: contains the information to write + * + * Writes bus info into the channel memory to be used for diagnostic + * purposes. * - * Returns void since this is debug information and not needed for + * Returns no value since this is debug information and not needed for * device functionality. */ - static void write_vbus_bus_info(struct visorchannel *chan, struct spar_vbus_headerinfo *hdr_info, @@ -874,10 +971,18 @@ write_vbus_bus_info(struct visorchannel *chan, visorchannel_write(chan, off, info, sizeof(*info)); } -/* Write the contents of to the - * struct spar_vbus_channel_protocol.dev_info[]. +/** + * write_vbus_dev_info() - write the contents of to the struct + * spar_vbus_channel_protocol.dev_info[] + * @chan: indentifies the s-Par channel that will be updated + * @hdr_info: used to find appropriate channel offset to write data + * @info: contains the information to write + * @devix: the relative device number (0..n-1) of the device on the bus * - * Returns void since this is debug information and not needed for + * Writes device info into the channel memory to be used for diagnostic + * purposes. + * + * Returns no value since this is debug information and not needed for * device functionality. */ static void @@ -895,10 +1000,12 @@ write_vbus_dev_info(struct visorchannel *chan, visorchannel_write(chan, off, info, sizeof(*info)); } -/* For a child device just created on a client bus, fill in - * information about the driver that is controlling this device into - * the the appropriate slot within the vbus channel of the bus - * instance. +/** + * fix_vbus_dev_info() - for a child device just created on a client bus, fill + * in information about the driver that is controlling + * this device into the the appropriate slot within the + * vbus channel of the bus instance + * @visordev: struct visor_device for the desired device */ static void fix_vbus_dev_info(struct visor_device *visordev) @@ -925,7 +1032,8 @@ fix_vbus_dev_info(struct visor_device *visordev) visordrv = to_visor_driver(visordev->device.driver); - /* Within the list of device types (by GUID) that the driver + /* + * Within the list of device types (by GUID) that the driver * says it supports, find out which one of those types matches * the type of this device, so that we can include the device * type name @@ -944,15 +1052,21 @@ fix_vbus_dev_info(struct visor_device *visordev) visordrv->vertag); write_vbus_dev_info(bdev->visorchannel, hdr_info, &dev_info, dev_no); - /* Re-write bus+chipset info, because it is possible that this - * was previously written by our evil counterpart, virtpci. - */ + /* + * Re-write bus+chipset info, because it is possible that this + * was previously written by our evil counterpart, virtpci. + */ write_vbus_chp_info(bdev->visorchannel, hdr_info, &chipset_driverinfo); write_vbus_bus_info(bdev->visorchannel, hdr_info, &clientbus_driverinfo); } -/** Create a device instance for the visor bus itself. +/** + * create_bus_instance() - create a device instance for the visor bus itself + * @dev: struct visor_device indicating the bus instance + * + * Return: 0 for success, otherwise negative errno value indicating reason for + * failure */ static int create_bus_instance(struct visor_device *dev) @@ -993,12 +1107,15 @@ create_bus_instance(struct visor_device *dev) return 0; } -/** Remove a device instance for the visor bus itself. +/** + * remove_bus_instance() - remove a device instance for the visor bus itself + * @dev: struct visor_device indentifying the bus to remove */ static void remove_bus_instance(struct visor_device *dev) { - /* Note that this will result in the release method for + /* + * Note that this will result in the release method for * dev->dev being called, which will call * visorbus_release_busdevice(). This has something to do with * the put_device() done in device_unregister(), but I have never @@ -1015,8 +1132,11 @@ remove_bus_instance(struct visor_device *dev) device_unregister(&dev->device); } -/** Create and register the one-and-only one instance of - * the visor bus type (visorbus_type). +/** + * create_bus_type() - create and register the one-and-only one instance of + * the visor bus type (visorbus_type) + * Return: 0 for success, otherwise negative errno value returned by + * bus_register() indicating the reason for failure */ static int create_bus_type(void) @@ -1025,7 +1145,9 @@ create_bus_type(void) return busreg_rc; } -/** Remove the one-and-only one instance of the visor bus type (visorbus_type). +/** + * remove_bus_type() - remove the one-and-only one instance of the visor bus + * type (visorbus_type) */ static void remove_bus_type(void) @@ -1033,7 +1155,8 @@ remove_bus_type(void) bus_unregister(&visorbus_type); } -/** Remove all child visor bus device instances. +/** + * remove_all_visor_devices() - remove all child visor bus device instances */ static void remove_all_visor_devices(void) @@ -1108,9 +1231,14 @@ chipset_device_destroy(struct visor_device *dev_info) (*chipset_responders.device_destroy) (dev_info, 0); } -/* This is the callback function specified for a function driver, to - * be called when a pending "pause device" operation has been - * completed. +/** + * pause_state_change_complete() - the callback function to be called by a + * visorbus function driver when a + * pending "pause device" operation has + * completed + * @dev: struct visor_device identifying the paused device + * @status: 0 iff the pause state change completed successfully, otherwise + * a negative errno value indicating the reason for failure */ static void pause_state_change_complete(struct visor_device *dev, int status) @@ -1129,9 +1257,14 @@ pause_state_change_complete(struct visor_device *dev, int status) (*chipset_responders.device_pause) (dev, status); } -/* This is the callback function specified for a function driver, to - * be called when a pending "resume device" operation has been - * completed. +/** + * resume_state_change_complete() - the callback function to be called by a + * visorbus function driver when a + * pending "resume device" operation has + * completed + * @dev: struct visor_device identifying the resumed device + * @status: 0 iff the resume state change completed successfully, otherwise + * a negative errno value indicating the reason for failure */ static void resume_state_change_complete(struct visor_device *dev, int status) @@ -1143,16 +1276,24 @@ resume_state_change_complete(struct visor_device *dev, int status) if (!chipset_responders.device_resume) /* this can never happen! */ return; - /* Notify the chipset driver that the resume is complete, + /* + * Notify the chipset driver that the resume is complete, * which will presumably want to send some sort of response to * the initiator. */ (*chipset_responders.device_resume) (dev, status); } -/* Tell the subordinate function driver for a specific device to pause - * or resume that device. Result is returned asynchronously via a - * callback function. +/** + * initiate_chipset_device_pause_resume() - start a pause or resume operation + * for a visor device + * @dev: struct visor_device identifying the device being paused or resumed + * @is_pause: true to indicate pause operation, false to indicate resume + * + * Tell the subordinate function driver for a specific device to pause + * or resume that device. Success/failure result is returned asynchronously + * via a callback function; see pause_state_change_complete() and + * resume_state_change_complete(). */ static void initiate_chipset_device_pause_resume(struct visor_device *dev, bool is_pause) @@ -1179,7 +1320,8 @@ initiate_chipset_device_pause_resume(struct visor_device *dev, bool is_pause) return; } - /* Note that even though both drv->pause() and drv->resume + /* + * Note that even though both drv->pause() and drv->resume * specify a callback function, it is NOT necessary for us to * increment our local module usage count. Reason is, there * is already a linkage dependency between child function @@ -1219,12 +1361,28 @@ initiate_chipset_device_pause_resume(struct visor_device *dev, bool is_pause) } } +/** + * chipset_device_pause() - start a pause operation for a visor device + * @dev_info: struct visor_device identifying the device being paused + * + * Tell the subordinate function driver for a specific device to pause + * that device. Success/failure result is returned asynchronously + * via a callback function; see pause_state_change_complete(). + */ static void chipset_device_pause(struct visor_device *dev_info) { initiate_chipset_device_pause_resume(dev_info, true); } +/** + * chipset_device_resume() - start a resume operation for a visor device + * @dev_info: struct visor_device identifying the device being resumed + * + * Tell the subordinate function driver for a specific device to resume + * that device. Success/failure result is returned asynchronously + * via a callback function; see resume_state_change_complete(). + */ static void chipset_device_resume(struct visor_device *dev_info) { -- 1.9.1 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from silver.osuosl.org (smtp3.osuosl.org [140.211.166.136]) by ash.osuosl.org (Postfix) with ESMTP id 14FFB1C0D7B for ; Wed, 8 Jun 2016 21:14:44 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id EAF192FF02 for ; Wed, 8 Jun 2016 21:14:43 +0000 (UTC) Received: from silver.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id NMr6oF2nWiFq for ; Wed, 8 Jun 2016 21:14:39 +0000 (UTC) Received: from mail1.bemta12.messagelabs.com (mail1.bemta12.messagelabs.com [216.82.251.12]) by silver.osuosl.org (Postfix) with ESMTPS id E325230E7E for ; Wed, 8 Jun 2016 21:14:38 +0000 (UTC) From: David Kershner Subject: [PATCH v4 18/29] staging: unisys: visorbus: fix commenting in visorbus_main.c Date: Wed, 8 Jun 2016 17:14:12 -0400 Message-ID: <1465420463-24982-19-git-send-email-david.kershner@unisys.com> In-Reply-To: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> References: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> MIME-Version: 1.0 List-Id: Linux Driver Project Developer List List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: driverdev-devel-bounces@linuxdriverproject.org Sender: "devel" To: corbet@lwn.net, tglx@linutronix.de, mingo@redhat.com, hpa@zytor.com, david.kershner@unisys.com, gregkh@linuxfoundation.org, erik.arfvidson@unisys.com, timothy.sell@unisys.com, hofrat@osadl.org, dzickus@redhat.com, jes.sorensen@redhat.com, alexander.curtin@unisys.com, janani.rvchndrn@gmail.com, sudipm.mukherjee@gmail.com, prarit@redhat.com, david.binder@unisys.com, nhorman@redhat.com, dan.j.williams@intel.com, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, driverdev-devel@linuxdriverproject.org, sparmaintainer@unisys.com Cc: Tim Sell From: David Binder This patch ONLY touches comment lines, i.e., NO executable code is affected. * All functions worthy of documenting now use standard kerneldoc formatting. * Improper uses of kerneldoc formatting were converted to standard multi-line comments. * Multi-line comments were tweaked so as to use appropriate conventions. Signed-off-by: David Binder Signed-off-by: Tim Sell Signed-off-by: David Kershner --- drivers/staging/unisys/visorbus/visorbus_main.c | 420 ++++++++++++++++-------- 1 file changed, 289 insertions(+), 131 deletions(-) diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c b/drivers/staging/unisys/visorbus/visorbus_main.c index 8c1754f9..2468264 100644 --- a/drivers/staging/unisys/visorbus/visorbus_main.c +++ b/drivers/staging/unisys/visorbus/visorbus_main.c @@ -44,11 +44,11 @@ static int visorbus_uevent(struct device *xdev, struct kobj_uevent_env *env); static int visorbus_match(struct device *xdev, struct device_driver *xdrv); static void fix_vbus_dev_info(struct visor_device *visordev); -/* BUS type attributes - * - * define & implement display of bus attributes under - * /sys/bus/visorbus. +/* + * BUS type attributes * + * define & implement display of bus attributes under + * /sys/bus/visorbus. */ static ssize_t version_show(struct bus_type *bus, char *buf) @@ -104,7 +104,8 @@ static const struct attribute_group *visorbus_dev_groups[] = { NULL, }; -/** This describes the TYPE of bus. +/* + * This describes the TYPE of bus. * (Don't confuse this with an INSTANCE of the bus.) */ struct bus_type visorbus_type = { @@ -115,8 +116,8 @@ struct bus_type visorbus_type = { .bus_groups = visorbus_bus_groups, }; -static long long bus_count; /** number of bus instances */ - /** ever-increasing */ +static long long bus_count; /* number of bus instances */ + /* ever-increasing */ static void chipset_bus_create(struct visor_device *bus_info); static void chipset_bus_destroy(struct visor_device *bus_info); @@ -125,8 +126,9 @@ static void chipset_device_destroy(struct visor_device *dev_info); static void chipset_device_pause(struct visor_device *dev_info); static void chipset_device_resume(struct visor_device *dev_info); -/** These functions are implemented herein, and are called by the chipset - * driver to notify us about specific events. +/* + * These functions are implemented herein, and are called by the chipset + * driver to notify us about specific events. */ static struct visorchipset_busdev_notifiers chipset_notifiers = { .bus_create = chipset_bus_create, @@ -137,8 +139,9 @@ static struct visorchipset_busdev_notifiers chipset_notifiers = { .device_resume = chipset_device_resume, }; -/** These functions are implemented in the chipset driver, and we call them - * herein when we want to acknowledge a specific event. +/* + * These functions are implemented in the chipset driver, and we call them + * herein when we want to acknowledge a specific event. */ static struct visorchipset_busdev_responders chipset_responders; @@ -147,9 +150,9 @@ static struct ultra_vbus_deviceinfo chipset_driverinfo; /* filled in with info about this driver, wrt it servicing client busses */ static struct ultra_vbus_deviceinfo clientbus_driverinfo; -/** list of visor_device structs, linked via .list_all */ +/* list of visor_device structs, linked via .list_all */ static LIST_HEAD(list_all_bus_instances); -/** list of visor_device structs, linked via .list_all */ +/* list of visor_device structs, linked via .list_all */ static LIST_HEAD(list_all_device_instances); static int @@ -166,9 +169,14 @@ visorbus_uevent(struct device *xdev, struct kobj_uevent_env *env) return 0; } -/* This is called automatically upon adding a visor_device (device_add), or - * adding a visor_driver (visorbus_register_visor_driver), and returns 1 iff the - * provided driver can control the specified device. +/** + * visorbus_match() - called automatically upon adding a visor_device + * (device_add), or adding a visor_driver + * (visorbus_register_visor_driver) + * @xdev: struct device for the device being matched + * @xdrv: struct device_driver for driver to match device against + * + * Return: 1 iff the provided driver can control the specified device */ static int visorbus_match(struct device *xdev, struct device_driver *xdrv) @@ -200,9 +208,11 @@ visorbus_match(struct device *xdev, struct device_driver *xdrv) return 0; } -/** This is called when device_unregister() is called for the bus device - * instance, after all other tasks involved with destroying the device - * are complete. +/** + * visorbus_releae_busdevice() - called when device_unregister() is called for + * the bus device instance, after all other tasks + * involved with destroying the dev are complete + * @xdev: struct device for the bus being released */ static void visorbus_release_busdevice(struct device *xdev) @@ -212,8 +222,10 @@ visorbus_release_busdevice(struct device *xdev) kfree(dev); } -/** This is called when device_unregister() is called for each child - * device instance. +/** + * visorbus_release_device() - called when device_unregister() is called for + * each child device instance + * @xdev: struct device for the visor device being released */ static void visorbus_release_device(struct device *xdev) @@ -227,9 +239,11 @@ visorbus_release_device(struct device *xdev) kfree(dev); } -/* begin implementation of specific channel attributes to appear under -* /sys/bus/visorbus/dev/channel -*/ +/* + * begin implementation of specific channel attributes to appear under + * /sys/bus/visorbus/dev/channel + */ + static ssize_t physaddr_show(struct device *dev, struct device_attribute *attr, char *buf) { @@ -334,15 +348,11 @@ static const struct attribute_group *visorbus_channel_groups[] = { /* end implementation of specific channel attributes */ -/* BUS instance attributes +/* + * BUS instance attributes * * define & implement display of bus attributes under - * /sys/bus/visorbus/busses/visorbus. - * - * This is a bit hoaky because the kernel does not yet have the infrastructure - * to separate bus INSTANCE attributes from bus TYPE attributes... - * so we roll our own. See businst.c / businst.h. - * + * /sys/bus/visorbus/devices/visorbus. */ static ssize_t partition_handle_show(struct device *dev, @@ -493,11 +503,11 @@ static const struct attribute_group *visorbus_groups[] = { NULL }; -/* DRIVER attributes +/* + * DRIVER attributes * * define & implement display of driver attributes under * /sys/bus/visorbus/drivers/. - * */ static ssize_t @@ -556,10 +566,20 @@ dev_stop_periodic_work(struct visor_device *dev) put_device(&dev->device); } -/** This is called automatically upon adding a visor_device (device_add), or - * adding a visor_driver (visorbus_register_visor_driver), but only after - * visorbus_match has returned 1 to indicate a successful match between - * driver and device. +/** + * visordriver_probe_device() - handle new visor device coming online + * @xdev: struct device for the visor device being probed + * + * This is called automatically upon adding a visor_device (device_add), or + * adding a visor_driver (visorbus_register_visor_driver), but only after + * visorbus_match() has returned 1 to indicate a successful match between + * driver and device. + * + * If successful, a reference to the device will be held onto via get_device(). + * + * Return: 0 if successful, meaning the function driver's probe() function + * was successful with this device, otherwise a negative errno + * value indicating failure reason */ static int visordriver_probe_device(struct device *xdev) @@ -588,9 +608,15 @@ visordriver_probe_device(struct device *xdev) return res; } -/** This is called when device_unregister() is called for each child device - * instance, to notify the appropriate visorbus_driver that the device is - * going away, and to decrease the reference count of the device. +/** + * visordriver_remove_device() - handle visor device going away + * @xdev: struct device for the visor device being removed + * + * This is called when device_unregister() is called for each child device + * instance, to notify the appropriate visorbus function driver that the device + * is going away, and to decrease the reference count of the device. + * + * Return: 0 iff successful */ static int visordriver_remove_device(struct device *xdev) @@ -611,47 +637,54 @@ 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 +/** + * visorbus_register_visor_driver() - registers the provided visor driver + * for handling one or more visor device + * types (channel_types) + * @drv: the driver to register * - * Here's how the whole Linux bus / driver / device model works. + * A visor function 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 * - * At system start-up, the visorbus kernel module is loaded, which registers - * visorbus_type as a bus type, using bus_register(). + * Here's how the whole Linux bus / driver / device model works. * - * 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): + * At system start-up, the visorbus kernel module is loaded, which registers + * visorbus_type as a bus type, using bus_register(). * - * 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()). + * 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): * - * 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(). + * 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 *drv) { @@ -666,7 +699,8 @@ int visorbus_register_visor_driver(struct visor_driver *drv) drv->driver.remove = visordriver_remove_device; drv->driver.owner = drv->owner; - /* driver_register does this: + /* + * driver_register does this: * bus_add_driver(drv) * ->if (drv.bus) ** (bus_type) ** * driver_attach(drv) @@ -688,8 +722,12 @@ int visorbus_register_visor_driver(struct visor_driver *drv) } EXPORT_SYMBOL_GPL(visorbus_register_visor_driver); -/** A particular type of visor driver calls this function to unregister - * the driver, i.e., within its module_exit function. +/** + * visorbus_unregister_visor_driver() - unregisters the provided driver + * @drv: the driver to unregister + * + * A visor function driver calls this function to unregister the driver, + * i.e., within its module_exit function. */ void visorbus_unregister_visor_driver(struct visor_driver *drv) @@ -699,6 +737,19 @@ visorbus_unregister_visor_driver(struct visor_driver *drv) } EXPORT_SYMBOL_GPL(visorbus_unregister_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) @@ -707,6 +758,19 @@ visorbus_read_channel(struct visor_device *dev, unsigned long offset, } EXPORT_SYMBOL_GPL(visorbus_read_channel); +/** + * 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) @@ -715,8 +779,13 @@ visorbus_write_channel(struct visor_device *dev, unsigned long offset, } EXPORT_SYMBOL_GPL(visorbus_write_channel); -/** We don't really have a real interrupt, so for now we just call the - * interrupt function periodically... +/** + * visorbus_enable_channel_interrupts() - enables interrupts on the + * designated device + * @dev: the device on which to enable interrupts + * + * Currently we don't yet have a real interrupt, so for now we just call the + * interrupt function periodically via a timer. */ void visorbus_enable_channel_interrupts(struct visor_device *dev) @@ -725,6 +794,11 @@ visorbus_enable_channel_interrupts(struct visor_device *dev) } EXPORT_SYMBOL_GPL(visorbus_enable_channel_interrupts); +/** + * 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) { @@ -732,19 +806,28 @@ visorbus_disable_channel_interrupts(struct visor_device *dev) } EXPORT_SYMBOL_GPL(visorbus_disable_channel_interrupts); -/** This is how everything starts from the device end. - * This function is called when a channel first appears via a ControlVM - * message. In response, this function allocates a visor_device to - * correspond to the new channel, and attempts to connect it the appropriate - * driver. If the appropriate driver is found, the visor_driver.probe() - * function for that driver will be called, and will be passed the new - * visor_device that we just created. +/** + * create_visor_device() - create visor device as a result of receiving the + * controlvm device_create message for a new device + * @dev: a freshly-zeroed struct visor_device, containing only filled-in values + * for chipset_bus_no and chipset_dev_no, that will be initialized + * + * This is how everything starts from the device end. + * This function is called when a channel first appears via a ControlVM + * message. In response, this function allocates a visor_device to + * correspond to the new channel, and attempts to connect it the appropriate + * driver. If the appropriate driver is found, the visor_driver.probe() + * function for that driver will be called, and will be passed the new + * visor_device that we just created. * - * It's ok if the appropriate driver is not yet loaded, because in that case - * the new device struct will just stick around in the bus' list of devices. - * When the appropriate driver calls visorbus_register_visor_driver(), the - * visor_driver.probe() for the new driver will be called with the new - * device. + * It's ok if the appropriate driver is not yet loaded, because in that case + * the new device struct will just stick around in the bus' list of devices. + * When the appropriate driver calls visorbus_register_visor_driver(), the + * visor_driver.probe() for the new driver will be called with the new + * device. + * + * Return: 0 if successful, otherwise the negative value returned by + * device_add() indicating the reason for failure */ static int create_visor_device(struct visor_device *dev) @@ -767,14 +850,16 @@ create_visor_device(struct visor_device *dev) dev->timer.data = (unsigned long)(dev); dev->timer.function = dev_periodic_work; - /* bus_id must be a unique name with respect to this bus TYPE + /* + * bus_id must be a unique name with respect to this bus TYPE * (NOT bus instance). That's why we need to include the bus * number within the name. */ dev_set_name(&dev->device, "vbus%u:dev%u", chipset_bus_no, chipset_dev_no); - /* device_add does this: + /* + * device_add does this: * bus_add_device(dev) * ->device_attach(dev) * ->for each driver drv registered on the bus that dev is on @@ -834,13 +919,19 @@ get_vbus_header_info(struct visorchannel *chan, return 0; } -/* Write the contents of to the struct - * spar_vbus_channel_protocol.chp_info. +/** + * write_vbus_chp_info() - write the contents of to the struct + * spar_vbus_channel_protocol.chp_info + * @chan: indentifies the s-Par channel that will be updated + * @hdr_info: used to find appropriate channel offset to write data + * @info: contains the information to write + * + * Writes chipset info into the channel memory to be used for diagnostic + * purposes. * - * Returns void since this is debug information and not needed for + * Returns no value since this is debug information and not needed for * device functionality. */ - static void write_vbus_chp_info(struct visorchannel *chan, struct spar_vbus_headerinfo *hdr_info, @@ -854,13 +945,19 @@ write_vbus_chp_info(struct visorchannel *chan, visorchannel_write(chan, off, info, sizeof(*info)); } -/* Write the contents of to the struct - * spar_vbus_channel_protocol.bus_info. +/** + * write_vbus_bus_info() - write the contents of to the struct + * spar_vbus_channel_protocol.bus_info + * @chan: indentifies the s-Par channel that will be updated + * @hdr_info: used to find appropriate channel offset to write data + * @info: contains the information to write + * + * Writes bus info into the channel memory to be used for diagnostic + * purposes. * - * Returns void since this is debug information and not needed for + * Returns no value since this is debug information and not needed for * device functionality. */ - static void write_vbus_bus_info(struct visorchannel *chan, struct spar_vbus_headerinfo *hdr_info, @@ -874,10 +971,18 @@ write_vbus_bus_info(struct visorchannel *chan, visorchannel_write(chan, off, info, sizeof(*info)); } -/* Write the contents of to the - * struct spar_vbus_channel_protocol.dev_info[]. +/** + * write_vbus_dev_info() - write the contents of to the struct + * spar_vbus_channel_protocol.dev_info[] + * @chan: indentifies the s-Par channel that will be updated + * @hdr_info: used to find appropriate channel offset to write data + * @info: contains the information to write + * @devix: the relative device number (0..n-1) of the device on the bus * - * Returns void since this is debug information and not needed for + * Writes device info into the channel memory to be used for diagnostic + * purposes. + * + * Returns no value since this is debug information and not needed for * device functionality. */ static void @@ -895,10 +1000,12 @@ write_vbus_dev_info(struct visorchannel *chan, visorchannel_write(chan, off, info, sizeof(*info)); } -/* For a child device just created on a client bus, fill in - * information about the driver that is controlling this device into - * the the appropriate slot within the vbus channel of the bus - * instance. +/** + * fix_vbus_dev_info() - for a child device just created on a client bus, fill + * in information about the driver that is controlling + * this device into the the appropriate slot within the + * vbus channel of the bus instance + * @visordev: struct visor_device for the desired device */ static void fix_vbus_dev_info(struct visor_device *visordev) @@ -925,7 +1032,8 @@ fix_vbus_dev_info(struct visor_device *visordev) visordrv = to_visor_driver(visordev->device.driver); - /* Within the list of device types (by GUID) that the driver + /* + * Within the list of device types (by GUID) that the driver * says it supports, find out which one of those types matches * the type of this device, so that we can include the device * type name @@ -944,15 +1052,21 @@ fix_vbus_dev_info(struct visor_device *visordev) visordrv->vertag); write_vbus_dev_info(bdev->visorchannel, hdr_info, &dev_info, dev_no); - /* Re-write bus+chipset info, because it is possible that this - * was previously written by our evil counterpart, virtpci. - */ + /* + * Re-write bus+chipset info, because it is possible that this + * was previously written by our evil counterpart, virtpci. + */ write_vbus_chp_info(bdev->visorchannel, hdr_info, &chipset_driverinfo); write_vbus_bus_info(bdev->visorchannel, hdr_info, &clientbus_driverinfo); } -/** Create a device instance for the visor bus itself. +/** + * create_bus_instance() - create a device instance for the visor bus itself + * @dev: struct visor_device indicating the bus instance + * + * Return: 0 for success, otherwise negative errno value indicating reason for + * failure */ static int create_bus_instance(struct visor_device *dev) @@ -993,12 +1107,15 @@ create_bus_instance(struct visor_device *dev) return 0; } -/** Remove a device instance for the visor bus itself. +/** + * remove_bus_instance() - remove a device instance for the visor bus itself + * @dev: struct visor_device indentifying the bus to remove */ static void remove_bus_instance(struct visor_device *dev) { - /* Note that this will result in the release method for + /* + * Note that this will result in the release method for * dev->dev being called, which will call * visorbus_release_busdevice(). This has something to do with * the put_device() done in device_unregister(), but I have never @@ -1015,8 +1132,11 @@ remove_bus_instance(struct visor_device *dev) device_unregister(&dev->device); } -/** Create and register the one-and-only one instance of - * the visor bus type (visorbus_type). +/** + * create_bus_type() - create and register the one-and-only one instance of + * the visor bus type (visorbus_type) + * Return: 0 for success, otherwise negative errno value returned by + * bus_register() indicating the reason for failure */ static int create_bus_type(void) @@ -1025,7 +1145,9 @@ create_bus_type(void) return busreg_rc; } -/** Remove the one-and-only one instance of the visor bus type (visorbus_type). +/** + * remove_bus_type() - remove the one-and-only one instance of the visor bus + * type (visorbus_type) */ static void remove_bus_type(void) @@ -1033,7 +1155,8 @@ remove_bus_type(void) bus_unregister(&visorbus_type); } -/** Remove all child visor bus device instances. +/** + * remove_all_visor_devices() - remove all child visor bus device instances */ static void remove_all_visor_devices(void) @@ -1108,9 +1231,14 @@ chipset_device_destroy(struct visor_device *dev_info) (*chipset_responders.device_destroy) (dev_info, 0); } -/* This is the callback function specified for a function driver, to - * be called when a pending "pause device" operation has been - * completed. +/** + * pause_state_change_complete() - the callback function to be called by a + * visorbus function driver when a + * pending "pause device" operation has + * completed + * @dev: struct visor_device identifying the paused device + * @status: 0 iff the pause state change completed successfully, otherwise + * a negative errno value indicating the reason for failure */ static void pause_state_change_complete(struct visor_device *dev, int status) @@ -1129,9 +1257,14 @@ pause_state_change_complete(struct visor_device *dev, int status) (*chipset_responders.device_pause) (dev, status); } -/* This is the callback function specified for a function driver, to - * be called when a pending "resume device" operation has been - * completed. +/** + * resume_state_change_complete() - the callback function to be called by a + * visorbus function driver when a + * pending "resume device" operation has + * completed + * @dev: struct visor_device identifying the resumed device + * @status: 0 iff the resume state change completed successfully, otherwise + * a negative errno value indicating the reason for failure */ static void resume_state_change_complete(struct visor_device *dev, int status) @@ -1143,16 +1276,24 @@ resume_state_change_complete(struct visor_device *dev, int status) if (!chipset_responders.device_resume) /* this can never happen! */ return; - /* Notify the chipset driver that the resume is complete, + /* + * Notify the chipset driver that the resume is complete, * which will presumably want to send some sort of response to * the initiator. */ (*chipset_responders.device_resume) (dev, status); } -/* Tell the subordinate function driver for a specific device to pause - * or resume that device. Result is returned asynchronously via a - * callback function. +/** + * initiate_chipset_device_pause_resume() - start a pause or resume operation + * for a visor device + * @dev: struct visor_device identifying the device being paused or resumed + * @is_pause: true to indicate pause operation, false to indicate resume + * + * Tell the subordinate function driver for a specific device to pause + * or resume that device. Success/failure result is returned asynchronously + * via a callback function; see pause_state_change_complete() and + * resume_state_change_complete(). */ static void initiate_chipset_device_pause_resume(struct visor_device *dev, bool is_pause) @@ -1179,7 +1320,8 @@ initiate_chipset_device_pause_resume(struct visor_device *dev, bool is_pause) return; } - /* Note that even though both drv->pause() and drv->resume + /* + * Note that even though both drv->pause() and drv->resume * specify a callback function, it is NOT necessary for us to * increment our local module usage count. Reason is, there * is already a linkage dependency between child function @@ -1219,12 +1361,28 @@ initiate_chipset_device_pause_resume(struct visor_device *dev, bool is_pause) } } +/** + * chipset_device_pause() - start a pause operation for a visor device + * @dev_info: struct visor_device identifying the device being paused + * + * Tell the subordinate function driver for a specific device to pause + * that device. Success/failure result is returned asynchronously + * via a callback function; see pause_state_change_complete(). + */ static void chipset_device_pause(struct visor_device *dev_info) { initiate_chipset_device_pause_resume(dev_info, true); } +/** + * chipset_device_resume() - start a resume operation for a visor device + * @dev_info: struct visor_device identifying the device being resumed + * + * Tell the subordinate function driver for a specific device to resume + * that device. Success/failure result is returned asynchronously + * via a callback function; see resume_state_change_complete(). + */ static void chipset_device_resume(struct visor_device *dev_info) { -- 1.9.1 _______________________________________________ devel mailing list devel@linuxdriverproject.org http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel