[PATCH linux dev-4.10 v3 25/31] drivers: fsi: occ: Add comments for clarity

Fri Oct 6 10:17:33 AEDT 2017

On Thu, 2017-10-05 at 14:24 -0500, Eddie James wrote:
> From: "Edward A. James" <eajames at us.ibm.com>
> 
> Fixup some existing comments as well.
> 
> Signed-off-by: Edward A. James <eajames at us.ibm.com>

Reviewed-by: Andrew Jeffery <andrew at aj.id.au>

> ---
>  drivers/fsi/occ.c | 55 +++++++++++++++++++++++++++++++++++++------
------------
>  1 file changed, 37 insertions(+), 18 deletions(-)
> 
> diff --git a/drivers/fsi/occ.c b/drivers/fsi/occ.c
> index 561b029..29a17ed 100644
> --- a/drivers/fsi/occ.c
> +++ b/drivers/fsi/occ.c
> @@ -39,8 +39,8 @@ struct occ {
>  	int idx;
>  	struct miscdevice mdev;
>  	struct list_head xfrs;
> -	spinlock_t list_lock;
> -	struct mutex occ_lock;
> +	spinlock_t list_lock;		/* lock access to the
xfrs list */
> +	struct mutex occ_lock;		/* lock access to the
hardware */
>  	struct work_struct work;
>  };
>  
> @@ -57,17 +57,17 @@ struct occ_response {
>  
>  /*
>   * transfer flags are NOT mutually exclusive
> - * 
> + *
>   * Initial flags are none; transfer is created and queued from
write(). All
> - * 	flags are cleared when the transfer is completed by
closing the file or
> - * 	reading all of the available response data.
> + *  flags are cleared when the transfer is completed by closing the
file or
> + *  reading all of the available response data.
>   * XFR_IN_PROGRESS is set when a transfer is started from
occ_worker_putsram,
> - * 	and cleared if the transfer fails or occ_worker_getsram
completes.
> + *  and cleared if the transfer fails or occ_worker_getsram
completes.
>   * XFR_COMPLETE is set when a transfer fails or finishes
occ_worker_getsram.
>   * XFR_CANCELED is set when the transfer's client is released.
>   * XFR_WAITING is set from read() if the transfer isn't complete and
> - * 	NONBLOCKING wasn't specified. Cleared in read() when
transfer completes
> - * 	or fails.
> + *  O_NONBLOCK wasn't specified. Cleared in read() when transfer
completes or
> + *  fails.
>   */
>  enum {
>  	XFR_IN_PROGRESS,
> @@ -89,9 +89,9 @@ struct occ_xfr {
>   * client flags
>   *
>   * CLIENT_NONBLOCKING is set during open() if the file was opened
with the
> - * 	O_NONBLOCKING flag.
> + *  O_NONBLOCK flag.
>   * CLIENT_XFR_PENDING is set during write() and cleared when all
data has been
> - * 	read.
> + *  read.
>   */
>  enum {
>  	CLIENT_NONBLOCKING,
> @@ -101,7 +101,7 @@ enum {
>  struct occ_client {
>  	struct occ *occ;
>  	struct occ_xfr xfr;
> -	spinlock_t lock;
> +	spinlock_t lock;		/* lock access to the client
state */
>  	wait_queue_head_t wait;
>  	size_t read_offset;
>  	unsigned long flags;
> @@ -273,10 +273,15 @@ static ssize_t occ_write_common(struct
occ_client *client,
>  		goto done;
>  	}
>  
> -	/* clear out the transfer */
> -	memset(xfr, 0, sizeof(*xfr));
> -	xfr->buf[0] = 1;
> +	memset(xfr, 0, sizeof(*xfr));	/* clear out the
transfer */
> +	xfr->buf[0] = 1;		/* occ sequence number */
>  
> +	/*
> +	 * Assume user data follows the occ command format.
> +	 * byte 0: command type
> +	 * bytes 1-2: data length (msb first)
> +	 * bytes 3-n: data
> +	 */
>  	if (ubuf) {
>  		if (copy_from_user(&xfr->buf[1], ubuf, len)) {
>  			rc = -EFAULT;
> @@ -354,7 +359,7 @@ static int occ_release_common(struct occ_client
*client)
>  		return 0;
>  	}
>  
> -	/* operation is in progress; let worker clean up*/
> +	/* operation is in progress; let worker clean up */
>  	spin_unlock_irq(&occ->list_lock);
>  	spin_unlock_irq(&client->lock);
>  	return 0;
> @@ -419,9 +424,13 @@ static int occ_getsram(struct device *sbefifo,
u32 address, u8 *data,
>  	int rc;
>  	u8 *resp;
>  	__be32 buf[5];
> -	u32 data_len = ((len + 7) / 8) * 8;
> +	u32 data_len = ((len + 7) / 8) * 8;	/* must be
multiples of 8 B */
>  	struct sbefifo_client *client;
>  
> +	/*
> +	 * Magic sequence to do SBE getsram command. SBE will fetch
data from
> +	 * specified SRAM address.
> +	 */
>  	buf[0] = cpu_to_be32(0x5);
>  	buf[1] = cpu_to_be32(0xa403);
>  	buf[2] = cpu_to_be32(1);
> @@ -470,7 +479,7 @@ static int occ_putsram(struct device *sbefifo,
u32 address, u8 *data,
>  {
>  	int rc;
>  	__be32 *buf;
> -	u32 data_len = ((len + 7) / 8) * 8;
> +	u32 data_len = ((len + 7) / 8) * 8;	/* must be
multiples of 8 B */
>  	size_t cmd_len = data_len + 20;
>  	struct sbefifo_client *client;
>  
> @@ -478,6 +487,10 @@ static int occ_putsram(struct device *sbefifo,
u32 address, u8 *data,
>  	if (!buf)
>  		return -ENOMEM;
>  
> +	/*
> +	 * Magic sequence to do SBE putsram command. SBE will
transfer
> +	 * data to specified SRAM address.
> +	 */
>  	buf[0] = cpu_to_be32(0x5 + (data_len / 4));
>  	buf[1] = cpu_to_be32(0xa404);
>  	buf[2] = cpu_to_be32(1);
> @@ -518,11 +531,15 @@ static int occ_trigger_attn(struct device
*sbefifo)
>  	__be32 buf[6];
>  	struct sbefifo_client *client;
>  
> +	/*
> +	 * Magic sequence to do SBE putscom command. SBE will write
8 bytes to
> +	 * specified SCOM address.
> +	 */
>  	buf[0] = cpu_to_be32(0x6);
>  	buf[1] = cpu_to_be32(0xa202);
>  	buf[2] = 0;
>  	buf[3] = cpu_to_be32(0x6D035);
> -	buf[4] = cpu_to_be32(0x20010000);
> +	buf[4] = cpu_to_be32(0x20010000);	/* trigger occ
attention */
>  	buf[5] = 0;
>  
>  	client = sbefifo_drv_open(sbefifo, 0);
> @@ -573,6 +590,7 @@ static void occ_worker(struct work_struct *work)
>  	spin_unlock_irq(&occ->list_lock);
>  	mutex_lock(&occ->occ_lock);
>  
> +	/* write occ command */
>  	rc = occ_putsram(sbefifo, 0xFFFBE000, xfr->buf,
>  			 xfr->cmd_data_length);
>  	if (rc)
> @@ -582,6 +600,7 @@ static void occ_worker(struct work_struct *work)
>  	if (rc)
>  		goto done;
>  
> +	/* read occ response */
>  	rc = occ_getsram(sbefifo, 0xFFFBF000, xfr->buf, 8);
>  	if (rc)
>  		goto done;
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: This is a digitally signed message part
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20171006/d4a49927/attachment.sig>