staging: unisys: include: fixed iochannel.h comments

The purpose of this patch is to add style consistency and beautify the
entire file.

Grammar:
Uppercased beginning of new sentences/paragraphs
Missing ' and .
Fixed several comments using prefix phrase "as is in" to "as in"
Standard Grammar

Comments:
Fixed comments to follow the multiline styling
All comments are now either same line or above variable/definitions
Removed nested slash-star comments
Removed a random comment left by accident
Aligned star comments
Signed-off-by: Erik Arfvidson <erik.arfvidson@unisys.com>
Signed-off-by: David Kershner <david.kershner@unisys.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

drivers/staging/unisys/include/iochannel.h

-/* Copyright (C) 2010 - 2013 UNISYS CORPORATION */
+/* Copyright (C) 2010 - 2016 UNISYS CORPORATION */
 /* All rights reserved. */
 #ifndef __IOCHANNEL_H__
 #define __IOCHANNEL_H__
@@ -14,7 +14,7 @@
  * channel state. The following states are currently being used:
  *       UNINIT(All Zeroes), CHANNEL_ATTACHING, CHANNEL_ATTACHED, CHANNEL_OPENED
  *
- * additional states will be used later.  No locking is needed to switch between
+ * Additional states will be used later. No locking is needed to switch between
  * states due to the following rules:
  *
  *      1.  IOPart is only the only partition allowed to change from UNIT
@@ -39,10 +39,11 @@
 #define ULTRA_VSWITCH_CHANNEL_PROTOCOL_SIGNATURE \
 	ULTRA_CHANNEL_PROTOCOL_SIGNATURE
 
-/* Must increment these whenever you insert or delete fields within this channel
+/*
+ * Must increment these whenever you insert or delete fields within this channel
  * struct. Also increment whenever you change the meaning of fields within this
  * channel struct so as to break pre-existing software. Note that you can
- * usually add fields to the END of the channel struct withOUT needing to
+ * usually add fields to the END of the channel struct without needing to
  * increment this.
  */
 #define ULTRA_VHBA_CHANNEL_PROTOCOL_VERSIONID 2
@@ -70,46 +71,49 @@
 #define MINNUM(a, b) (((a) < (b)) ? (a) : (b))
 #define MAXNUM(a, b) (((a) > (b)) ? (a) : (b))
 
-/* define the two queues per data channel between iopart and ioguestparts */
-/* used by ioguestpart to 'insert' signals to iopart */
+/* Define the two queues per data channel between iopart and ioguestparts. */
+/* Used by ioguestpart to 'insert' signals to iopart. */
 #define IOCHAN_TO_IOPART 0
-/* used by ioguestpart to 'remove' signals from iopart, same previous queue */
+/* Used by ioguestpart to 'remove' signals from iopart, same previous queue. */
 #define IOCHAN_FROM_IOPART 1
 
-/* size of cdb - i.e., scsi cmnd */
+/* Size of cdb - i.e., SCSI cmnd */
 #define MAX_CMND_SIZE 16
 
 #define MAX_SENSE_SIZE 64
 
 #define MAX_PHYS_INFO 64
 
-/* various types of network packets that can be sent in cmdrsp */
+/* Various types of network packets that can be sent in cmdrsp. */
 enum net_types {
-	NET_RCV_POST = 0,	/* submit buffer to hold receiving
+	NET_RCV_POST = 0,	/*
+				 * Submit buffer to hold receiving
 				 * incoming packet
 				 */
-	/* virtnic -> uisnic */
+	/* visornic -> uisnic */
 	NET_RCV,		/* incoming packet received */
 	/* uisnic -> virtpci */
 	NET_XMIT,		/* for outgoing net packets */
-	/* virtnic -> uisnic */
+	/* visornic -> uisnic */
 	NET_XMIT_DONE,		/* outgoing packet xmitted */
 	/* uisnic -> virtpci */
 	NET_RCV_ENBDIS,		/* enable/disable packet reception */
-	/* virtnic -> uisnic */
+	/* visornic -> uisnic */
 	NET_RCV_ENBDIS_ACK,	/* acknowledge enable/disable packet */
 				/* reception */
-	/* uisnic -> virtnic */
+	/* uisnic -> visornic */
 	NET_RCV_PROMISC,	/* enable/disable promiscuous mode */
-	/* virtnic -> uisnic */
-	NET_CONNECT_STATUS,	/* indicate the loss or restoration of a network
+	/* visornic -> uisnic */
+	NET_CONNECT_STATUS,	/*
+				 * indicate the loss or restoration of a network
 				 * connection
 				 */
-	/* uisnic -> virtnic */
-	NET_MACADDR,		/* indicates the client has requested to update
-				 * its MAC addr
+	/* uisnic -> visornic */
+	NET_MACADDR,		/*
+				 * Indicates the client has requested to update
+				 * it's MAC address
 				 */
-	NET_MACADDR_ACK,	/* MAC address */
+	NET_MACADDR_ACK,	/* MAC address acknowledge */
 
 };
 
@@ -122,9 +126,9 @@ enum net_types {
 
 #ifndef MAX_MACADDR_LEN
 #define MAX_MACADDR_LEN 6	/* number of bytes in MAC address */
-#endif				/* MAX_MACADDR_LEN */
+#endif
 
-/* various types of scsi task mgmt commands  */
+/* Various types of scsi task mgmt commands. */
 enum task_mgmt_types {
 	TASK_MGMT_ABORT_TASK = 1,
 	TASK_MGMT_BUS_RESET,
@@ -132,7 +136,7 @@ enum task_mgmt_types {
 	TASK_MGMT_TARGET_RESET,
 };
 
-/* various types of vdisk mgmt commands  */
+/* Various types of vdisk mgmt commands. */
 enum vdisk_mgmt_types {
 	VDISK_MGMT_ACQUIRE = 1,
 	VDISK_MGMT_RELEASE,
@@ -146,7 +150,7 @@ struct phys_info {
 
 #define MIN_NUMSIGNALS 64
 
-/* structs with pragma pack  */
+/* Structs with pragma pack. */
 
 struct guest_phys_info {
 	u64 address;
@@ -166,7 +170,8 @@ struct vhba_wwnn {
 	u32 wwnn2;
 } __packed;
 
-/* WARNING: Values stired in this structure must contain maximum counts (not
+/*
+ * WARNING: Values stired in this structure must contain maximum counts (not
  * maximum values).
  */
 struct vhba_config_max {/* 20 bytes */
@@ -193,19 +198,20 @@ struct uiscmdrsp_scsi {
 	struct uisscsi_dest vdest;	/* identifies the virtual hba, id, */
 					/* channel, lun to which cmd was sent */
 
-	/* Needed to queue the rsp back to cmd originator */
-	int linuxstat;		/* original Linux status used by linux vdisk */
+	/* Needed to queue the rsp back to cmd originator. */
+	int linuxstat;		/* original Linux status used by Linux vdisk */
 	u8 scsistat;		/* the scsi status */
 	u8 addlstat;		/* non-scsi status */
 #define ADDL_SEL_TIMEOUT	4
 
-	/* the following fields are need to determine the result of command */
+	/* The following fields are need to determine the result of command. */
 	 u8 sensebuf[MAX_SENSE_SIZE];	/* sense info in case cmd failed; */
-	/* it holds the sense_data struct; */
-	/* see that struct for details. */
-	void *vdisk; /* pointer to the vdisk to clean up when IO completes. */
+	/* sensebuf holds the sense_data struct; */
+	/* See sense_data struct for more details. */
+	void *vdisk; /* Pointer to the vdisk to clean up when IO completes. */
 	int no_disk_result;
-	/* used to return no disk inquiry result
+	/*
+	 * Used to return no disk inquiry result
 	 * when no_disk_result is set to 1,
 	 * scsi.scsistat is SAM_STAT_GOOD
 	 * scsi.addlstat is 0
@@ -214,35 +220,44 @@ struct uiscmdrsp_scsi {
 	 */
 } __packed;
 
-/* Defines to support sending correct inquiry result when no disk is
+/*
+ * Defines to support sending correct inquiry result when no disk is
  * configured.
  */
 
-/* From SCSI SPC2 -
+/*
+ * From SCSI SPC2 -
  *
  * If the target is not capable of supporting a device on this logical unit, the
  * device server shall set this field to 7Fh (PERIPHERAL QUALIFIER set to 011b
  * and PERIPHERAL DEVICE TYPE set to 1Fh).
  *
- *The device server is capable of supporting the specified peripheral device
- *type on this logical unit. However, the physical device is not currently
- *connected to this logical unit.
+ * The device server is capable of supporting the specified peripheral device
+ * type on this logical unit. However, the physical device is not currently
+ * connected to this logical unit.
  */
 
-#define DEV_NOT_CAPABLE 0x7f	/* peripheral qualifier of 0x3  */
-				/* peripheral type of 0x1f */
-				/* specifies no device but target present */
+#define DEV_NOT_CAPABLE 0x7f	/*
+				 * peripheral qualifier of 0x3
+				 * peripheral type of 0x1f
+				 * specifies no device but target present
+				 */
 
-#define DEV_DISK_CAPABLE_NOT_PRESENT 0x20 /* peripheral qualifier of 0x1 */
-    /* peripheral type of 0 - disk */
-    /* specifies device capable, but not present */
+#define DEV_DISK_CAPABLE_NOT_PRESENT 0x20	/* peripheral qualifier of 0x1
+						 * peripheral type of 0 - disk
+						 * Specifies device capable, but
+						 * not present
+						 */
 
-#define DEV_HISUPPORT 0x10	/* HiSup = 1; shows support for report luns */
-				/* must be returned for lun 0. */
+#define DEV_HISUPPORT 0x10	/*
+				 * HiSup = 1; shows support for report luns
+				 * must be returned for lun 0.
+				 */
 
-/* NOTE: Linux code assumes inquiry contains 36 bytes. Without checking length
- * in buf[4] some linux code accesses bytes beyond 5 to retrieve vendor, product
- * & revision.  Yikes! So let us always send back 36 bytes, the minimum for
+/*
+ * NOTE: Linux code assumes inquiry contains 36 bytes. Without checking length
+ * in buf[4] some Linux code accesses bytes beyond 5 to retrieve vendor, product
+ * and revision. Yikes! So let us always send back 36 bytes, the minimum for
  * inquiry result.
  */
 #define NO_DISK_INQUIRY_RESULT_LEN 36
@@ -252,9 +267,10 @@ struct uiscmdrsp_scsi {
 /* SCSI device version for no disk inquiry result */
 #define SCSI_SPC2_VER 4	/* indicates SCSI SPC2 (SPC3 is 5) */
 
-/* Struct & Defines to support sense information. */
+/* Struct and Defines to support sense information. */
 
-/* The following struct is returned in sensebuf field in uiscmdrsp_scsi.  It is
+/*
+ * The following struct is returned in sensebuf field in uiscmdrsp_scsi. It is
  * initialized in exactly the manner that is recommended in Windows (hence the
  * odd values).
  * When set, these fields will have the following values:
@@ -290,7 +306,7 @@ struct net_pkt_xmt {
 	struct phys_info frags[MAX_PHYS_INFO];	/* physical page information */
 	char ethhdr[ETH_HEADER_SIZE];	/* the ethernet header  */
 	struct {
-		/* these are needed for csum at uisnic end */
+		/* These are needed for csum at uisnic end */
 		u8 valid;	/* 1 = struct is valid - else ignore */
 		u8 hrawoffv;	/* 1 = hwrafoff is valid */
 		u8 nhrawoffv;	/* 1 = nhwrafoff is valid */
@@ -302,7 +318,8 @@ struct net_pkt_xmt {
 		/* nhrawoff points to the start of the NETWORK LAYER HEADER */
 	} lincsum;
 
-	    /* **** NOTE ****
+	    /*
+	     * NOTE:
 	     * The full packet is described in frags but the ethernet header is
 	     * separately kept in ethhdr so that uisnic doesn't have "MAP" the
 	     * guest memory to get to the header. uisnic needs ethhdr to
@@ -314,11 +331,12 @@ struct net_pkt_xmtdone {
 	u32 xmt_done_result; /* result of NET_XMIT */
 } __packed;
 
-/* RCVPOST_BUF_SIZe must be at most page_size(4096) - cache_line_size (64) The
+/*
+ * RCVPOST_BUF_SIZE must be at most page_size(4096) - cache_line_size (64) The
  * reason is because dev_skb_alloc which is used to generate RCV_POST skbs in
- * virtnic requires that there is "overhead" in the buffer, and pads 16 bytes. I
- * prefer to use 1 full cache line size for "overhead" so that transfers are
- * better.  IOVM requires that a buffer be represented by 1 phys_info structure
+ * visornic requires that there is "overhead" in the buffer, and pads 16 bytes.
+ * Use 1 full cache line size for "overhead" so that transfers are optimized.
+ * IOVM requires that a buffer be represented by 1 phys_info structure
  * which can only cover page_size.
  */
 #define RCVPOST_BUF_SIZE 4032
@@ -326,26 +344,38 @@ struct net_pkt_xmtdone {
 	((ETH_MAX_MTU + ETH_HEADER_SIZE + RCVPOST_BUF_SIZE - 1) \
 	/ RCVPOST_BUF_SIZE)
 
+/*
+ * rcv buf size must be large enough to include ethernet data len + ethernet
+ * header len - we are choosing 2K because it is guaranteed to be describable.
+ */
 struct net_pkt_rcvpost {
-	    /* rcv buf size must be large enough to include ethernet data len +
-	     * ethernet header len - we are choosing 2K because it is guaranteed
-	     * to be describable
+	/* Physical page information for the single fragment 2K rcv buf */
+	struct phys_info frag;
+
+	/*
+	 * Ensures that receive posts are returned to the adapter which we sent
+	 * them from originally.
 	 */
-	    struct phys_info frag;	/* physical page information for the */
-					/* single fragment 2K rcv buf */
 	u64 unique_num;
-	    /* unique_num ensure that receive posts are returned to */
-	    /* the Adapter which we sent them originally. */
+
 } __packed;
 
+/*
+ * The number of rcvbuf that can be chained is based on max mtu and size of each
+ * rcvbuf.
+ */
 struct net_pkt_rcv {
-	/* the number of receive buffers that can be chained  */
-	/* is based on max mtu and size of each rcv buf */
 	u32 rcv_done_len; /* length of received data */
-	u8 numrcvbufs;		/* number of receive buffers that contain the */
-	/* incoming data; guest end MUST chain these together. */
+
+	/*
+	 * numrcvbufs: contain the incoming data; guest side MUST chain these
+	 * together.
+	 */
+	u8 numrcvbufs;
+
 	void *rcvbuf[MAX_NET_RCV_CHAIN]; /* list of chained rcvbufs */
-	/* each entry is a receive buffer provided by NET_RCV_POST. */
+
+	/* Each entry is a receive buffer provided by NET_RCV_POST. */
 	/* NOTE: first rcvbuf in the chain will also be provided in net.buf. */
 	u64 unique_num;
 	u32 rcvs_dropped_delta;
@@ -379,41 +409,44 @@ struct uiscmdrsp_net {
 } __packed;
 
 struct uiscmdrsp_scsitaskmgmt {
+	/* The type of task. */
 	enum task_mgmt_types tasktype;
 
-	    /* the type of task */
+	/* The vdisk for which this task mgmt is generated. */
 	struct uisscsi_dest vdest;
 
-	    /* the vdisk for which this task mgmt is generated */
-	u64 handle;
-
-	    /* This is a handle that the guest has saved off for its own use.
-	     * Its value is preserved by iopart & returned as is in the task
+	/*
+	 * This is a handle that the guest has saved off for its own use.
+	 * The handle value is preserved by iopart and returned as in task
 	 * mgmt rsp.
 	 */
-	u64 notify_handle;
+	u64 handle;
 
-	   /* For linux guests, this is a pointer to wait_queue_head that a
+	/*
+	 * For Linux guests, this is a pointer to wait_queue_head that a
 	 * thread is waiting on to see if the taskmgmt command has completed.
 	 * When the rsp is received by guest, the thread receiving the
 	 * response uses this to notify the thread waiting for taskmgmt
-	    * command completion.  Its value is preserved by iopart & returned
-	    * as is in the task mgmt rsp.
+	 * command completion. It's value is preserved by iopart and returned
+	 * as in the task mgmt rsp.
 	 */
-	u64 notifyresult_handle;
+	u64 notify_handle;
 
-	    /* this is a handle to location in guest where the result of the
-	     * taskmgmt command (result field) is to saved off when the response
-	     * is handled.  Its value is preserved by iopart & returned as is in
+	/*
+	 * This is a handle to the location in the guest where the result of
+	 * the taskmgmt command (result field) is saved to when the response
+	 * is handled. It's value is preserved by iopart and returned as in
 	 * the task mgmt rsp.
 	 */
+	u64 notifyresult_handle;
+
+	/* Result of taskmgmt command - set by IOPart - values are: */
 	char result;
 
-	    /* result of taskmgmt command - set by IOPart - values are: */
 #define TASK_MGMT_FAILED  0
 } __packed;
 
-/* Used by uissd to send disk add/remove notifications to Guest */
+/* Used by uissd to send disk add/remove notifications to Guest. */
 /* Note that the vHba pointer is not used by the Client/Guest side. */
 struct uiscmdrsp_disknotify {
 	u8 add;			/* 0-remove, 1-add */
@@ -421,49 +454,52 @@ struct uiscmdrsp_disknotify {
 	u32 channel, id, lun;	/* SCSI Path of Disk to added or removed */
 } __packed;
 
-/* The following is used by virthba/vSCSI to send the Acquire/Release commands
+/*
+ * The following is used by virthba/vSCSI to send the Acquire/Release commands
  * to the IOVM.
  */
 struct uiscmdrsp_vdiskmgmt {
+	/* The type of task */
 	enum vdisk_mgmt_types vdisktype;
 
-	    /* the type of task */
+	/* The vdisk for which this task mgmt is generated */
 	struct uisscsi_dest vdest;
 
-	    /* the vdisk for which this task mgmt is generated */
-	u64 handle;
-
-	    /* This is a handle that the guest has saved off for its own use.
-	     * Its value is preserved by iopart & returned as is in the task
-	     * mgmt rsp.
+	/*
+	 * This is a handle that the guest has saved off for its own use. It's
+	 * value is preserved by iopart and returned as in the task mgmt rsp.
 	 */
-	u64 notify_handle;
+	u64 handle;
 
-	    /* For linux guests, this is a pointer to wait_queue_head that a
+	/*
+	 * For Linux guests, this is a pointer to wait_queue_head that a
 	 * thread is waiting on to see if the tskmgmt command has completed.
 	 * When the rsp is received by guest, the thread receiving the
 	 * response uses this to notify the thread waiting for taskmgmt
-	     * command completion.  Its value is preserved by iopart & returned
-	     * as is in the task mgmt rsp.
+	 * command completion. It's value is preserved by iopart and returned
+	 * as in the task mgmt rsp.
 	 */
-	u64 notifyresult_handle;
+	u64 notify_handle;
 
-	    /* this is a handle to location in guest where the result of the
-	     * taskmgmt command (result field) is to saved off when the response
-	     * is handled.  Its value is preserved by iopart & returned as is in
+	/*
+	 * Handle to the location in guest where the result of the
+	 * taskmgmt command (result field) is saved to when the response
+	 * is handled. It's value is preserved by iopart and returned as in
 	 * the task mgmt rsp.
 	 */
+	u64 notifyresult_handle;
+
+	/* Result of taskmgmt command - set by IOPart - values are: */
 	char result;
 
-	    /* result of taskmgmt command - set by IOPart - values are: */
 #define VDISK_MGMT_FAILED  0
 } __packed;
 
-/* keeping cmd & rsp info in one structure for now cmd rsp packet for scsi */
+/* Keeping cmd and rsp info in one structure for now cmd rsp packet for SCSI */
 struct uiscmdrsp {
 	char cmdtype;
 
-/* describes what type of information is in the struct */
+/* Describes what type of information is in the struct */
 #define CMD_SCSI_TYPE		1
 #define CMD_NET_TYPE		2
 #define CMD_SCSITASKMGMT_TYPE	3
@@ -476,11 +512,11 @@ struct uiscmdrsp {
 		struct uiscmdrsp_disknotify disknotify;
 		struct uiscmdrsp_vdiskmgmt vdiskmgmt;
 	};
-	void *private_data;	/* send the response when the cmd is */
-				/* done (scsi & scsittaskmgmt). */
+	/* Send the response when the cmd is done (scsi and scsittaskmgmt). */
+	void *private_data;
 	struct uiscmdrsp *next;	/* General Purpose Queue Link */
-	struct uiscmdrsp *activeQ_next;	/* Used to track active commands */
-	struct uiscmdrsp *activeQ_prev;	/* Used to track active commands */
+	struct uiscmdrsp *activeQ_next;	/* Pointer to the nextactive commands */
+	struct uiscmdrsp *activeQ_prev;	/* Pointer to the prevactive commands */
 } __packed;
 
 struct iochannel_vhba {
@@ -493,7 +529,8 @@ struct iochannel_vnic {
 	u32 mtu;			/* 4 bytes */
 	uuid_le zone_uuid;		/* 16 bytes */
 } __packed;
-/* This is just the header of the IO channel.  It is assumed that directly after
+/*
+ * This is just the header of the IO channel. It is assumed that directly after
  * this header there is a large region of memory which contains the command and
  * response queues as specified in cmd_q and rsp_q SIGNAL_QUEUE_HEADERS.
  */
@@ -507,30 +544,22 @@ struct spar_io_channel_protocol {
 	} __packed;
 
 #define MAX_CLIENTSTRING_LEN 1024
-	/* client_string is NULL termimated so holds max -1 bytes */
+	/* client_string is NULL termimated so holds max-1 bytes */
 	 u8 client_string[MAX_CLIENTSTRING_LEN];
 } __packed;
 
-/* INLINE functions for initializing and accessing I/O data channels */
+/* INLINE functions for initializing and accessing I/O data channels. */
 #define SIZEOF_PROTOCOL (COVER(sizeof(struct spar_io_channel_protocol), 64))
 #define SIZEOF_CMDRSP (COVER(sizeof(struct uiscmdrsp), 64))
 
 #define MIN_IO_CHANNEL_SIZE COVER(SIZEOF_PROTOCOL + \
 				  2 * MIN_NUMSIGNALS * SIZEOF_CMDRSP, 4096)
 
-/*
- * INLINE function for expanding a guest's pfn-off-size into multiple 4K page
- * pfn-off-size entires.
- */
-
-/* use 4K page sizes when we it comes to passing page information between */
-/* Guest and IOPartition. */
+/* Use 4K page sizes when passing page info between Guest and IOPartition. */
 #define PI_PAGE_SIZE  0x1000
 #define PI_PAGE_MASK  0x0FFF
 
-/* returns next non-zero index on success or zero on failure (i.e. out of
- * room)
- */
+/* Returns next non-zero index on success or 0 on failure (i.e. out of room). */
 static inline u16
 add_physinfo_entries(u64 inp_pfn, u16 inp_off, u32 inp_len, u16 index,
 		     u16 max_pi_arr_entries, struct phys_info pi_arr[])
@@ -540,7 +569,7 @@ add_physinfo_entries(u64 inp_pfn, u16 inp_off, u32 inp_len, u16 index,
 
 	firstlen = PI_PAGE_SIZE - inp_off;
 	if (inp_len <= firstlen) {
-		/* the input entry spans only one page - add as is */
+		/* The input entry spans only one page - add as is. */
 		if (index >= max_pi_arr_entries)
 			return 0;
 		pi_arr[index].pi_pfn = inp_pfn;
@@ -549,7 +578,7 @@ add_physinfo_entries(u64 inp_pfn, u16 inp_off, u32 inp_len, u16 index,
 		return index + 1;
 	}
 
-	/* this entry spans multiple pages */
+	/* This entry spans multiple pages. */
 	for (len = inp_len, i = 0; len;
 		len -= pi_arr[index + i].pi_len, i++) {
 		if (index + i >= max_pi_arr_entries)