hollalinux
/
linux-sg2042
mirror of https://github.com/sophgo/linux-riscv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

staging: unisys: visorbus: fix commenting in visorbus_main.c 

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 <david.binder@unisys.com>
Signed-off-by: Tim Sell <Timothy.Sell@unisys.com>
Signed-off-by: David Kershner <david.kershner@unisys.com>
Acked-By: Neil Horman <nhorman@tuxdriver.com>
Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
David Binder 2016-06-10 21:48:16 -04:00 committed by Greg Kroah-Hartman
parent 0048be9e1e
commit 3fd1b3b682
1 changed files with 289 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

314
drivers/staging/unisys/visorbus/visorbus_main.c
View File

@ -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
/*
* 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,7 +126,8 @@ 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
/*
* 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 = {
@ -137,7 +139,8 @@ static struct visorchipset_busdev_notifiers chipset_notifiers = {
.device_resume = chipset_device_resume,
};
/** These functions are implemented in the chipset driver, and we call them
/*
* 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<x>/dev<y>/channel
*/
/*
* begin implementation of specific channel attributes to appear under
* /sys/bus/visorbus<x>/dev<y>/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<n>.
*
* 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<n>.
*/
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/<drivername>.
*
*/
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
/**
* 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
* 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,7 +637,13 @@ visordriver_remove_device(struct device *xdev)
return 0;
}
/** A particular type of visor driver calls this function to register
/**
* visorbus_register_visor_driver() - registers the provided visor driver
* for handling one or more visor device
* types (channel_types)
* @drv: the driver to register
*
* 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
@ -652,6 +684,7 @@ visordriver_remove_device(struct device *xdev)
* 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,7 +806,13 @@ visorbus_disable_channel_interrupts(struct visor_device *dev)
}
EXPORT_SYMBOL_GPL(visorbus_disable_channel_interrupts);
/** This is how everything starts from the device end.
/**
* 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
@ -745,6 +825,9 @@ EXPORT_SYMBOL_GPL(visorbus_disable_channel_interrupts);
* 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 <info> to the struct
* spar_vbus_channel_protocol.chp_info.
/**
* write_vbus_chp_info() - write the contents of <info> 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
*
* Returns void since this is debug information and not needed for
* Writes chipset 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
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 <info> to the struct
* spar_vbus_channel_protocol.bus_info.
/**
* write_vbus_bus_info() - write the contents of <info> 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
*
* Returns void since this is debug information and not needed for
* Writes bus 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
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 <info> to the
* struct spar_vbus_channel_protocol.dev_info[<devix>].
/**
* write_vbus_dev_info() - write the contents of <info> to the struct
* spar_vbus_channel_protocol.dev_info[<devix>]
* @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,7 +1052,8 @@ 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
/*
* 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);
@ -952,7 +1061,12 @@ fix_vbus_dev_info(struct visor_device *visordev)
&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)
{