Commit 34f42a07 authored by Robert Love's avatar Robert Love Committed by James Bottomley
Browse files

[SCSI] libfc, fcoe: Fix kerneldoc comments



1) Added '()' for function names in kerneldoc comments

2) Changed comment bookends from '**/' to '*/'. The comment on the the
   mailing list was that '**/' "is consistently unconventional.  Not
   wrong, just odd." The Documentation/kernel-doc-nano-HOWTO.txt
   states that kerneldoc comment blocks should end with '**/' but most
   (if not all) instance I found under drivers/scsi/ were only using
   the '*/' so I converted to that style.

3) Removed incorrect linebreaks in kerneldoc comments where found

4) Removed a few unnecessary blank comment lines in kerneldoc comment
   blocks
Signed-off-by: default avatarRobert Love <robert.w.love@intel.com>
Signed-off-by: default avatarJames Bottomley <James.Bottomley@HansenPartnership.com>
parent 0ae4d4ae
......@@ -33,19 +33,19 @@ static LIST_HEAD(fcoe_transports);
static DEFINE_MUTEX(fcoe_transports_lock);
/**
* fcoe_transport_default - returns ptr to the default transport fcoe_sw
**/
* fcoe_transport_default() - Returns ptr to the default transport fcoe_sw
*/
struct fcoe_transport *fcoe_transport_default(void)
{
return &fcoe_sw_transport;
}
/**
* fcoe_transport_to_pcidev - get the pci dev from a netdev
* fcoe_transport_to_pcidev() - get the pci dev from a netdev
* @netdev: the netdev that pci dev will be retrived from
*
* Returns: NULL or the corrsponding pci_dev
**/
*/
struct pci_dev *fcoe_transport_pcidev(const struct net_device *netdev)
{
if (!netdev->dev.parent)
......@@ -54,16 +54,14 @@ struct pci_dev *fcoe_transport_pcidev(const struct net_device *netdev)
}
/**
* fcoe_transport_device_lookup - find out netdev is managed by the
* transport
* assign a transport to a device
* fcoe_transport_device_lookup() - Lookup a transport
* @netdev: the netdev the transport to be attached to
*
* This will look for existing offload driver, if not found, it falls back to
* the default sw hba (fcoe_sw) as its fcoe transport.
*
* Returns: 0 for success
**/
*/
static struct fcoe_transport_internal *fcoe_transport_device_lookup(
struct fcoe_transport *t, struct net_device *netdev)
{
......@@ -81,14 +79,14 @@ static struct fcoe_transport_internal *fcoe_transport_device_lookup(
return NULL;
}
/**
* fcoe_transport_device_add - assign a transport to a device
* fcoe_transport_device_add() - Assign a transport to a device
* @netdev: the netdev the transport to be attached to
*
* This will look for existing offload driver, if not found, it falls back to
* the default sw hba (fcoe_sw) as its fcoe transport.
*
* Returns: 0 for success
**/
*/
static int fcoe_transport_device_add(struct fcoe_transport *t,
struct net_device *netdev)
{
......@@ -123,14 +121,14 @@ static int fcoe_transport_device_add(struct fcoe_transport *t,
}
/**
* fcoe_transport_device_remove - remove a device from its transport
* fcoe_transport_device_remove() - Remove a device from its transport
* @netdev: the netdev the transport to be attached to
*
* this removes the device from the transport so the given transport will
* This removes the device from the transport so the given transport will
* not manage this device any more
*
* Returns: 0 for success
**/
*/
static int fcoe_transport_device_remove(struct fcoe_transport *t,
struct net_device *netdev)
{
......@@ -155,13 +153,13 @@ static int fcoe_transport_device_remove(struct fcoe_transport *t,
}
/**
* fcoe_transport_device_remove_all - remove all from transport devlist
* fcoe_transport_device_remove_all() - Remove all from transport devlist
*
* this removes the device from the transport so the given transport will
* This removes the device from the transport so the given transport will
* not manage this device any more
*
* Returns: 0 for success
**/
*/
static void fcoe_transport_device_remove_all(struct fcoe_transport *t)
{
struct fcoe_transport_internal *ti, *tmp;
......@@ -175,16 +173,16 @@ static void fcoe_transport_device_remove_all(struct fcoe_transport *t)
}
/**
* fcoe_transport_match - use the bus device match function to match the hw
* @t: the fcoe transport
* @netdev:
* fcoe_transport_match() - Use the bus device match function to match the hw
* @t: The fcoe transport to check
* @netdev: The netdev to match against
*
* This function is used to check if the givne transport wants to manage the
* This function is used to check if the given transport wants to manage the
* input netdev. if the transports implements the match function, it will be
* called, o.w. we just compare the pci vendor and device id.
*
* Returns: true for match up
**/
*/
static bool fcoe_transport_match(struct fcoe_transport *t,
struct net_device *netdev)
{
......@@ -210,15 +208,15 @@ static bool fcoe_transport_match(struct fcoe_transport *t,
}
/**
* fcoe_transport_lookup - check if the transport is already registered
* fcoe_transport_lookup() - Check if the transport is already registered
* @t: the transport to be looked up
*
* This compares the parent device (pci) vendor and device id
*
* Returns: NULL if not found
*
* TODO - return default sw transport if no other transport is found
**/
* TODO: return default sw transport if no other transport is found
*/
static struct fcoe_transport *fcoe_transport_lookup(
struct net_device *netdev)
{
......@@ -239,11 +237,11 @@ static struct fcoe_transport *fcoe_transport_lookup(
}
/**
* fcoe_transport_register - adds a fcoe transport to the fcoe transports list
* fcoe_transport_register() - Adds a fcoe transport to the fcoe transports list
* @t: ptr to the fcoe transport to be added
*
* Returns: 0 for success
**/
*/
int fcoe_transport_register(struct fcoe_transport *t)
{
struct fcoe_transport *tt;
......@@ -269,11 +267,11 @@ int fcoe_transport_register(struct fcoe_transport *t)
EXPORT_SYMBOL_GPL(fcoe_transport_register);
/**
* fcoe_transport_unregister - remove the tranport fro the fcoe transports list
* fcoe_transport_unregister() - Remove the tranport fro the fcoe transports list
* @t: ptr to the fcoe transport to be removed
*
* Returns: 0 for success
**/
*/
int fcoe_transport_unregister(struct fcoe_transport *t)
{
struct fcoe_transport *tt, *tmp;
......@@ -294,8 +292,8 @@ int fcoe_transport_unregister(struct fcoe_transport *t)
}
EXPORT_SYMBOL_GPL(fcoe_transport_unregister);
/*
* fcoe_load_transport_driver - load an offload driver by alias name
/**
* fcoe_load_transport_driver() - Load an offload driver by alias name
* @netdev: the target net device
*
* Requests for an offload driver module as the fcoe transport, if fails, it
......@@ -307,7 +305,7 @@ EXPORT_SYMBOL_GPL(fcoe_transport_unregister);
* 3. pure hw fcoe hba may not have netdev
*
* Returns: 0 for success
**/
*/
int fcoe_load_transport_driver(struct net_device *netdev)
{
struct pci_dev *pci;
......@@ -335,14 +333,14 @@ int fcoe_load_transport_driver(struct net_device *netdev)
EXPORT_SYMBOL_GPL(fcoe_load_transport_driver);
/**
* fcoe_transport_attach - load transport to fcoe
* fcoe_transport_attach() - Load transport to fcoe
* @netdev: the netdev the transport to be attached to
*
* This will look for existing offload driver, if not found, it falls back to
* the default sw hba (fcoe_sw) as its fcoe transport.
*
* Returns: 0 for success
**/
*/
int fcoe_transport_attach(struct net_device *netdev)
{
struct fcoe_transport *t;
......@@ -373,11 +371,11 @@ int fcoe_transport_attach(struct net_device *netdev)
EXPORT_SYMBOL_GPL(fcoe_transport_attach);
/**
* fcoe_transport_release - unload transport from fcoe
* fcoe_transport_release() - Unload transport from fcoe
* @netdev: the net device on which fcoe is to be released
*
* Returns: 0 for success
**/
*/
int fcoe_transport_release(struct net_device *netdev)
{
struct fcoe_transport *t;
......@@ -410,12 +408,12 @@ int fcoe_transport_release(struct net_device *netdev)
EXPORT_SYMBOL_GPL(fcoe_transport_release);
/**
* fcoe_transport_init - initializes fcoe transport layer
* fcoe_transport_init() - Initializes fcoe transport layer
*
* This prepares for the fcoe transport layer
*
* Returns: none
**/
*/
int __init fcoe_transport_init(void)
{
INIT_LIST_HEAD(&fcoe_transports);
......@@ -424,12 +422,13 @@ int __init fcoe_transport_init(void)
}
/**
* fcoe_transport_exit - cleans up the fcoe transport layer
* fcoe_transport_exit() - Cleans up the fcoe transport layer
*
* This cleans up the fcoe transport layer. removing any transport on the list,
* note that the transport destroy func is not called here.
*
* Returns: none
**/
*/
int __exit fcoe_transport_exit(void)
{
struct fcoe_transport *t, *tmp;
......
......@@ -104,13 +104,12 @@ static struct scsi_host_template fcoe_sw_shost_template = {
.max_sectors = 0xffff,
};
/*
* fcoe_sw_lport_config - sets up the fc_lport
/**
* fcoe_sw_lport_config() - sets up the fc_lport
* @lp: ptr to the fc_lport
* @shost: ptr to the parent scsi host
*
* Returns: 0 for success
*
*/
static int fcoe_sw_lport_config(struct fc_lport *lp)
{
......@@ -137,16 +136,14 @@ static int fcoe_sw_lport_config(struct fc_lport *lp)
return 0;
}
/*
* fcoe_sw_netdev_config - sets up fcoe_softc for lport and network
* related properties
/**
* fcoe_sw_netdev_config() - Set up netdev for SW FCoE
* @lp : ptr to the fc_lport
* @netdev : ptr to the associated netdevice struct
*
* Must be called after fcoe_sw_lport_config() as it will use lport mutex
*
* Returns : 0 for success
*
*/
static int fcoe_sw_netdev_config(struct fc_lport *lp, struct net_device *netdev)
{
......@@ -224,16 +221,15 @@ static int fcoe_sw_netdev_config(struct fc_lport *lp, struct net_device *netdev)
return 0;
}
/*
* fcoe_sw_shost_config - sets up fc_lport->host
/**
* fcoe_sw_shost_config() - Sets up fc_lport->host
* @lp : ptr to the fc_lport
* @shost : ptr to the associated scsi host
* @dev : device associated to scsi host
*
* Must be called after fcoe_sw_lport_config) and fcoe_sw_netdev_config()
* Must be called after fcoe_sw_lport_config() and fcoe_sw_netdev_config()
*
* Returns : 0 for success
*
*/
static int fcoe_sw_shost_config(struct fc_lport *lp, struct Scsi_Host *shost,
struct device *dev)
......@@ -261,8 +257,8 @@ static int fcoe_sw_shost_config(struct fc_lport *lp, struct Scsi_Host *shost,
return 0;
}
/*
* fcoe_sw_em_config - allocates em for this lport
/**
* fcoe_sw_em_config() - allocates em for this lport
* @lp: the port that em is to allocated for
*
* Returns : 0 on success
......@@ -279,8 +275,8 @@ static inline int fcoe_sw_em_config(struct fc_lport *lp)
return 0;
}
/*
* fcoe_sw_destroy - FCoE software HBA tear-down function
/**
* fcoe_sw_destroy() - FCoE software HBA tear-down function
* @netdev: ptr to the associated net_device
*
* Returns: 0 if link is OK for use by FCoE.
......@@ -353,8 +349,8 @@ static struct libfc_function_template fcoe_sw_libfc_fcn_templ = {
.frame_send = fcoe_xmit,
};
/*
* fcoe_sw_create - this function creates the fcoe interface
/**
* fcoe_sw_create() - this function creates the fcoe interface
* @netdev: pointer the associated netdevice
*
* Creates fc_lport struct and scsi_host for lport, configures lport
......@@ -440,8 +436,8 @@ out_host_put:
return rc;
}
/*
* fcoe_sw_match - the fcoe sw transport match function
/**
* fcoe_sw_match() - The FCoE SW transport match function
*
* Returns : false always
*/
......@@ -461,8 +457,8 @@ struct fcoe_transport fcoe_sw_transport = {
.device = 0xffff,
};
/*
* fcoe_sw_init - registers fcoe_sw_transport
/**
* fcoe_sw_init() - Registers fcoe_sw_transport
*
* Returns : 0 on success
*/
......@@ -480,8 +476,8 @@ int __init fcoe_sw_init(void)
return 0;
}
/*
* fcoe_sw_exit - unregisters fcoe_sw_transport
/**
* fcoe_sw_exit() - Unregisters fcoe_sw_transport
*
* Returns : 0 on success
*/
......
......@@ -91,13 +91,13 @@ static struct notifier_block fcoe_cpu_notifier = {
};
/**
* fcoe_create_percpu_data - creates the associated cpu data
* fcoe_create_percpu_data() - creates the associated cpu data
* @cpu: index for the cpu where fcoe cpu data will be created
*
* create percpu stats block, from cpu add notifier
*
* Returns: none
**/
*/
static void fcoe_create_percpu_data(int cpu)
{
struct fc_lport *lp;
......@@ -115,13 +115,13 @@ static void fcoe_create_percpu_data(int cpu)
}
/**
* fcoe_destroy_percpu_data - destroys the associated cpu data
* fcoe_destroy_percpu_data() - destroys the associated cpu data
* @cpu: index for the cpu where fcoe cpu data will destroyed
*
* destroy percpu stats block called by cpu add/remove notifier
*
* Retuns: none
**/
*/
static void fcoe_destroy_percpu_data(int cpu)
{
struct fc_lport *lp;
......@@ -137,7 +137,7 @@ static void fcoe_destroy_percpu_data(int cpu)
}
/**
* fcoe_cpu_callback - fcoe cpu hotplug event callback
* fcoe_cpu_callback() - fcoe cpu hotplug event callback
* @nfb: callback data block
* @action: event triggering the callback
* @hcpu: index for the cpu of this event
......@@ -145,7 +145,7 @@ static void fcoe_destroy_percpu_data(int cpu)
* this creates or destroys per cpu data for fcoe
*
* Returns NOTIFY_OK always.
**/
*/
static int fcoe_cpu_callback(struct notifier_block *nfb, unsigned long action,
void *hcpu)
{
......@@ -166,7 +166,7 @@ static int fcoe_cpu_callback(struct notifier_block *nfb, unsigned long action,
#endif /* CONFIG_HOTPLUG_CPU */
/**
* fcoe_rcv - this is the fcoe receive function called by NET_RX_SOFTIRQ
* fcoe_rcv() - this is the fcoe receive function called by NET_RX_SOFTIRQ
* @skb: the receive skb
* @dev: associated net device
* @ptype: context
......@@ -175,7 +175,7 @@ static int fcoe_cpu_callback(struct notifier_block *nfb, unsigned long action,
* this function will receive the packet and build fc frame and pass it up
*
* Returns: 0 for success
**/
*/
int fcoe_rcv(struct sk_buff *skb, struct net_device *dev,
struct packet_type *ptype, struct net_device *olddev)
{
......@@ -265,11 +265,11 @@ err2:
EXPORT_SYMBOL_GPL(fcoe_rcv);
/**
* fcoe_start_io - pass to netdev to start xmit for fcoe
* fcoe_start_io() - pass to netdev to start xmit for fcoe
* @skb: the skb to be xmitted
*
* Returns: 0 for success
**/
*/
static inline int fcoe_start_io(struct sk_buff *skb)
{
int rc;
......@@ -283,12 +283,12 @@ static inline int fcoe_start_io(struct sk_buff *skb)
}
/**
* fcoe_get_paged_crc_eof - in case we need alloc a page for crc_eof
* fcoe_get_paged_crc_eof() - in case we need alloc a page for crc_eof
* @skb: the skb to be xmitted
* @tlen: total len
*
* Returns: 0 for success
**/
*/
static int fcoe_get_paged_crc_eof(struct sk_buff *skb, int tlen)
{
struct fcoe_percpu_s *fps;
......@@ -326,13 +326,12 @@ static int fcoe_get_paged_crc_eof(struct sk_buff *skb, int tlen)
}
/**
* fcoe_fc_crc - calculates FC CRC in this fcoe skb
* fcoe_fc_crc() - calculates FC CRC in this fcoe skb
* @fp: the fc_frame containg data to be checksummed
*
* This uses crc32() to calculate the crc for fc frame
* Return : 32 bit crc
*
**/
*/
u32 fcoe_fc_crc(struct fc_frame *fp)
{
struct sk_buff *skb = fp_skb(fp);
......@@ -363,13 +362,12 @@ u32 fcoe_fc_crc(struct fc_frame *fp)
EXPORT_SYMBOL_GPL(fcoe_fc_crc);
/**
* fcoe_xmit - FCoE frame transmit function
* fcoe_xmit() - FCoE frame transmit function
* @lp: the associated local port
* @fp: the fc_frame to be transmitted
*
* Return : 0 for success
*
**/
*/
int fcoe_xmit(struct fc_lport *lp, struct fc_frame *fp)
{
int wlen, rc = 0;
......@@ -511,12 +509,11 @@ int fcoe_xmit(struct fc_lport *lp, struct fc_frame *fp)
}
EXPORT_SYMBOL_GPL(fcoe_xmit);
/*
* fcoe_percpu_receive_thread - recv thread per cpu
/**
* fcoe_percpu_receive_thread() - recv thread per cpu
* @arg: ptr to the fcoe per cpu struct
*
* Return: 0 for success
*
*/
int fcoe_percpu_receive_thread(void *arg)
{
......@@ -658,7 +655,7 @@ int fcoe_percpu_receive_thread(void *arg)
}
/**
* fcoe_recv_flogi - flogi receive function
* fcoe_recv_flogi() - flogi receive function
* @fc: associated fcoe_softc
* @fp: the recieved frame
* @sa: the source address of this flogi
......@@ -667,7 +664,7 @@ int fcoe_percpu_receive_thread(void *arg)
* mac address for the initiator, eitehr OUI based or GW based.
*
* Returns: none
**/
*/
static void fcoe_recv_flogi(struct fcoe_softc *fc, struct fc_frame *fp, u8 *sa)
{
struct fc_frame_header *fh;
......@@ -715,7 +712,7 @@ static void fcoe_recv_flogi(struct fcoe_softc *fc, struct fc_frame *fp, u8 *sa)
}
/**
* fcoe_watchdog - fcoe timer callback
* fcoe_watchdog() - fcoe timer callback
* @vp:
*
* This checks the pending queue length for fcoe and set lport qfull
......@@ -723,7 +720,7 @@ static void fcoe_recv_flogi(struct fcoe_softc *fc, struct fc_frame *fp, u8 *sa)
* fcoe_hostlist.
*
* Returns: 0 for success
**/
*/
void fcoe_watchdog(ulong vp)
{
struct fc_lport *lp;
......@@ -750,7 +747,7 @@ void fcoe_watchdog(ulong vp)
/**
* fcoe_check_wait_queue - put the skb into fcoe pending xmit queue
* fcoe_check_wait_queue() - put the skb into fcoe pending xmit queue
* @lp: the fc_port for this skb
* @skb: the associated skb to be xmitted
*
......@@ -764,7 +761,7 @@ void fcoe_watchdog(ulong vp)
* by the next skb transmit.
*
* Returns: 0 for success
**/
*/
static int fcoe_check_wait_queue(struct fc_lport *lp)
{
int rc;
......@@ -797,12 +794,12 @@ static int fcoe_check_wait_queue(struct fc_lport *lp)
}
/**
* fcoe_insert_wait_queue_head - puts skb to fcoe pending queue head
* fcoe_insert_wait_queue_head() - puts skb to fcoe pending queue head
* @lp: the fc_port for this skb
* @skb: the associated skb to be xmitted
*
* Returns: none
**/
*/
static void fcoe_insert_wait_queue_head(struct fc_lport *lp,
struct sk_buff *skb)
{
......@@ -815,12 +812,12 @@ static void fcoe_insert_wait_queue_head(struct fc_lport *lp,
}
/**
* fcoe_insert_wait_queue - put the skb into fcoe pending queue tail
* fcoe_insert_wait_queue() - put the skb into fcoe pending queue tail
* @lp: the fc_port for this skb
* @skb: the associated skb to be xmitted
*
* Returns: none
**/
*/
static void fcoe_insert_wait_queue(struct fc_lport *lp,
struct sk_buff *skb)
{
......@@ -833,10 +830,9 @@ static void fcoe_insert_wait_queue(struct fc_lport *lp,
}
/**
* fcoe_dev_setup - setup link change notification interface
*
**/
static void fcoe_dev_setup(void)
* fcoe_dev_setup() - setup link change notification interface
*/
static void fcoe_dev_setup()
{
/*
* here setup a interface specific wd time to
......@@ -846,15 +842,15 @@ static void fcoe_dev_setup(void)
}
/**
* fcoe_dev_setup - cleanup link change notification interface
**/
* fcoe_dev_setup() - cleanup link change notification interface
*/
static void fcoe_dev_cleanup(void)
{
unregister_netdevice_notifier(&fcoe_notifier);
}
/**
* fcoe_device_notification - netdev event notification callback
* fcoe_device_notification() - netdev event notification callback
* @notifier: context of the notification
* @event: type of event
* @ptr: fixed array for output parsed ifname
......@@ -862,7 +858,7 @@ static void fcoe_dev_cleanup(void)
* This function is called by the ethernet driver in case of link change event
*
* Returns: 0 for success
**/
*/
static int fcoe_device_notification(struct notifier_block *notifier,
ulong event, void *ptr)
{
......@@ -926,12 +922,12 @@ out:
}
/**
* fcoe_if_to_netdev - parse a name buffer to get netdev
* fcoe_if_to_netdev() - parse a name buffer to get netdev
* @ifname: fixed array for output parsed ifname
* @buffer: incoming buffer to be copied
*
* Returns: NULL or ptr to netdeive
**/
*/
static struct net_device *fcoe_if_to_netdev(const char *buffer)
{
char *cp;
......@@ -948,11 +944,11 @@ static struct net_device *fcoe_if_to_netdev(const char *buffer)
}
/**
* fcoe_netdev_to_module_owner - finds out the nic drive moddule of the netdev
* fcoe_netdev_to_module_owner() - finds out the nic drive moddule of the netdev
* @netdev: the target netdev
*
* Returns: ptr to the struct module, NULL for failure
**/
*/
static struct module *fcoe_netdev_to_module_owner(
const struct net_device *netdev)
{
......@@ -972,12 +968,14 @@ static struct module *fcoe_netdev_to_module_owner(
}
/**
* fcoe_ethdrv_get - holds the nic driver module by try_module_get() for
* the corresponding netdev.
* fcoe_ethdrv_get() - Hold the Ethernet driver