[SCSI] libfcoe: formatting and comment cleanups
Ensures that there are kernel-doc style comments for all
routines and structures.
There were also a few instances of fc_lport's named 'lp'
which were switched to 'lport' as per the libfc/libfcoe/fcoe
naming convention.
Also, emacs 'indent-region' and 'tabify' were ran on libfcoe.c.
Signed-off-by: Robert Love <robert.w.love@intel.com>
Signed-off-by: James Bottomley <James.Bottomley@suse.de>
diff --git a/drivers/scsi/fcoe/libfcoe.c b/drivers/scsi/fcoe/libfcoe.c
index 6a93ba9..6b07a84 100644
--- a/drivers/scsi/fcoe/libfcoe.c
+++ b/drivers/scsi/fcoe/libfcoe.c
@@ -59,15 +59,15 @@
module_param_named(debug_logging, libfcoe_debug_logging, int, S_IRUGO|S_IWUSR);
MODULE_PARM_DESC(debug_logging, "a bit mask of logging levels");
-#define LIBFCOE_LOGGING 0x01 /* General logging, not categorized */
+#define LIBFCOE_LOGGING 0x01 /* General logging, not categorized */
#define LIBFCOE_FIP_LOGGING 0x02 /* FIP logging */
-#define LIBFCOE_CHECK_LOGGING(LEVEL, CMD) \
-do { \
- if (unlikely(libfcoe_debug_logging & LEVEL)) \
- do { \
- CMD; \
- } while (0); \
+#define LIBFCOE_CHECK_LOGGING(LEVEL, CMD) \
+do { \
+ if (unlikely(libfcoe_debug_logging & LEVEL)) \
+ do { \
+ CMD; \
+ } while (0); \
} while (0)
#define LIBFCOE_DBG(fmt, args...) \
@@ -78,7 +78,10 @@
LIBFCOE_CHECK_LOGGING(LIBFCOE_FIP_LOGGING, \
printk(KERN_INFO "fip: " fmt, ##args);)
-/*
+/**
+ * fcoe_ctlr_mtu_valid() - Check if a FCF's MTU is valid
+ * @fcf: The FCF to check
+ *
* Return non-zero if FCF fcoe_size has been validated.
*/
static inline int fcoe_ctlr_mtu_valid(const struct fcoe_fcf *fcf)
@@ -86,7 +89,10 @@
return (fcf->flags & FIP_FL_SOL) != 0;
}
-/*
+/**
+ * fcoe_ctlr_fcf_usable() - Check if a FCF is usable
+ * @fcf: The FCF to check
+ *
* Return non-zero if the FCF is usable.
*/
static inline int fcoe_ctlr_fcf_usable(struct fcoe_fcf *fcf)
@@ -97,8 +103,8 @@
}
/**
- * fcoe_ctlr_init() - Initialize the FCoE Controller instance.
- * @fip: FCoE controller.
+ * fcoe_ctlr_init() - Initialize the FCoE Controller instance
+ * @fip: The FCoE controller to initialize
*/
void fcoe_ctlr_init(struct fcoe_ctlr *fip)
{
@@ -114,8 +120,8 @@
EXPORT_SYMBOL(fcoe_ctlr_init);
/**
- * fcoe_ctlr_reset_fcfs() - Reset and free all FCFs for a controller.
- * @fip: FCoE controller.
+ * fcoe_ctlr_reset_fcfs() - Reset and free all FCFs for a controller
+ * @fip: The FCoE controller whose FCFs are to be reset
*
* Called with &fcoe_ctlr lock held.
*/
@@ -134,8 +140,8 @@
}
/**
- * fcoe_ctlr_destroy() - Disable and tear-down the FCoE controller.
- * @fip: FCoE controller.
+ * fcoe_ctlr_destroy() - Disable and tear down a FCoE controller
+ * @fip: The FCoE controller to tear down
*
* This is called by FCoE drivers before freeing the &fcoe_ctlr.
*
@@ -162,8 +168,8 @@
EXPORT_SYMBOL(fcoe_ctlr_destroy);
/**
- * fcoe_ctlr_fcoe_size() - Return the maximum FCoE size required for VN_Port.
- * @fip: FCoE controller.
+ * fcoe_ctlr_fcoe_size() - Return the maximum FCoE size required for VN_Port
+ * @fip: The FCoE controller to get the maximum FCoE size from
*
* Returns the maximum packet size including the FCoE header and trailer,
* but not including any Ethernet or VLAN headers.
@@ -180,9 +186,9 @@
}
/**
- * fcoe_ctlr_solicit() - Send a solicitation.
- * @fip: FCoE controller.
- * @fcf: Destination FCF. If NULL, a multicast solicitation is sent.
+ * fcoe_ctlr_solicit() - Send a FIP solicitation
+ * @fip: The FCoE controller to send the solicitation on
+ * @fcf: The destination FCF (if NULL, a multicast solicitation is sent)
*/
static void fcoe_ctlr_solicit(struct fcoe_ctlr *fip, struct fcoe_fcf *fcf)
{
@@ -241,8 +247,8 @@
}
/**
- * fcoe_ctlr_link_up() - Start FCoE controller.
- * @fip: FCoE controller.
+ * fcoe_ctlr_link_up() - Start FCoE controller
+ * @fip: The FCoE controller to start
*
* Called from the LLD when the network link is ready.
*/
@@ -268,15 +274,15 @@
EXPORT_SYMBOL(fcoe_ctlr_link_up);
/**
- * fcoe_ctlr_reset() - Reset FIP.
- * @fip: FCoE controller.
- * @new_state: FIP state to be entered.
+ * fcoe_ctlr_reset() - Reset a FCoE controller
+ * @fip: The FCoE controller to reset
+ * @new_state: The FIP state to be entered
*
* Returns non-zero if the link was up and now isn't.
*/
static int fcoe_ctlr_reset(struct fcoe_ctlr *fip, enum fip_state new_state)
{
- struct fc_lport *lp = fip->lp;
+ struct fc_lport *lport = fip->lp;
int link_dropped;
spin_lock_bh(&fip->lock);
@@ -294,19 +300,19 @@
spin_unlock_bh(&fip->lock);
if (link_dropped)
- fc_linkdown(lp);
+ fc_linkdown(lport);
if (new_state == FIP_ST_ENABLED) {
fcoe_ctlr_solicit(fip, NULL);
- fc_linkup(lp);
+ fc_linkup(lport);
link_dropped = 0;
}
return link_dropped;
}
/**
- * fcoe_ctlr_link_down() - Stop FCoE controller.
- * @fip: FCoE controller.
+ * fcoe_ctlr_link_down() - Stop a FCoE controller
+ * @fip: The FCoE controller to be stopped
*
* Returns non-zero if the link was up and now isn't.
*
@@ -320,11 +326,11 @@
EXPORT_SYMBOL(fcoe_ctlr_link_down);
/**
- * fcoe_ctlr_send_keep_alive() - Send a keep-alive to the selected FCF.
- * @fip: FCoE controller.
- * @lport: libfc fc_lport to send from
- * @ports: 0 for controller keep-alive, 1 for port keep-alive.
- * @sa: source MAC address.
+ * fcoe_ctlr_send_keep_alive() - Send a keep-alive to the selected FCF
+ * @fip: The FCoE controller to send the FKA on
+ * @lport: libfc fc_lport to send from
+ * @ports: 0 for controller keep-alive, 1 for port keep-alive
+ * @sa: The source MAC address
*
* A controller keep-alive is sent every fka_period (typically 8 seconds).
* The source MAC is the native MAC address.
@@ -369,7 +375,7 @@
kal->fip.fip_op = htons(FIP_OP_CTRL);
kal->fip.fip_subcode = FIP_SC_KEEP_ALIVE;
kal->fip.fip_dl_len = htons((sizeof(kal->mac) +
- ports * sizeof(*vn)) / FIP_BPW);
+ ports * sizeof(*vn)) / FIP_BPW);
kal->fip.fip_flags = htons(FIP_FL_FPMA);
if (fip->spma)
kal->fip.fip_flags |= htons(FIP_FL_SPMA);
@@ -393,11 +399,10 @@
}
/**
- * fcoe_ctlr_encaps() - Encapsulate an ELS frame for FIP, without sending it.
- * @fip: FCoE controller.
- * @lport: libfc fc_lport to use for the source address
- * @dtype: FIP descriptor type for the frame.
- * @skb: FCoE ELS frame including FC header but no FCoE headers.
+ * fcoe_ctlr_encaps() - Encapsulate an ELS frame for FIP, without sending it
+ * @fip: The FCoE controller for the ELS frame
+ * @dtype: The FIP descriptor type for the frame
+ * @skb: The FCoE ELS frame including FC header but no FCoE headers
*
* Returns non-zero error code on failure.
*
@@ -553,9 +558,9 @@
}
EXPORT_SYMBOL(fcoe_ctlr_els_send);
-/*
- * fcoe_ctlr_age_fcfs() - Reset and free all old FCFs for a controller.
- * @fip: FCoE controller.
+/**
+ * fcoe_ctlr_age_fcfs() - Reset and free all old FCFs for a controller
+ * @fip: The FCoE controller to free FCFs on
*
* Called with lock held.
*
@@ -596,9 +601,9 @@
}
/**
- * fcoe_ctlr_parse_adv() - Decode a FIP advertisement into a new FCF entry.
- * @skb: received FIP advertisement frame
- * @fcf: resulting FCF entry.
+ * fcoe_ctlr_parse_adv() - Decode a FIP advertisement into a new FCF entry
+ * @skb: The received FIP advertisement frame
+ * @fcf: The resulting FCF entry
*
* Returns zero on a valid parsed advertisement,
* otherwise returns non zero value.
@@ -699,9 +704,9 @@
}
/**
- * fcoe_ctlr_recv_adv() - Handle an incoming advertisement.
- * @fip: FCoE controller.
- * @skb: Received FIP packet.
+ * fcoe_ctlr_recv_adv() - Handle an incoming advertisement
+ * @fip: The FCoE controller receiving the advertisement
+ * @skb: The received FIP packet
*/
static void fcoe_ctlr_recv_adv(struct fcoe_ctlr *fip, struct sk_buff *skb)
{
@@ -784,7 +789,7 @@
*/
if (mtu_valid && !fip->sel_time && fcoe_ctlr_fcf_usable(fcf)) {
fip->sel_time = jiffies +
- msecs_to_jiffies(FCOE_CTLR_START_DELAY);
+ msecs_to_jiffies(FCOE_CTLR_START_DELAY);
if (!timer_pending(&fip->timer) ||
time_before(fip->sel_time, fip->timer.expires))
mod_timer(&fip->timer, fip->sel_time);
@@ -794,13 +799,13 @@
}
/**
- * fcoe_ctlr_recv_els() - Handle an incoming FIP-encapsulated ELS frame.
- * @fip: FCoE controller.
- * @skb: Received FIP packet.
+ * fcoe_ctlr_recv_els() - Handle an incoming FIP encapsulated ELS frame
+ * @fip: The FCoE controller which received the packet
+ * @skb: The received FIP packet
*/
static void fcoe_ctlr_recv_els(struct fcoe_ctlr *fip, struct sk_buff *skb)
{
- struct fc_lport *lp = fip->lp;
+ struct fc_lport *lport = fip->lp;
struct fip_header *fiph;
struct fc_frame *fp = (struct fc_frame *)skb;
struct fc_frame_header *fh = NULL;
@@ -886,13 +891,13 @@
fc_frame_init(fp);
fr_sof(fp) = FC_SOF_I3;
fr_eof(fp) = FC_EOF_T;
- fr_dev(fp) = lp;
+ fr_dev(fp) = lport;
- stats = fc_lport_get_stats(lp);
+ stats = fc_lport_get_stats(lport);
stats->RxFrames++;
stats->RxWords += skb->len / FIP_BPW;
- fc_exch_recv(lp, fp);
+ fc_exch_recv(lport, fp);
return;
len_err:
@@ -903,15 +908,15 @@
}
/**
- * fcoe_ctlr_recv_els() - Handle an incoming link reset frame.
- * @fip: FCoE controller.
- * @fh: Received FIP header.
+ * fcoe_ctlr_recv_els() - Handle an incoming link reset frame
+ * @fip: The FCoE controller that received the frame
+ * @fh: The received FIP header
*
* There may be multiple VN_Port descriptors.
* The overall length has already been checked.
*/
static void fcoe_ctlr_recv_clr_vlink(struct fcoe_ctlr *fip,
- struct fip_header *fh)
+ struct fip_header *fh)
{
struct fip_desc *desc;
struct fip_mac_desc *mp;
@@ -920,13 +925,13 @@
size_t rlen;
size_t dlen;
struct fcoe_fcf *fcf = fip->sel_fcf;
- struct fc_lport *lp = fip->lp;
+ struct fc_lport *lport = fip->lp;
u32 desc_mask;
LIBFCOE_FIP_DBG("Clear Virtual Link received\n");
if (!fcf)
return;
- if (!fcf || !fc_host_port_id(lp->host))
+ if (!fcf || !fc_host_port_id(lport->host))
return;
/*
@@ -962,9 +967,10 @@
if (dlen < sizeof(*vp))
return;
if (compare_ether_addr(vp->fd_mac,
- fip->get_src_addr(lp)) == 0 &&
- get_unaligned_be64(&vp->fd_wwpn) == lp->wwpn &&
- ntoh24(vp->fd_fc_id) == fc_host_port_id(lp->host))
+ fip->get_src_addr(lport)) == 0 &&
+ get_unaligned_be64(&vp->fd_wwpn) == lport->wwpn &&
+ ntoh24(vp->fd_fc_id) ==
+ fc_host_port_id(lport->host))
desc_mask &= ~BIT(FIP_DT_VN_ID);
break;
default:
@@ -989,9 +995,9 @@
}
/**
- * fcoe_ctlr_recv() - Receive a FIP frame.
- * @fip: FCoE controller.
- * @skb: Received FIP packet.
+ * fcoe_ctlr_recv() - Receive a FIP packet
+ * @fip: The FCoE controller that received the packet
+ * @skb: The received FIP packet
*
* This is called from NET_RX_SOFTIRQ.
*/
@@ -1005,9 +1011,9 @@
EXPORT_SYMBOL(fcoe_ctlr_recv);
/**
- * fcoe_ctlr_recv_handler() - Receive a FIP frame.
- * @fip: FCoE controller.
- * @skb: Received FIP packet.
+ * fcoe_ctlr_recv_handler() - Receive a FIP frame
+ * @fip: The FCoE controller that received the frame
+ * @skb: The received FIP frame
*
* Returns non-zero if the frame is dropped.
*/
@@ -1064,8 +1070,8 @@
}
/**
- * fcoe_ctlr_select() - Select the best FCF, if possible.
- * @fip: FCoE controller.
+ * fcoe_ctlr_select() - Select the best FCF (if possible)
+ * @fip: The FCoE controller
*
* If there are conflicting advertisements, no FCF can be chosen.
*
@@ -1106,8 +1112,8 @@
}
/**
- * fcoe_ctlr_timeout() - FIP timer function.
- * @arg: &fcoe_ctlr pointer.
+ * fcoe_ctlr_timeout() - FIP timeout handler
+ * @arg: The FCoE controller that timed out
*
* Ages FCFs. Triggers FCF selection if possible. Sends keep-alives.
*/
@@ -1142,12 +1148,12 @@
fip->lp->host->host_no, sel->fcf_mac);
memcpy(fip->dest_addr, sel->fcf_mac, ETH_ALEN);
fip->port_ka_time = jiffies +
- msecs_to_jiffies(FIP_VN_KA_PERIOD);
+ msecs_to_jiffies(FIP_VN_KA_PERIOD);
fip->ctlr_ka_time = jiffies + sel->fka_period;
fip->link = 1;
} else {
printk(KERN_NOTICE "libfcoe: host%d: "
- "FIP Fibre-Channel Forwarder timed out. "
+ "FIP Fibre-Channel Forwarder timed out. "
"Starting FCF discovery.\n",
fip->lp->host->host_no);
fip->link = 0;
@@ -1165,7 +1171,7 @@
if (time_after_eq(jiffies, fip->port_ka_time)) {
fip->port_ka_time += jiffies +
- msecs_to_jiffies(FIP_VN_KA_PERIOD);
+ msecs_to_jiffies(FIP_VN_KA_PERIOD);
fip->send_port_ka = 1;
}
if (time_after(next_timer, fip->port_ka_time))
@@ -1173,7 +1179,7 @@
mod_timer(&fip->timer, next_timer);
} else if (fip->sel_time) {
next_timer = fip->sel_time +
- msecs_to_jiffies(FCOE_CTLR_START_DELAY);
+ msecs_to_jiffies(FCOE_CTLR_START_DELAY);
mod_timer(&fip->timer, next_timer);
}
if (fip->send_ctlr_ka || fip->send_port_ka)
@@ -1182,8 +1188,8 @@
}
/**
- * fcoe_ctlr_link_work() - worker thread function for link changes.
- * @work: pointer to link_work member inside &fcoe_ctlr.
+ * fcoe_ctlr_link_work() - Worker thread function for link changes
+ * @work: Handle to a FCoE controller
*
* See if the link status has changed and if so, report it.
*
@@ -1230,8 +1236,8 @@
}
/**
- * fcoe_ctlr_recv_work() - Worker thread function for receiving FIP frames.
- * @recv_work: pointer to recv_work member inside &fcoe_ctlr.
+ * fcoe_ctlr_recv_work() - Worker thread function for receiving FIP frames
+ * @recv_work: Handle to a FCoE controller
*/
static void fcoe_ctlr_recv_work(struct work_struct *recv_work)
{
@@ -1249,11 +1255,10 @@
}
/**
- * fcoe_ctlr_recv_flogi() - snoop Pre-FIP receipt of FLOGI response or request.
- * @fip: FCoE controller.
- * @lport: libfc fc_lport instance received on
- * @fp: FC frame.
- * @sa: Ethernet source MAC address from received FCoE frame.
+ * fcoe_ctlr_recv_flogi() - Snoop pre-FIP receipt of FLOGI response or request
+ * @fip: The FCoE controller
+ * @fp: The FC frame to snoop
+ * @sa: Ethernet source MAC address from received FCoE frame
*
* Snoop potential response to FLOGI or even incoming FLOGI.
*
@@ -1323,10 +1328,10 @@
EXPORT_SYMBOL(fcoe_ctlr_recv_flogi);
/**
- * fcoe_wwn_from_mac() - Converts 48-bit IEEE MAC address to 64-bit FC WWN.
- * @mac: mac address
- * @scheme: check port
- * @port: port indicator for converting
+ * fcoe_wwn_from_mac() - Converts a 48-bit IEEE MAC address to a 64-bit FC WWN
+ * @mac: The MAC address to convert
+ * @scheme: The scheme to use when converting
+ * @port: The port indicator for converting
*
* Returns: u64 fc world wide name
*/
@@ -1364,23 +1369,24 @@
EXPORT_SYMBOL_GPL(fcoe_wwn_from_mac);
/**
- * fcoe_libfc_config() - sets up libfc related properties for lport
- * @lp: ptr to the fc_lport
- * @tt: libfc function template
+ * fcoe_libfc_config() - Sets up libfc related properties for local port
+ * @lp: The local port to configure libfc for
+ * @tt: The libfc function template
*
* Returns : 0 for success
*/
-int fcoe_libfc_config(struct fc_lport *lp, struct libfc_function_template *tt)
+int fcoe_libfc_config(struct fc_lport *lport,
+ struct libfc_function_template *tt)
{
/* Set the function pointers set by the LLDD */
- memcpy(&lp->tt, tt, sizeof(*tt));
- if (fc_fcp_init(lp))
+ memcpy(&lport->tt, tt, sizeof(*tt));
+ if (fc_fcp_init(lport))
return -ENOMEM;
- fc_exch_init(lp);
- fc_elsct_init(lp);
- fc_lport_init(lp);
- fc_rport_init(lp);
- fc_disc_init(lp);
+ fc_exch_init(lport);
+ fc_elsct_init(lport);
+ fc_lport_init(lport);
+ fc_rport_init(lport);
+ fc_disc_init(lport);
return 0;
}