Commit 3caf1b48 authored by Lee Jones's avatar Lee Jones Committed by Greg Kroah-Hartman
Browse files

misc: ti-st: st_kim: Tidy-up bespoke commentry 



If it's still in use and worth the effort, it sure looks like
this driver could do with a good scrub (clean).

This patch conserns itself with the non-standard comments located
thoughout the file.

It also fixes the following W=1 warnings by demoting the kerneldoc
function headers to standard comments, since there doesn't appear
to be a requirement for the function args to be documented:

 /drivers/misc/ti-st/st_kim.c:42: warning: Function parameter or member 'id' not described in 'st_get_plat_device'
 /drivers/misc/ti-st/st_kim.c:53: warning: Function parameter or member 'kim_gdata' not described in 'validate_firmware_response'
 /drivers/misc/ti-st/st_kim.c:126: warning: Function parameter or member 'kim_gdata' not described in 'kim_int_recv'
 /drivers/misc/ti-st/st_kim.c:126: warning: Function parameter or member 'data' not described in 'kim_int_recv'
 /drivers/misc/ti-st/st_kim.c:126: warning: Function parameter or member 'count' not described in 'kim_int_recv'
 /drivers/misc/ti-st/st_kim.c:272: warning: Function parameter or member 'kim_gdata' not described in 'download_firmware'
 /drivers/misc/ti-st/st_kim.c:445: warning: Function parameter or member 'kim_data' not described in 'st_kim_start'
 /drivers/misc/ti-st/st_kim.c:509: warning: Function parameter or member 'kim_data' not described in 'st_kim_stop'
 /drivers/misc/ti-st/st_kim.c:661: warning: Function parameter or member 'core_data' not described in 'st_kim_ref'
 /drivers/misc/ti-st/st_kim.c:661: warning: Function parameter or member 'id' not described in 'st_kim_ref'

Cc: Pavan Savoy <pavan_savoy@ti.com>
Acked-by: default avatarArnd Bergmann <arnd@arndb.de>
Signed-off-by: default avatarLee Jones <lee.jones@linaro.org>
Link: https://lore.kernel.org/r/20200626130525.389469-4-lee.jones@linaro.org


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 7e8eebef

drivers/misc/ti-st/st_kim.c

+44 −27
Original line number Diff line number Diff line
@@ -30,7 +30,7 @@ static struct platform_device *st_kim_devices[MAX_ST_DEVICES]; 
/**********************************************************************/

/* internal functions */



/**

/*

 * st_get_plat_device -

 *	function which returns the reference to the platform device

 *	requested by id. As of now only 1 such device exists (id=0)
@@ -43,7 +43,7 @@ static struct platform_device *st_get_plat_device(int id) 
	return st_kim_devices[id];

}



/**

/*

 * validate_firmware_response -

 *	function to return whether the firmware response was proper

 *	in case of error don't complete so that waiting for proper
@@ -55,7 +55,8 @@ static void validate_firmware_response(struct kim_data_s *kim_gdata) 
	if (!skb)

		return;



	/* these magic numbers are the position in the response buffer which

	/*

	 * these magic numbers are the position in the response buffer which

	 * allows us to distinguish whether the response is for the read

	 * version info. command

	 */
@@ -79,7 +80,8 @@ static void validate_firmware_response(struct kim_data_s *kim_gdata) 
	kfree_skb(skb);

}



/* check for data len received inside kim_int_recv

/*

 * check for data len received inside kim_int_recv

 * most often hit the last case to update state to waiting for data

 */

static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len)
@@ -91,14 +93,16 @@ static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len) 
	if (!len) {

		validate_firmware_response(kim_gdata);

	} else if (len > room) {

		/* Received packet's payload length is larger.

		/*

		 * Received packet's payload length is larger.

		 * We can't accommodate it in created skb.

		 */

		pr_err("Data length is too large len %d room %d", len,

			   room);

		kfree_skb(kim_gdata->rx_skb);

	} else {

		/* Packet header has non-zero payload length and

		/*

		 * Packet header has non-zero payload length and

		 * we have enough space in created skb. Lets read

		 * payload data */

		kim_gdata->rx_state = ST_W4_DATA;
@@ -106,8 +110,10 @@ static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len) 
		return len;

	}



	/* Change ST LL state to continue to process next

	 * packet */

	/*

	 * Change ST LL state to continue to process next

	 * packet

	 */

	kim_gdata->rx_state = ST_W4_PACKET_TYPE;

	kim_gdata->rx_skb = NULL;

	kim_gdata->rx_count = 0;
@@ -115,7 +121,7 @@ static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len) 
	return 0;

}



/**

/*

 * kim_int_recv - receive function called during firmware download

 *	firmware download responses on different UART drivers

 *	have been observed to come in bursts of different
@@ -216,7 +222,8 @@ static long read_local_version(struct kim_data_s *kim_gdata, char *bts_scr_name) 
		return timeout ? -ERESTARTSYS : -ETIMEDOUT;

	}

	reinit_completion(&kim_gdata->kim_rcvd);

	/* the positions 12 & 13 in the response buffer provide with the

	/*

	 * the positions 12 & 13 in the response buffer provide with the

	 * chip, major & minor numbers

	 */
@@ -263,7 +270,7 @@ static void skip_change_remote_baud(unsigned char **ptr, long *len) 
	}

}



/**

/*

 * download_firmware -

 *	internal function which parses through the .bts firmware

 *	script file intreprets SEND, DELAY actions only as of now
@@ -295,7 +302,8 @@ static long download_firmware(struct kim_data_s *kim_gdata) 
	}

	ptr = (void *)kim_gdata->fw_entry->data;

	len = kim_gdata->fw_entry->size;

	/* bts_header to remove out magic number and

	/*

	 * bts_header to remove out magic number and

	 * version

	 */

	ptr += sizeof(struct bts_header);
@@ -313,8 +321,10 @@ static long download_firmware(struct kim_data_s *kim_gdata) 
			if (unlikely

			    (((struct hci_command *)action_ptr)->opcode ==

			     0xFF36)) {

				/* ignore remote change

				 * baud rate HCI VS command */

				/*

				 * ignore remote change

				 * baud rate HCI VS command

				 */

				pr_warn("change remote baud"

				    " rate command in firmware");

				skip_change_remote_baud(&ptr, &len);
@@ -346,7 +356,8 @@ static long download_firmware(struct kim_data_s *kim_gdata) 
				release_firmware(kim_gdata->fw_entry);

				return -ETIMEDOUT;

			}

			/* reinit completion before sending for the

			/*

			 * reinit completion before sending for the

			 * relevant wait

			 */

			reinit_completion(&kim_gdata->kim_rcvd);
@@ -418,14 +429,16 @@ void st_kim_recv(void *disc_data, const unsigned char *data, long count) 
	struct st_data_s	*st_gdata = (struct st_data_s *)disc_data;

	struct kim_data_s	*kim_gdata = st_gdata->kim_data;



	/* proceed to gather all data and distinguish read fw version response

	/*

	 * proceed to gather all data and distinguish read fw version response

	 * from other fw responses when data gathering is complete

	 */

	kim_int_recv(kim_gdata, data, count);

	return;

}



/* to signal completion of line discipline installation

/*

 * to signal completion of line discipline installation

 * called from ST Core, upon tty_open

 */

void st_kim_complete(void *kim_data)
@@ -434,7 +447,7 @@ void st_kim_complete(void *kim_data) 
	complete(&kim_gdata->ldisc_installed);

}



/**

/*

 * st_kim_start - called from ST Core upon 1st registration

 *	This involves toggling the chip enable gpio, reading

 *	the firmware version from chip, forming the fw file name
@@ -472,8 +485,10 @@ long st_kim_start(void *kim_data) 
		err = wait_for_completion_interruptible_timeout(

			&kim_gdata->ldisc_installed, msecs_to_jiffies(LDISC_TIME));

		if (!err) {

			/* ldisc installation timeout,

			 * flush uart, power cycle BT_EN */

			/*

			 * ldisc installation timeout,

			 * flush uart, power cycle BT_EN

			 */

			pr_err("ldisc installation timeout");

			err = st_kim_stop(kim_gdata);

			continue;
@@ -482,8 +497,10 @@ long st_kim_start(void *kim_data) 
			pr_info("line discipline installed");

			err = download_firmware(kim_gdata);

			if (err != 0) {

				/* ldisc installed but fw download failed,

				 * flush uart & power cycle BT_EN */

				/*

				 * ldisc installed but fw download failed,

				 * flush uart & power cycle BT_EN

				 */

				pr_err("download firmware failed");

				err = st_kim_stop(kim_gdata);

				continue;
@@ -495,7 +512,7 @@ long st_kim_start(void *kim_data) 
	return err;

}



/**

/*

 * st_kim_stop - stop communication with chip.

 *	This can be called from ST Core/KIM, on the-

 *	(a) last un-register when chip need not be powered there-after,
@@ -650,7 +667,7 @@ static const struct attribute_group uim_attr_grp = { 
	.attrs = uim_attrs,

};



/**

/*

 * st_kim_ref - reference the core's data

 *	This references the per-ST platform device in the arch/xx/

 *	board-xx.c file.
@@ -729,8 +746,7 @@ static int kim_probe(struct platform_device *pdev) 
		pr_err(" unable to configure gpio %d", kim_gdata->nshutdown);

		goto err_sysfs_group;

	}

	/* get reference of pdev for request_firmware

	 */

	/* get reference of pdev for request_firmware */

	kim_gdata->kim_pdev = pdev;

	init_completion(&kim_gdata->kim_rcvd);

	init_completion(&kim_gdata->ldisc_installed);
@@ -772,7 +788,8 @@ static int kim_remove(struct platform_device *pdev) 


	kim_gdata = platform_get_drvdata(pdev);



	/* Free the Bluetooth/FM/GPIO

	/*

	 * Free the Bluetooth/FM/GPIO

	 * nShutdown gpio from the system

	 */

	gpio_free(pdata->nshutdown_gpio);