staging: hv: Corrected all header comment formats kernel-doc format

Removed kerneldoc /** from functions that should not have them.
Added proper kerneldoc headers to functions that should have them.

This includes fixes as pointed out by Randy Dunlap and Joe Perches.

Cc: Joe Perches <joe@perches.com>
Acked-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Hank Janssen <hjanssen@microsoft.com>
Signed-off-by: Haiyang Zhang <haiyangz@microsoft.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

drivers/staging/hv/Channel.c

@@ -65,8 +65,9 @@ static void DumpMonitorPage(struct hv_monitor_page *MonitorPage)
 }
 #endif
 
-/**
- * VmbusChannelSetEvent - Trigger an event notification on the specified channel.
+/*
+ * VmbusChannelSetEvent - Trigger an event notification on the specified
+ * channel.
  */
 static void VmbusChannelSetEvent(struct vmbus_channel *Channel)
 {
@@ -120,7 +121,7 @@ static void VmbusChannelClearEvent(struct vmbus_channel *channel)
 }
 
 #endif
-/**
+/*
  * VmbusChannelGetDebugInfo -Retrieve various channel debug info
  */
 void VmbusChannelGetDebugInfo(struct vmbus_channel *Channel,
@@ -165,7 +166,7 @@ void VmbusChannelGetDebugInfo(struct vmbus_channel *Channel,
 	RingBufferGetDebugInfo(&Channel->Outbound, &DebugInfo->Outbound);
 }
 
-/**
+/*
  * VmbusChannelOpen - Open the specified channel.
  */
 int VmbusChannelOpen(struct vmbus_channel *NewChannel, u32 SendRingBufferSize,
@@ -283,8 +284,9 @@ int VmbusChannelOpen(struct vmbus_channel *NewChannel, u32 SendRingBufferSize,
 	return 0;
 }
 
-/**
- * DumpGpadlBody - Dump the gpadl body message to the console for debugging purposes.
+/*
+ * DumpGpadlBody - Dump the gpadl body message to the console for
+ * debugging purposes.
  */
 static void DumpGpadlBody(struct vmbus_channel_gpadl_body *Gpadl, u32 Len)
 {
@@ -300,8 +302,9 @@ static void DumpGpadlBody(struct vmbus_channel_gpadl_body *Gpadl, u32 Len)
 			   i, Gpadl->Pfn[i]);
 }
 
-/**
- * DumpGpadlHeader - Dump the gpadl header message to the console for debugging purposes.
+/*
+ * DumpGpadlHeader - Dump the gpadl header message to the console for
+ * debugging purposes.
  */
 static void DumpGpadlHeader(struct vmbus_channel_gpadl_header *Gpadl)
 {
@@ -325,7 +328,7 @@ static void DumpGpadlHeader(struct vmbus_channel_gpadl_header *Gpadl)
 	}
 }
 
-/**
+/*
  * VmbusChannelCreateGpadlHeader - Creates a gpadl for the specified buffer
  */
 static int VmbusChannelCreateGpadlHeader(void *Kbuffer, u32 Size,
@@ -441,7 +444,7 @@ static int VmbusChannelCreateGpadlHeader(void *Kbuffer, u32 Size,
 	return 0;
 }
 
-/**
+/*
  * VmbusChannelEstablishGpadl - Estabish a GPADL for the specified buffer
  *
  * @Channel: a channel
@@ -545,7 +548,7 @@ int VmbusChannelEstablishGpadl(struct vmbus_channel *Channel, void *Kbuffer,
 	return ret;
 }
 
-/**
+/*
  * VmbusChannelTeardownGpadl -Teardown the specified GPADL handle
  */
 int VmbusChannelTeardownGpadl(struct vmbus_channel *Channel, u32 GpadlHandle)
@@ -598,7 +601,7 @@ int VmbusChannelTeardownGpadl(struct vmbus_channel *Channel, u32 GpadlHandle)
 	return ret;
 }
 
-/**
+/*
  * VmbusChannelClose - Close the specified channel
  */
 void VmbusChannelClose(struct vmbus_channel *Channel)
@@ -663,7 +666,7 @@ void VmbusChannelClose(struct vmbus_channel *Channel)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelSendPacket - Send the specified buffer on the given channel
  */
 int VmbusChannelSendPacket(struct vmbus_channel *Channel, const void *Buffer,
@@ -709,8 +712,9 @@ int VmbusChannelSendPacket(struct vmbus_channel *Channel, const void *Buffer,
 	return ret;
 }
 
-/**
- * VmbusChannelSendPacketPageBuffer - Send a range of single-page buffer packets using a GPADL Direct packet type.
+/*
+ * VmbusChannelSendPacketPageBuffer - Send a range of single-page buffer
+ * packets using a GPADL Direct packet type.
  */
 int VmbusChannelSendPacketPageBuffer(struct vmbus_channel *Channel,
 				     struct hv_page_buffer PageBuffers[],
@@ -774,8 +778,9 @@ int VmbusChannelSendPacketPageBuffer(struct vmbus_channel *Channel,
 	return ret;
 }
 
-/**
- * VmbusChannelSendPacketMultiPageBuffer - Send a multi-page buffer packet using a GPADL Direct packet type.
+/*
+ * VmbusChannelSendPacketMultiPageBuffer - Send a multi-page buffer packet
+ * using a GPADL Direct packet type.
  */
 int VmbusChannelSendPacketMultiPageBuffer(struct vmbus_channel *Channel,
 				struct hv_multipage_buffer *MultiPageBuffer,
@@ -843,7 +848,7 @@ int VmbusChannelSendPacketMultiPageBuffer(struct vmbus_channel *Channel,
 	return ret;
 }
 
-/**
+/*
  * VmbusChannelRecvPacket - Retrieve the user packet on the specified channel
  */
 /* TODO: Do we ever receive a gpa direct packet other than the ones we send ? */
@@ -909,7 +914,7 @@ int VmbusChannelRecvPacket(struct vmbus_channel *Channel, void *Buffer,
 	return 0;
 }
 
-/**
+/*
  * VmbusChannelRecvPacketRaw - Retrieve the raw packet on the specified channel
  */
 int VmbusChannelRecvPacketRaw(struct vmbus_channel *Channel, void *Buffer,
@@ -972,7 +977,7 @@ int VmbusChannelRecvPacketRaw(struct vmbus_channel *Channel, void *Buffer,
 	return 0;
 }
 
-/**
+/*
  * VmbusChannelOnChannelEvent - Channel event callback
  */
 void VmbusChannelOnChannelEvent(struct vmbus_channel *Channel)
@@ -985,7 +990,7 @@ void VmbusChannelOnChannelEvent(struct vmbus_channel *Channel)
 	mod_timer(&Channel->poll_timer, jiffies + usecs_to_jiffies(100));
 }
 
-/**
+/*
  * VmbusChannelOnTimer - Timer event callback
  */
 void VmbusChannelOnTimer(unsigned long data)
@@ -996,7 +1001,7 @@ void VmbusChannelOnTimer(unsigned long data)
 		channel->OnChannelCallback(channel->ChannelCallbackContext);
 }
 
-/**
+/*
  * DumpVmbusChannel - Dump vmbus channel info to the console
  */
 static void DumpVmbusChannel(struct vmbus_channel *Channel)

drivers/staging/hv/ChannelMgmt.c

@@ -71,7 +71,7 @@ static const struct hv_guid
 	},
 };
 
-/**
+/*
  * AllocVmbusChannel - Allocate and initialize a vmbus channel object
  */
 struct vmbus_channel *AllocVmbusChannel(void)
@@ -97,7 +97,7 @@ struct vmbus_channel *AllocVmbusChannel(void)
 	return channel;
 }
 
-/**
+/*
  * ReleaseVmbusChannel - Release the vmbus channel object itself
  */
 static inline void ReleaseVmbusChannel(void *context)
@@ -115,7 +115,7 @@ static inline void ReleaseVmbusChannel(void *context)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * FreeVmbusChannel - Release the resources used by the vmbus channel object
  */
 void FreeVmbusChannel(struct vmbus_channel *Channel)
@@ -131,7 +131,7 @@ void FreeVmbusChannel(struct vmbus_channel *Channel)
 			      Channel);
 }
 
-/**
+/*
  * VmbusChannelProcessOffer - Process the offer by creating a channel/device associated with this offer
  */
 static void VmbusChannelProcessOffer(void *context)
@@ -213,7 +213,7 @@ static void VmbusChannelProcessOffer(void *context)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelProcessRescindOffer - Rescind the offer by initiating a device removal
  */
 static void VmbusChannelProcessRescindOffer(void *context)
@@ -225,7 +225,7 @@ static void VmbusChannelProcessRescindOffer(void *context)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelOnOffer - Handler for channel offers from vmbus in parent partition.
  *
  * We ignore all offers except network and storage offers. For each network and
@@ -308,7 +308,7 @@ static void VmbusChannelOnOffer(struct vmbus_channel_message_header *hdr)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelOnOfferRescind - Rescind offer handler.
  *
  * We queue a work item to process this offer synchronously
@@ -335,7 +335,7 @@ static void VmbusChannelOnOfferRescind(struct vmbus_channel_message_header *hdr)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelOnOffersDelivered - This is invoked when all offers have been delivered.
  *
  * Nothing to do here.
@@ -347,7 +347,7 @@ static void VmbusChannelOnOffersDelivered(
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelOnOpenResult - Open result handler.
  *
  * This is invoked when we received a response to our channel open request.
@@ -395,7 +395,7 @@ static void VmbusChannelOnOpenResult(struct vmbus_channel_message_header *hdr)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelOnGpadlCreated - GPADL created handler.
  *
  * This is invoked when we received a response to our gpadl create request.
@@ -447,7 +447,7 @@ static void VmbusChannelOnGpadlCreated(struct vmbus_channel_message_header *hdr)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelOnGpadlTorndown - GPADL torndown handler.
  *
  * This is invoked when we received a response to our gpadl teardown request.
@@ -495,7 +495,7 @@ static void VmbusChannelOnGpadlTorndown(
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelOnVersionResponse - Version response handler
  *
  * This is invoked when we received a response to our initiate contact request.
@@ -558,7 +558,7 @@ static struct vmbus_channel_message_table_entry
 	{ChannelMessageUnload,			NULL},
 };
 
-/**
+/*
  * VmbusOnChannelMessage - Handler for channel protocol messages.
  *
  * This is invoked in the vmbus worker thread context.
@@ -597,7 +597,7 @@ void VmbusOnChannelMessage(void *Context)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusChannelRequestOffers - Send a request to get all our pending offers.
  */
 int VmbusChannelRequestOffers(void)
@@ -651,8 +651,9 @@ int VmbusChannelRequestOffers(void)
 	return ret;
 }
 
-/**
- * VmbusChannelReleaseUnattachedChannels - Release channels that are unattached/unconnected ie (no drivers associated)
+/*
+ * VmbusChannelReleaseUnattachedChannels - Release channels that are
+ * unattached/unconnected ie (no drivers associated)
  */
 void VmbusChannelReleaseUnattachedChannels(void)
 {

drivers/staging/hv/Connection.c

@@ -34,7 +34,7 @@ struct VMBUS_CONNECTION gVmbusConnection = {
 	.NextGpadlHandle	= ATOMIC_INIT(0xE1E10),
 };
 
-/**
+/*
  * VmbusConnect - Sends a connect request on the partition service connection
  */
 int VmbusConnect(void)
@@ -180,7 +180,7 @@ int VmbusConnect(void)
 	return ret;
 }
 
-/**
+/*
  * VmbusDisconnect - Sends a disconnect request on the partition service connection
  */
 int VmbusDisconnect(void)
@@ -218,7 +218,7 @@ int VmbusDisconnect(void)
 	return ret;
 }
 
-/**
+/*
  * GetChannelFromRelId - Get the channel object given its child relative id (ie channel id)
  */
 struct vmbus_channel *GetChannelFromRelId(u32 relId)
@@ -239,7 +239,7 @@ struct vmbus_channel *GetChannelFromRelId(u32 relId)
 	return foundChannel;
 }
 
-/**
+/*
  * VmbusProcessChannelEvent - Process a channel event notification
  */
 static void VmbusProcessChannelEvent(void *context)
@@ -267,7 +267,7 @@ static void VmbusProcessChannelEvent(void *context)
 	}
 }
 
-/**
+/*
  * VmbusOnEvents - Handler for events
  */
 void VmbusOnEvents(void)
@@ -308,7 +308,7 @@ void VmbusOnEvents(void)
 	return;
 }
 
-/**
+/*
  * VmbusPostMessage - Send a msg on the vmbus's message connection
  */
 int VmbusPostMessage(void *buffer, size_t bufferLen)
@@ -320,7 +320,7 @@ int VmbusPostMessage(void *buffer, size_t bufferLen)
 	return HvPostMessage(connId, 1, buffer, bufferLen);
 }
 
-/**
+/*
  * VmbusSetEvent - Send an event notification to the parent
  */
 int VmbusSetEvent(u32 childRelId)

drivers/staging/hv/Hv.c

@@ -35,7 +35,7 @@ struct hv_context gHvContext = {
 	.SignalEventBuffer	= NULL,
 };
 
-/**
+/*
  * HvQueryHypervisorPresence - Query the cpuid for presense of windows hypervisor
  */
 static int HvQueryHypervisorPresence(void)
@@ -56,7 +56,7 @@ static int HvQueryHypervisorPresence(void)
 	return ecx & HV_PRESENT_BIT;
 }
 
-/**
+/*
  * HvQueryHypervisorInfo - Get version info of the windows hypervisor
  */
 static int HvQueryHypervisorInfo(void)
@@ -125,7 +125,7 @@ static int HvQueryHypervisorInfo(void)
 	return maxLeaf;
 }
 
-/**
+/*
  * HvDoHypercall - Invoke the specified hypercall
  */
 static u64 HvDoHypercall(u64 Control, void *Input, void *Output)
@@ -180,7 +180,7 @@ static u64 HvDoHypercall(u64 Control, void *Input, void *Output)
 #endif /* !x86_64 */
 }
 
-/**
+/*
  * HvInit - Main initialization routine.
  *
  * This routine must be called before any other routines in here are called
@@ -294,7 +294,7 @@ int HvInit(void)
 	return ret;
 }
 
-/**
+/*
  * HvCleanup - Cleanup routine.
  *
  * This routine is called normally during driver unloading or exiting.
@@ -321,7 +321,7 @@ void HvCleanup(void)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * HvPostMessage - Post a message using the hypervisor message IPC.
  *
  * This involves a hypercall.
@@ -362,7 +362,7 @@ u16 HvPostMessage(union hv_connection_id connectionId,
 }
 
 
-/**
+/*
  * HvSignalEvent - Signal an event on the specified connection using the hypervisor event IPC.
  *
  * This involves a hypercall.
@@ -376,7 +376,7 @@ u16 HvSignalEvent(void)
 	return status;
 }
 
-/**
+/*
  * HvSynicInit - Initialize the Synthethic Interrupt Controller.
  *
  * If it is already initialized by another entity (ie x2v shim), we need to
@@ -482,7 +482,7 @@ void HvSynicInit(void *irqarg)
 	return;
 }
 
-/**
+/*
  * HvSynicCleanup - Cleanup routine for HvSynicInit().
  */
 void HvSynicCleanup(void *arg)

drivers/staging/hv/NetVsc.c

@@ -167,7 +167,7 @@ static struct netvsc_device *ReleaseInboundNetDevice(struct hv_device *Device)
 	return netDevice;
 }
 
-/**
+/*
  * NetVscInitialize - Main entry point
  */
 int NetVscInitialize(struct hv_driver *drv)
@@ -705,7 +705,7 @@ static void NetVscDisconnectFromVsp(struct netvsc_device *NetDevice)
 	DPRINT_EXIT(NETVSC);
 }
 
-/**
+/*
  * NetVscOnDeviceAdd - Callback when the device belonging to this driver is added
  */
 static int NetVscOnDeviceAdd(struct hv_device *Device, void *AdditionalInfo)
@@ -807,7 +807,7 @@ static int NetVscOnDeviceAdd(struct hv_device *Device, void *AdditionalInfo)
 	return ret;
 }
 
-/**
+/*
  * NetVscOnDeviceRemove - Callback when the root bus device is removed
  */
 static int NetVscOnDeviceRemove(struct hv_device *Device)
@@ -864,7 +864,7 @@ static int NetVscOnDeviceRemove(struct hv_device *Device)
 	return 0;
 }
 
-/**
+/*
  * NetVscOnCleanup - Perform any cleanup when the driver is removed
  */
 static void NetVscOnCleanup(struct hv_driver *drv)

drivers/staging/hv/StorVsc.c

@@ -533,7 +533,7 @@ static int StorVscConnectToVsp(struct hv_device *Device)
 	return ret;
 }
 
-/**
+/*
  * StorVscOnDeviceAdd - Callback when the device belonging to this driver is added
  */
 static int StorVscOnDeviceAdd(struct hv_device *Device, void *AdditionalInfo)
@@ -585,7 +585,7 @@ static int StorVscOnDeviceAdd(struct hv_device *Device, void *AdditionalInfo)
 	return ret;
 }
 
-/**
+/*
  * StorVscOnDeviceRemove - Callback when the our device is being removed
  */
 static int StorVscOnDeviceRemove(struct hv_device *Device)
@@ -683,7 +683,7 @@ int StorVscOnHostReset(struct hv_device *Device)
 	return ret;
 }
 
-/**
+/*
  * StorVscOnIORequest - Callback to initiate an I/O request
  */
 static int StorVscOnIORequest(struct hv_device *Device,
@@ -783,7 +783,7 @@ static int StorVscOnIORequest(struct hv_device *Device,
 	return ret;
 }
 
-/**
+/*
  * StorVscOnCleanup - Perform any cleanup when the driver is removed
  */
 static void StorVscOnCleanup(struct hv_driver *Driver)
@@ -792,7 +792,7 @@ static void StorVscOnCleanup(struct hv_driver *Driver)
 	DPRINT_EXIT(STORVSC);
 }
 
-/**
+/*
  * StorVscInitialize - Main entry point
  */
 int StorVscInitialize(struct hv_driver *Driver)

drivers/staging/hv/TODO

 TODO:
 	- fix remaining checkpatch warnings and errors
-	- use of /** when it is not a kerneldoc header
 	- audit the vmbus to verify it is working properly with the
 	  driver model
 	- convert vmbus driver interface function pointer tables

drivers/staging/hv/Vmbus.c

@@ -52,7 +52,7 @@ static const struct hv_guid gVmbusDeviceId = {
 static struct hv_driver *gDriver; /* vmbus driver object */
 static struct hv_device *gDevice; /* vmbus root device */
 
-/**
+/*
  * VmbusGetChannelOffers - Retrieve the channel offers from the parent partition
  */
 static void VmbusGetChannelOffers(void)
@@ -62,7 +62,7 @@ static void VmbusGetChannelOffers(void)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusGetChannelInterface - Get the channel interface
  */
 static void VmbusGetChannelInterface(struct vmbus_channel_interface *Interface)
@@ -70,7 +70,7 @@ static void VmbusGetChannelInterface(struct vmbus_channel_interface *Interface)
 	GetChannelInterface(Interface);
 }
 
-/**
+/*
  * VmbusGetChannelInfo - Get the device info for the specified device object
  */
 static void VmbusGetChannelInfo(struct hv_device *DeviceObject,
@@ -79,7 +79,7 @@ static void VmbusGetChannelInfo(struct hv_device *DeviceObject,
 	GetChannelInfo(DeviceObject, DeviceInfo);
 }
 
-/**
+/*
  * VmbusCreateChildDevice - Creates the child device on the bus that represents the channel offer
  */
 struct hv_device *VmbusChildDeviceCreate(struct hv_guid *DeviceType,
@@ -92,7 +92,7 @@ struct hv_device *VmbusChildDeviceCreate(struct hv_guid *DeviceType,
 						Context);
 }
 
-/**
+/*
  * VmbusChildDeviceAdd - Registers the child device with the vmbus
  */
 int VmbusChildDeviceAdd(struct hv_device *ChildDevice)
@@ -102,7 +102,7 @@ int VmbusChildDeviceAdd(struct hv_device *ChildDevice)
 	return vmbusDriver->OnChildDeviceAdd(gDevice, ChildDevice);
 }
 
-/**
+/*
  * VmbusChildDeviceRemove Unregisters the child device from the vmbus
  */
 void VmbusChildDeviceRemove(struct hv_device *ChildDevice)
@@ -112,7 +112,7 @@ void VmbusChildDeviceRemove(struct hv_device *ChildDevice)
 	vmbusDriver->OnChildDeviceRemove(ChildDevice);
 }
 
-/**
+/*
  * VmbusOnDeviceAdd - Callback when the root bus device is added
  */
 static int VmbusOnDeviceAdd(struct hv_device *dev, void *AdditionalInfo)
@@ -141,7 +141,7 @@ static int VmbusOnDeviceAdd(struct hv_device *dev, void *AdditionalInfo)
 	return ret;
 }
 
-/**
+/*
  * VmbusOnDeviceRemove - Callback when the root bus device is removed
  */
 static int VmbusOnDeviceRemove(struct hv_device *dev)
@@ -157,7 +157,7 @@ static int VmbusOnDeviceRemove(struct hv_device *dev)
 	return ret;
 }
 
-/**
+/*
  * VmbusOnCleanup - Perform any cleanup when the driver is removed
  */
 static void VmbusOnCleanup(struct hv_driver *drv)
@@ -169,7 +169,7 @@ static void VmbusOnCleanup(struct hv_driver *drv)
 	DPRINT_EXIT(VMBUS);
 }
 
-/**
+/*
  * VmbusOnMsgDPC - DPC routine to handle messages from the hypervisior
  */
 static void VmbusOnMsgDPC(struct hv_driver *drv)
@@ -217,7 +217,7 @@ static void VmbusOnMsgDPC(struct hv_driver *drv)
 	}
 }
 
-/**
+/*
  * VmbusOnEventDPC - DPC routine to handle events from the hypervisior
  */
 static void VmbusOnEventDPC(struct hv_driver *drv)
@@ -226,7 +226,7 @@ static void VmbusOnEventDPC(struct hv_driver *drv)
 	VmbusOnEvents();
 }
 
-/**
+/*
  * VmbusOnISR - ISR routine
  */
 static int VmbusOnISR(struct hv_driver *drv)
@@ -264,7 +264,7 @@ static int VmbusOnISR(struct hv_driver *drv)
 	return ret;
 }
 
-/**
+/*
  * VmbusInitialize - Main entry point
  */
 int VmbusInitialize(struct hv_driver *drv)

drivers/staging/hv/VmbusApi.h

@@ -84,6 +84,24 @@ struct hv_device_info {
 	struct hv_dev_port_info Outbound;
 };
 
+/**
+ * struct vmbus_channel_interface - Contains member functions for vmbus channel
+ * @Open:      Open the channel
+ * @Close:     Close the channel
+ * @SendPacket:        Send a packet over the channel
+ * @SendPacketPageBuffer:      Send a single page buffer over the channel
+ * @SendPacketMultiPageBuffer: Send a multiple page buffers
+ * @RecvPacket:        Receive packet
+ * @RecvPacketRaw:     Receive Raw packet
+ * @EstablishGpadl:    Set up GPADL for ringbuffer
+ * @TeardownGpadl:     Teardown GPADL for ringbuffer
+ * @GetInfo:   Get info about the channel
+ *
+ * This structure contains function pointer to control vmbus channel
+ * behavior. None of these functions is externally callable, but they
+ * are used for normal vmbus channel internal behavior.
+ * Only used by Hyper-V drivers.
+ */
 struct vmbus_channel_interface {
 	int (*Open)(struct hv_device *Device, u32 SendBufferSize,
 		    u32 RecvRingBufferSize, void *UserData, u32 UserDataLen,

drivers/staging/hv/blkvsc_drv.c

@@ -165,7 +165,7 @@ static struct block_device_operations block_ops = {
 	.ioctl  = blkvsc_ioctl,
 };
 
-/**
+/*
  * blkvsc_drv_init -  BlkVsc driver initialization.
  */
 static int blkvsc_drv_init(int (*drv_init)(struct hv_driver *drv))
@@ -245,7 +245,7 @@ static void blkvsc_drv_exit(void)
 	return;
 }
 
-/**
+/*
  * blkvsc_probe - Add a new device for this driver
  */
 static int blkvsc_probe(struct device *device)
@@ -733,7 +733,7 @@ static int blkvsc_do_read_capacity16(struct block_device_context *blkdev)
 	return 0;
 }
 
-/**
+/*
  * blkvsc_remove() - Callback when our device is removed
  */
 static int blkvsc_remove(struct device *device)

drivers/staging/hv/netvsc_drv.c

@@ -266,7 +266,7 @@ static int netvsc_start_xmit(struct sk_buff *skb, struct net_device *net)
 	return ret;
 }
 
-/**
+/*
  * netvsc_linkstatus_callback - Link up/down notification
  */
 static void netvsc_linkstatus_callback(struct hv_device *device_obj,
@@ -293,8 +293,9 @@ static void netvsc_linkstatus_callback(struct hv_device *device_obj,
 	DPRINT_EXIT(NETVSC_DRV);
 }
 
-/**
- * netvsc_recv_callback -  Callback when we receive a packet from the "wire" on the specified device.
+/*
+ * netvsc_recv_callback -  Callback when we receive a packet from the
+ * "wire" on the specified device.
  */
 static int netvsc_recv_callback(struct hv_device *device_obj,
 				struct hv_netvsc_packet *packet)

drivers/staging/hv/osd.c

@@ -59,6 +59,15 @@ void *osd_VirtualAllocExec(unsigned int size)
 #endif
 }
 
+/**
+ * osd_PageAlloc() - Allocate pages
+ * @count:      Total number of Kernel pages you want to allocate
+ *
+ * Tries to allocate @count number of consecutive free kernel pages.
+ * And if successful, it will set the pages to 0 before returning.
+ * If successfull it will return pointer to the @count pages.
+ * Mainly used by Hyper-V drivers.
+ */
 void *osd_PageAlloc(unsigned int count)
 {
 	void *p;
@@ -78,6 +87,14 @@ void *osd_PageAlloc(unsigned int count)
 }
 EXPORT_SYMBOL_GPL(osd_PageAlloc);
 
+/**
+ * osd_PageFree() - Free pages
+ * @page:       Pointer to the first page to be freed
+ * @count:      Total number of Kernel pages you free
+ *
+ * Frees the pages allocated by osd_PageAlloc()
+ * Mainly used by Hyper-V drivers.
+ */
 void osd_PageFree(void *page, unsigned int count)
 {
 	free_pages((unsigned long)page, get_order(count * PAGE_SIZE));
@@ -86,6 +103,17 @@ void osd_PageFree(void *page, unsigned int count)
 }
 EXPORT_SYMBOL_GPL(osd_PageFree);
 
+/**
+ * osd_WaitEventCreate() - Create the event queue
+ *
+ * Allocates memory for a &struct osd_waitevent. And then calls
+ * init_waitqueue_head to set up the wait queue for the event.
+ * This structure is usually part of a another structure that contains
+ * the actual Hyper-V device driver structure.
+ *
+ * Returns pointer to &struct osd_waitevent
+ * Mainly used by Hyper-V drivers.
+ */
 struct osd_waitevent *osd_WaitEventCreate(void)
 {
 	struct osd_waitevent *wait = kmalloc(sizeof(struct osd_waitevent),
@@ -99,6 +127,19 @@ struct osd_waitevent *osd_WaitEventCreate(void)
 }
 EXPORT_SYMBOL_GPL(osd_WaitEventCreate);
 
+
+/**
+ * osd_WaitEventSet() - Wake up the process
+ * @waitEvent: Structure to event to be woken up
+ *
+ * @waitevent is of type &struct osd_waitevent
+ *
+ * Wake up the sleeping process so it can do some work.
+ * And set condition indicator in &struct osd_waitevent to indicate
+ * the process is in a woken state.
+ *
+ * Only used by Network and Storage Hyper-V drivers.
+ */
 void osd_WaitEventSet(struct osd_waitevent *waitEvent)
 {
 	waitEvent->condition = 1;
@@ -106,6 +147,20 @@ void osd_WaitEventSet(struct osd_waitevent *waitEvent)
 }
 EXPORT_SYMBOL_GPL(osd_WaitEventSet);
 
+/**
+ * osd_WaitEventWait() - Wait for event till condition is true
+ * @waitEvent: Structure to event to be put to sleep
+ *
+ * @waitevent is of type &struct osd_waitevent
+ *
+ * Set up the process to sleep until waitEvent->condition get true.
+ * And set condition indicator in &struct osd_waitevent to indicate
+ * the process is in a sleeping state.
+ *
+ * Returns the status of 'wait_event_interruptible()' system call
+ *
+ * Mainly used by Hyper-V drivers.
+ */
 int osd_WaitEventWait(struct osd_waitevent *waitEvent)
 {
 	int ret = 0;
@@ -117,6 +172,21 @@ int osd_WaitEventWait(struct osd_waitevent *waitEvent)
 }
 EXPORT_SYMBOL_GPL(osd_WaitEventWait);
 
+/**
+ * osd_WaitEventWaitEx() - Wait for event or timeout for process wakeup
+ * @waitEvent: Structure to event to be put to sleep
+ * @TimeoutInMs:       Total number of Milliseconds to wait before waking up
+ *
+ * @waitevent is of type &struct osd_waitevent
+ * Set up the process to sleep until @waitEvent->condition get true or
+ * @TimeoutInMs (Time out in Milliseconds) has been reached.
+ * And set condition indicator in &struct osd_waitevent to indicate
+ * the process is in a sleeping state.
+ *
+ * Returns the status of 'wait_event_interruptible_timeout()' system call
+ *
+ * Mainly used by Hyper-V drivers.
+ */
 int osd_WaitEventWaitEx(struct osd_waitevent *waitEvent, u32 TimeoutInMs)
 {
 	int ret = 0;

drivers/staging/hv/storvsc_drv.c

@@ -130,7 +130,7 @@ static struct scsi_host_template scsi_driver = {
 };
 
 
-/**
+/*
  * storvsc_drv_init - StorVsc driver initialization.
  */
 static int storvsc_drv_init(int (*drv_init)(struct hv_driver *drv))
@@ -223,7 +223,7 @@ static void storvsc_drv_exit(void)
 	return;
 }
 
-/**
+/*
  * storvsc_probe - Add a new device for this driver
  */
 static int storvsc_probe(struct device *device)
@@ -319,7 +319,7 @@ static int storvsc_probe(struct device *device)
 	return ret;
 }
 
-/**
+/*
  * storvsc_remove - Callback when our device is removed
  */
 static int storvsc_remove(struct device *device)
@@ -372,7 +372,7 @@ static int storvsc_remove(struct device *device)
 	return ret;
 }
 
-/**
+/*
  * storvsc_commmand_completion - Command completion processing
  */
 static void storvsc_commmand_completion(struct hv_storvsc_request *request)
@@ -623,7 +623,7 @@ static unsigned int copy_from_bounce_buffer(struct scatterlist *orig_sgl,
 	return total_copied;
 }
 
-/**
+/*
  * storvsc_queuecommand - Initiate command processing
  */
 static int storvsc_queuecommand(struct scsi_cmnd *scmnd,
@@ -824,7 +824,7 @@ static int storvsc_merge_bvec(struct request_queue *q,
 	return bvec->bv_len;
 }
 
-/**
+/*
  * storvsc_device_configure - Configure the specified scsi device
  */
 static int storvsc_device_alloc(struct scsi_device *sdevice)
@@ -863,7 +863,7 @@ static int storvsc_device_configure(struct scsi_device *sdevice)
 	return 0;
 }
 
-/**
+/*
  * storvsc_host_reset_handler - Reset the scsi HBA
  */
 static int storvsc_host_reset_handler(struct scsi_cmnd *scmnd)

drivers/staging/hv/vmbus_drv.c

@@ -129,7 +129,7 @@ static struct vmbus_driver_context g_vmbus_drv = {
 	.bus.dev_attrs =	vmbus_device_attrs,
 };
 
-/**
+/*
  * vmbus_show_device_attr - Show the device attribute in sysfs.
  *
  * This is invoked when user does a
@@ -233,7 +233,7 @@ static ssize_t vmbus_show_device_attr(struct device *dev,
 	}
 }
 
-/**
+/*
  * vmbus_bus_init -Main vmbus driver initialization routine.
  *
  * Here, we
@@ -362,7 +362,7 @@ static int vmbus_bus_init(int (*drv_init)(struct hv_driver *drv))
 	return ret;
 }
 
-/**
+/*
  * vmbus_bus_exit - Terminate the vmbus driver.
  *
  * This routine is opposite of vmbus_bus_init()
@@ -398,8 +398,18 @@ static void vmbus_bus_exit(void)
 	return;
 }
 
+
 /**
- * vmbus_child_driver_register - Register a vmbus's child driver
+ * vmbus_child_driver_register() - Register a vmbus's child driver
+ * @driver_ctx:        Pointer to driver structure you want to register
+ *
+ * @driver_ctx is of type &struct driver_context
+ *
+ * Registers the given driver with Linux through the 'driver_register()' call
+ * And sets up the hyper-v vmbus handling for this driver.
+ * It will return the state of the 'driver_register()' call.
+ *
+ * Mainly used by Hyper-V drivers.
  */
 int vmbus_child_driver_register(struct driver_context *driver_ctx)
 {
@@ -425,7 +435,15 @@ int vmbus_child_driver_register(struct driver_context *driver_ctx)
 EXPORT_SYMBOL(vmbus_child_driver_register);
 
 /**
- * vmbus_child_driver_unregister Unregister a vmbus's child driver
+ * vmbus_child_driver_unregister() - Unregister a vmbus's child driver
+ * @driver_ctx:        Pointer to driver structure you want to un-register
+ *
+ * @driver_ctx is of type &struct driver_context
+ *
+ * Un-register the given driver with Linux through the 'driver_unregister()'
+ * call. And ungegisters the driver from the Hyper-V vmbus handler.
+ *
+ * Mainly used by Hyper-V drivers.
  */
 void vmbus_child_driver_unregister(struct driver_context *driver_ctx)
 {
@@ -443,9 +461,15 @@ void vmbus_child_driver_unregister(struct driver_context *driver_ctx)
 EXPORT_SYMBOL(vmbus_child_driver_unregister);
 
 /**
- * vmbus_get_interface - Get the vmbus channel interface.
+ * vmbus_get_interface() - Get the vmbus channel interface.
+ * @interface: Pointer to channel interface structure
+ *
+ * Get the Hyper-V channel used for the driver.
+ *
+ * @interface is of type &struct vmbus_channel_interface
+ * This is invoked by child/client driver that sits above vmbus.
  *
- * This is invoked by child/client driver that sits above vmbus
+ * Mainly used by Hyper-V drivers.
  */
 void vmbus_get_interface(struct vmbus_channel_interface *interface)
 {
@@ -455,7 +479,7 @@ void vmbus_get_interface(struct vmbus_channel_interface *interface)
 }
 EXPORT_SYMBOL(vmbus_get_interface);
 
-/**
+/*
  * vmbus_child_device_get_info - Get the vmbus child device info.
  *
  * This is invoked to display various device attributes in sysfs.
@@ -468,8 +492,9 @@ static void vmbus_child_device_get_info(struct hv_device *device_obj,
 	vmbus_drv_obj->GetChannelInfo(device_obj, device_info);
 }
 
-/**
- * vmbus_child_device_create - Creates and registers a new child device on the vmbus.
+/*
+ * vmbus_child_device_create - Creates and registers a new child device
+ * on the vmbus.
  */
 static struct hv_device *vmbus_child_device_create(struct hv_guid *type,
 						   struct hv_guid *instance,
@@ -523,7 +548,7 @@ static struct hv_device *vmbus_child_device_create(struct hv_guid *type,
 	return child_device_obj;
 }
 
-/**
+/*
  * vmbus_child_device_register - Register the child device on the specified bus
  */
 static int vmbus_child_device_register(struct hv_device *root_device_obj,
@@ -571,8 +596,9 @@ static int vmbus_child_device_register(struct hv_device *root_device_obj,
 	return ret;
 }
 
-/**
- * vmbus_child_device_unregister - Remove the specified child device from the vmbus.
+/*
+ * vmbus_child_device_unregister - Remove the specified child device
+ * from the vmbus.
  */
 static void vmbus_child_device_unregister(struct hv_device *device_obj)
 {
@@ -595,7 +621,7 @@ static void vmbus_child_device_unregister(struct hv_device *device_obj)
 	DPRINT_EXIT(VMBUS_DRV);
 }
 
-/**
+/*
  * vmbus_child_device_destroy - Destroy the specified child device on the vmbus.
  */
 static void vmbus_child_device_destroy(struct hv_device *device_obj)
@@ -605,7 +631,7 @@ static void vmbus_child_device_destroy(struct hv_device *device_obj)
 	DPRINT_EXIT(VMBUS_DRV);
 }
 
-/**
+/*
  * vmbus_uevent - add uevent for our device
  *
  * This routine is invoked when a device is added or removed on the vmbus to
@@ -684,7 +710,7 @@ static int vmbus_uevent(struct device *device, struct kobj_uevent_env *env)
 	return 0;
 }
 
-/**
+/*
  * vmbus_match - Attempt to match the specified device to the specified driver
  */
 static int vmbus_match(struct device *device, struct device_driver *driver)
@@ -719,7 +745,7 @@ static int vmbus_match(struct device *device, struct device_driver *driver)
 	return match;
 }
 
-/**
+/*
  * vmbus_probe_failed_cb - Callback when a driver probe failed in vmbus_probe()
  *
  * We need a callback because we cannot invoked device_unregister() inside
@@ -742,7 +768,7 @@ static void vmbus_probe_failed_cb(struct work_struct *context)
 	DPRINT_EXIT(VMBUS_DRV);
 }
 
-/**
+/*
  * vmbus_probe - Add the new vmbus's child device
  */
 static int vmbus_probe(struct device *child_device)
@@ -778,7 +804,7 @@ static int vmbus_probe(struct device *child_device)
 	return ret;
 }
 
-/**
+/*
  * vmbus_remove - Remove a vmbus device
  */
 static int vmbus_remove(struct device *child_device)
@@ -820,7 +846,7 @@ static int vmbus_remove(struct device *child_device)
 	return 0;
 }
 
-/**
+/*
  * vmbus_shutdown - Shutdown a vmbus device
  */
 static void vmbus_shutdown(struct device *child_device)
@@ -856,7 +882,7 @@ static void vmbus_shutdown(struct device *child_device)
 	return;
 }
 
-/**
+/*
  * vmbus_bus_release - Final callback release of the vmbus root device
  */
 static void vmbus_bus_release(struct device *device)
@@ -870,7 +896,7 @@ static void vmbus_bus_release(struct device *device)
 	DPRINT_EXIT(VMBUS_DRV);
 }
 
-/**
+/*
  * vmbus_device_release - Final callback release of the vmbus child device
  */
 static void vmbus_device_release(struct device *device)
@@ -888,7 +914,7 @@ static void vmbus_device_release(struct device *device)
 	return;
 }
 
-/**
+/*
  * vmbus_msg_dpc - Tasklet routine to handle hypervisor messages
  */
 static void vmbus_msg_dpc(unsigned long data)
@@ -905,7 +931,7 @@ static void vmbus_msg_dpc(unsigned long data)
 	DPRINT_EXIT(VMBUS_DRV);
 }
 
-/**
+/*
  * vmbus_msg_dpc - Tasklet routine to handle hypervisor events
  */
 static void vmbus_event_dpc(unsigned long data)