From b0dca40304ae0262722400b11eb15e961b06ac82 Mon Sep 17 00:00:00 2001 From: Xiao Wang Date: Fri, 19 Feb 2016 19:07:01 +0800 Subject: [PATCH] fm10k/base: improve comments The comment for fm10k_iov_msg_lport_state_pf was changed during review of kernel driver, and the new wording is slightly clearer. Re-write the comment in base code based on this new wording. Fix a number of mailbox comment issues with function header comments, lower-case acronyms (i.e. FIFO, TLV), incorrect function names in DEBUGFUNC(), duplicate comments and a stubbed-out header comment for fm10k_sm_mbx_init. Signed-off-by: Wang Xiao W Tested-by: Heng Ding Acked-by: Jing Chen --- drivers/net/fm10k/base/fm10k_mbx.c | 61 ++++++++++++++++++------------ drivers/net/fm10k/base/fm10k_mbx.h | 4 +- drivers/net/fm10k/base/fm10k_pf.c | 12 +++--- drivers/net/fm10k/base/fm10k_tlv.c | 2 +- drivers/net/fm10k/base/fm10k_tlv.h | 4 +- 5 files changed, 47 insertions(+), 36 deletions(-) diff --git a/drivers/net/fm10k/base/fm10k_mbx.c b/drivers/net/fm10k/base/fm10k_mbx.c index 7d03704615..2e70434024 100644 --- a/drivers/net/fm10k/base/fm10k_mbx.c +++ b/drivers/net/fm10k/base/fm10k_mbx.c @@ -70,7 +70,7 @@ STATIC u16 fm10k_fifo_unused(struct fm10k_mbx_fifo *fifo) } /** - * fm10k_fifo_empty - Test to verify if fifo is empty + * fm10k_fifo_empty - Test to verify if FIFO is empty * @fifo: pointer to FIFO * * This function returns true if the FIFO is empty, else false @@ -85,7 +85,7 @@ STATIC bool fm10k_fifo_empty(struct fm10k_mbx_fifo *fifo) * @fifo: pointer to FIFO * @offset: offset to add to head * - * This function returns the indices into the fifo based on head + offset + * This function returns the indices into the FIFO based on head + offset **/ STATIC u16 fm10k_fifo_head_offset(struct fm10k_mbx_fifo *fifo, u16 offset) { @@ -97,7 +97,7 @@ STATIC u16 fm10k_fifo_head_offset(struct fm10k_mbx_fifo *fifo, u16 offset) * @fifo: pointer to FIFO * @offset: offset to add to tail * - * This function returns the indices into the fifo based on tail + offset + * This function returns the indices into the FIFO based on tail + offset **/ STATIC u16 fm10k_fifo_tail_offset(struct fm10k_mbx_fifo *fifo, u16 offset) { @@ -173,7 +173,7 @@ STATIC u16 fm10k_mbx_index_len(struct fm10k_mbx_info *mbx, u16 head, u16 tail) /** * fm10k_mbx_tail_add - Determine new tail value with added offset * @mbx: pointer to mailbox - * @offset: length to add to head offset + * @offset: length to add to tail offset * * This function takes the local tail index and recomputes it for * a given length added as an offset. @@ -189,7 +189,7 @@ STATIC u16 fm10k_mbx_tail_add(struct fm10k_mbx_info *mbx, u16 offset) /** * fm10k_mbx_tail_sub - Determine new tail value with subtracted offset * @mbx: pointer to mailbox - * @offset: length to add to head offset + * @offset: length to add to tail offset * * This function takes the local tail index and recomputes it for * a given length added as an offset. @@ -253,7 +253,7 @@ STATIC u16 fm10k_mbx_pushed_tail_len(struct fm10k_mbx_info *mbx) } /** - * fm10k_fifo_write_copy - pulls data off of msg and places it in fifo + * fm10k_fifo_write_copy - pulls data off of msg and places it in FIFO * @fifo: pointer to FIFO * @msg: message array to populate * @tail_offset: additional offset to add to tail pointer @@ -331,7 +331,7 @@ STATIC u16 fm10k_mbx_validate_msg_size(struct fm10k_mbx_info *mbx, u16 len) u16 total_len = 0, msg_len; u32 *msg; - DEBUGFUNC("fm10k_mbx_validate_msg"); + DEBUGFUNC("fm10k_mbx_validate_msg_size"); /* length should include previous amounts pushed */ len += mbx->pushed; @@ -353,6 +353,7 @@ STATIC u16 fm10k_mbx_validate_msg_size(struct fm10k_mbx_info *mbx, u16 len) /** * fm10k_mbx_write_copy - pulls data off of Tx FIFO and places it in mbmem + * @hw: pointer to hardware structure * @mbx: pointer to mailbox * * This function will take a section of the Tx FIFO and copy it into the @@ -734,7 +735,7 @@ STATIC bool fm10k_mbx_tx_complete(struct fm10k_mbx_info *mbx) * @hw: pointer to hardware structure * @mbx: pointer to mailbox * - * This function dequeues messages and hands them off to the tlv parser. + * This function dequeues messages and hands them off to the TLV parser. * It will return the number of messages processed when called. **/ STATIC u16 fm10k_mbx_dequeue_rx(struct fm10k_hw *hw, @@ -951,7 +952,7 @@ STATIC void fm10k_mbx_create_fake_disconnect_hdr(struct fm10k_mbx_info *mbx) } /** - * fm10k_mbx_create_error_msg - Generate a error message + * fm10k_mbx_create_error_msg - Generate an error message * @mbx: pointer to mailbox * @err: local error encountered * @@ -984,7 +985,6 @@ STATIC void fm10k_mbx_create_error_msg(struct fm10k_mbx_info *mbx, s32 err) /** * fm10k_mbx_validate_msg_hdr - Validate common fields in the message header * @mbx: pointer to mailbox - * @msg: message array to read * * This function will parse up the fields in the mailbox header and return * an error if the header contains any of a number of invalid configurations @@ -1050,11 +1050,12 @@ STATIC s32 fm10k_mbx_validate_msg_hdr(struct fm10k_mbx_info *mbx) /** * fm10k_mbx_create_reply - Generate reply based on state and remote head + * @hw: pointer to hardware structure * @mbx: pointer to mailbox * @head: acknowledgement number * * This function will generate an outgoing message based on the current - * mailbox state and the remote fifo head. It will return the length + * mailbox state and the remote FIFO head. It will return the length * of the outgoing message excluding header on success, and a negative value * on error. **/ @@ -1130,7 +1131,7 @@ STATIC void fm10k_mbx_reset_work(struct fm10k_mbx_info *mbx) } /** - * fm10k_mbx_update_max_size - Update the max_size and drop large messages + * fm10k_mbx_update_max_size - Update the max_size and drop any large messages * @mbx: pointer to mailbox * @size: new value for max_size * @@ -1144,7 +1145,7 @@ STATIC void fm10k_mbx_update_max_size(struct fm10k_mbx_info *mbx, u16 size) { u16 len; - DEBUGFUNC("fm10k_mbx_update_max_size_hdr"); + DEBUGFUNC("fm10k_mbx_update_max_size"); mbx->max_size = size; @@ -1182,8 +1183,8 @@ STATIC void fm10k_mbx_connect_reset(struct fm10k_mbx_info *mbx) /** * fm10k_mbx_process_connect - Process connect header + * @hw: pointer to hardware structure * @mbx: pointer to mailbox - * @msg: message array to process * * This function will read an incoming connect header and reply with the * appropriate message. It will return a value indicating the number of @@ -1229,6 +1230,7 @@ STATIC s32 fm10k_mbx_process_connect(struct fm10k_hw *hw, /** * fm10k_mbx_process_data - Process data header + * @hw: pointer to hardware structure * @mbx: pointer to mailbox * * This function will read an incoming data header and reply with the @@ -1272,6 +1274,7 @@ STATIC s32 fm10k_mbx_process_data(struct fm10k_hw *hw, /** * fm10k_mbx_process_disconnect - Process disconnect header + * @hw: pointer to hardware structure * @mbx: pointer to mailbox * * This function will read an incoming disconnect header and reply with the @@ -1324,6 +1327,7 @@ STATIC s32 fm10k_mbx_process_disconnect(struct fm10k_hw *hw, /** * fm10k_mbx_process_error - Process error header + * @hw: pointer to hardware structure * @mbx: pointer to mailbox * * This function will read an incoming error header and reply with the @@ -1501,6 +1505,7 @@ STATIC s32 fm10k_mbx_connect(struct fm10k_hw *hw, struct fm10k_mbx_info *mbx) fm10k_mbx_reset_work(mbx); + /* initialize header of remote mailbox */ fm10k_mbx_create_fake_disconnect_hdr(mbx); FM10K_WRITE_MBX(hw, mbx->mbmem_reg ^ mbx->mbmem_len, mbx->mbx_hdr); @@ -1602,7 +1607,7 @@ STATIC s32 fm10k_mbx_register_handlers(struct fm10k_mbx_info *mbx, * @id: ID reference for PF as it supports up to 64 PF/VF mailboxes * * This function initializes the mailbox for use. It will split the - * buffer provided an use that th populate both the Tx and Rx FIFO by + * buffer provided and use that to populate both the Tx and Rx FIFO by * evenly splitting it. In order to allow for easy masking of head/tail * the value reported in size must be a power of 2 and is reported in * DWORDs, not bytes. Any invalid values will cause the mailbox to return @@ -1681,7 +1686,7 @@ s32 fm10k_pfvf_mbx_init(struct fm10k_hw *hw, struct fm10k_mbx_info *mbx, * fm10k_sm_mbx_create_data_hdr - Generate a mailbox header for local FIFO * @mbx: pointer to mailbox * - * This function returns a connection mailbox header + * This function returns a data mailbox header **/ STATIC void fm10k_sm_mbx_create_data_hdr(struct fm10k_mbx_info *mbx) { @@ -1748,7 +1753,7 @@ STATIC void fm10k_sm_mbx_connect_reset(struct fm10k_mbx_info *mbx) **/ STATIC s32 fm10k_sm_mbx_connect(struct fm10k_hw *hw, struct fm10k_mbx_info *mbx) { - DEBUGFUNC("fm10k_mbx_connect"); + DEBUGFUNC("fm10k_sm_mbx_connect"); /* we cannot connect an uninitialized mailbox */ if (!mbx->rx.buffer) @@ -1776,8 +1781,6 @@ STATIC s32 fm10k_sm_mbx_connect(struct fm10k_hw *hw, struct fm10k_mbx_info *mbx) fm10k_sm_mbx_create_connect_hdr(mbx, 0); fm10k_mbx_write(hw, mbx); - /* enable interrupt and notify other party of new message */ - return FM10K_SUCCESS; } @@ -1823,7 +1826,7 @@ STATIC void fm10k_sm_mbx_disconnect(struct fm10k_hw *hw, } /** - * fm10k_mbx_validate_fifo_hdr - Validate fields in the remote FIFO header + * fm10k_sm_mbx_validate_fifo_hdr - Validate fields in the remote FIFO header * @mbx: pointer to mailbox * * This function will parse up the fields in the mailbox header and return @@ -1835,7 +1838,7 @@ STATIC s32 fm10k_sm_mbx_validate_fifo_hdr(struct fm10k_mbx_info *mbx) const u32 *hdr = &mbx->mbx_hdr; u16 tail, head, ver; - DEBUGFUNC("fm10k_mbx_validate_msg_hdr"); + DEBUGFUNC("fm10k_sm_mbx_validate_fifo_hdr"); tail = FM10K_MSG_HDR_FIELD_GET(*hdr, SM_TAIL); ver = FM10K_MSG_HDR_FIELD_GET(*hdr, SM_VER); @@ -1903,7 +1906,7 @@ STATIC void fm10k_sm_mbx_process_error(struct fm10k_mbx_info *mbx) } /** - * fm10k_sm_mbx_create_error_message - Process an error in FIFO hdr + * fm10k_sm_mbx_create_error_msg - Process an error in FIFO header * @mbx: pointer to mailbox * @err: local error encountered * @@ -1933,6 +1936,7 @@ STATIC void fm10k_sm_mbx_create_error_msg(struct fm10k_mbx_info *mbx, s32 err) * fm10k_sm_mbx_receive - Take message from Rx mailbox FIFO and put it in Rx * @hw: pointer to hardware structure * @mbx: pointer to mailbox + * @tail: tail index of message * * This function will dequeue one message from the Rx switch manager mailbox * FIFO and place it in the Rx mailbox FIFO for processing by software. @@ -1974,6 +1978,7 @@ STATIC s32 fm10k_sm_mbx_receive(struct fm10k_hw *hw, * fm10k_sm_mbx_transmit - Take message from Tx and put it in Tx mailbox FIFO * @hw: pointer to hardware structure * @mbx: pointer to mailbox + * @head: head index of message * * This function will dequeue one message from the Tx mailbox FIFO and place * it in the Tx switch manager mailbox FIFO for processing by hardware. @@ -2015,11 +2020,12 @@ STATIC void fm10k_sm_mbx_transmit(struct fm10k_hw *hw, /** * fm10k_sm_mbx_create_reply - Generate reply based on state and remote head + * @hw: pointer to hardware structure * @mbx: pointer to mailbox * @head: acknowledgement number * * This function will generate an outgoing message based on the current - * mailbox state and the remote fifo head. It will return the length + * mailbox state and the remote FIFO head. It will return the length * of the outgoing message excluding header on success, and a negative value * on error. **/ @@ -2131,7 +2137,7 @@ send_reply: } /** - * fm10k_sm_mbx_process - Process mailbox switch mailbox interrupt + * fm10k_sm_mbx_process - Process switch manager mailbox interrupt * @hw: pointer to hardware structure * @mbx: pointer to mailbox * @@ -2189,7 +2195,12 @@ fifo_err: * @mbx: pointer to mailbox * @msg_data: handlers for mailbox events * - * This function for now is used to stub out the PF/SM mailbox + * This function initializes the PF/SM mailbox for use. It will split the + * buffer provided and use that to populate both the Tx and Rx FIFO by + * evenly splitting it. In order to allow for easy masking of head/tail + * the value reported in size must be a power of 2 and is reported in + * DWORDs, not bytes. Any invalid values will cause the mailbox to return + * error. **/ s32 fm10k_sm_mbx_init(struct fm10k_hw *hw, struct fm10k_mbx_info *mbx, const struct fm10k_msg_data *msg_data) diff --git a/drivers/net/fm10k/base/fm10k_mbx.h b/drivers/net/fm10k/base/fm10k_mbx.h index 4b22f0efdb..e642c2ff8e 100644 --- a/drivers/net/fm10k/base/fm10k_mbx.h +++ b/drivers/net/fm10k/base/fm10k_mbx.h @@ -144,11 +144,11 @@ enum fm10k_mbx_state { * The maximum message size is provided during connect to avoid * jamming the mailbox with messages that do not fit. * Err_no: Error number - Applies only to error headers - * The error number provides a indication of the type of error + * The error number provides an indication of the type of error * experienced. */ -/* macros for retriving and setting header values */ +/* macros for retrieving and setting header values */ #define FM10K_MSG_HDR_MASK(name) \ ((0x1u << FM10K_MSG_##name##_SIZE) - 1) #define FM10K_MSG_HDR_FIELD_SET(value, name) \ diff --git a/drivers/net/fm10k/base/fm10k_pf.c b/drivers/net/fm10k/base/fm10k_pf.c index 716d7f1bd2..456fe6413a 100644 --- a/drivers/net/fm10k/base/fm10k_pf.c +++ b/drivers/net/fm10k/base/fm10k_pf.c @@ -1105,7 +1105,7 @@ STATIC s32 fm10k_iov_reset_resources_pf(struct fm10k_hw *hw, FM10K_WRITE_REG(hw, FM10K_RQMAP(qmap_idx + i), vf_q_idx + i); } - /* repeat the first ring for all of the remaining VF rings */ + /* repeat the first ring for all the remaining VF rings */ for (i = queues_per_pool; i < qmap_stride; i++) { FM10K_WRITE_REG(hw, FM10K_TQMAP(qmap_idx + i), vf_q_idx); FM10K_WRITE_REG(hw, FM10K_RQMAP(qmap_idx + i), vf_q_idx); @@ -1246,9 +1246,9 @@ s32 fm10k_iov_msg_mac_vlan_pf(struct fm10k_hw *hw, u32 **results, struct fm10k_mbx_info *mbx) { struct fm10k_vf_info *vf_info = (struct fm10k_vf_info *)mbx; - int err = FM10K_SUCCESS; u8 mac[ETH_ALEN]; u32 *result; + int err = FM10K_SUCCESS; bool set; u16 vlan; u32 vid; @@ -1427,10 +1427,10 @@ s32 fm10k_iov_msg_lport_state_pf(struct fm10k_hw *hw, u32 **results, err = fm10k_update_lport_state_pf(hw, vf_info->glort, 1, false); - /* need to clear VF_FLAG_ENABLED in order to ensure that we - * actually re-enable the lport state below. Note that this - * has no impact if VF is already disabled, as the flags are - * already zeroed. + /* we need to clear VF_FLAG_ENABLED flags in order to ensure + * that we actually re-enable the LPORT state below. Note that + * this has no impact if the VF is already disabled, as the + * flags are already cleared. */ if (!err) vf_info->vf_flags = FM10K_VF_FLAG_CAPABLE(vf_info); diff --git a/drivers/net/fm10k/base/fm10k_tlv.c b/drivers/net/fm10k/base/fm10k_tlv.c index b9000ae0de..e6150c1d85 100644 --- a/drivers/net/fm10k/base/fm10k_tlv.c +++ b/drivers/net/fm10k/base/fm10k_tlv.c @@ -405,7 +405,7 @@ static u32 *fm10k_tlv_attr_nest_start(u32 *msg, u16 attr_id) } /** - * fm10k_tlv_attr_nest_start - Start a set of nested attributes + * fm10k_tlv_attr_nest_stop - Stop a set of nested attributes * @msg: Pointer to message block * * This function closes off an existing set of nested attributes. The diff --git a/drivers/net/fm10k/base/fm10k_tlv.h b/drivers/net/fm10k/base/fm10k_tlv.h index a297bb8781..8f85fce3fe 100644 --- a/drivers/net/fm10k/base/fm10k_tlv.h +++ b/drivers/net/fm10k/base/fm10k_tlv.h @@ -51,9 +51,9 @@ struct fm10k_msg_data; * mailbox size we will provide a message with the above header and it * will be segmented and transported to the mailbox to the other side where * it is reassembled. It contains the following fields: - * Len: Length of the message in bytes excluding the message header + * Length: Length of the message in bytes excluding the message header * Flags: TBD - * Rule: These will be the message/argument types we pass + * Type/ID: These will be the message/argument types we pass */ /* message data header */ #define FM10K_TLV_ID_SHIFT 0 -- 2.20.1