staging: unisys: cleanup and align iochannel.h comments
authorErik Arfvidson <erik.arfvidson@unisys.com>
Tue, 5 May 2015 22:36:47 +0000 (18:36 -0400)
committerGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Fri, 8 May 2015 13:27:28 +0000 (15:27 +0200)
This patch reorganizes, aligns, and corrects grammar mistakes on
comments.

Signed-off-by: Erik Arfvidson <erik.arfvidson@unisys.com>
Signed-off-by: Benjamin Romer <benjamin.romer@unisys.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
drivers/staging/unisys/common-spar/include/channels/iochannel.h

index fad7fe9..cbb5875 100644 (file)
@@ -4,29 +4,29 @@
 #define __IOCHANNEL_H__
 
 /*
-* Everything needed for IOPart-GuestPart communication is define in
-* this file.  Note: Everything is OS-independent because this file is
-* used by Windows, Linux and possible EFI drivers.  */
+ * Everything needed for IOPart-GuestPart communication is define in
+ * this file.  Note: Everything is OS-independent because this file is
+ * used by Windows, Linux and possible EFI drivers.  */
 
 /*
-* Communication flow between the IOPart and GuestPart uses the channel headers
-* 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
-* states due to the following rules:
-*
-*      1.  IOPart is only the only partition allowed to change from UNIT
-*      2.  IOPart is only the only partition allowed to change from
-             CHANNEL_ATTACHING
-*      3.  GuestPart is only the only partition allowed to change from
-             CHANNEL_ATTACHED
-*
-* The state changes are the following: IOPart sees the channel is in UNINIT,
-*        UNINIT -> CHANNEL_ATTACHING (performed only by IOPart)
-*        CHANNEL_ATTACHING -> CHANNEL_ATTACHED (performed only by IOPart)
-*        CHANNEL_ATTACHED -> CHANNEL_OPENED (performed only by GuestPart)
-*/
+ * Communication flow between the IOPart and GuestPart uses the channel headers
+ * 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
+ * states due to the following rules:
+ *
+ *      1.  IOPart is only the only partition allowed to change from UNIT
+ *      2.  IOPart is only the only partition allowed to change from
+ *             CHANNEL_ATTACHING
+ *      3.  GuestPart is only the only partition allowed to change from
+ *             CHANNEL_ATTACHED
+ *
+ * The state changes are the following: IOPart sees the channel is in UNINIT,
+ *        UNINIT -> CHANNEL_ATTACHING (performed only by IOPart)
+ *        CHANNEL_ATTACHING -> CHANNEL_ATTACHED (performed only by IOPart)
+ *        CHANNEL_ATTACHED -> CHANNEL_OPENED (performed only by GuestPart)
+ */
 
 #include <linux/uuid.h>
 
 #include "vbuschannel.h"
 #undef _ULTRA_CONTROLVM_CHANNEL_INLINE_
 #include "channel.h"
-
-/*
- * CHANNEL Guids
- */
-
 #include "channel_guid.h"
 
 #define ULTRA_VHBA_CHANNEL_PROTOCOL_SIGNATURE ULTRA_CHANNEL_PROTOCOL_SIGNATURE
        ULTRA_CHANNEL_PROTOCOL_SIGNATURE
 
 /* 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
-* increment this. */
+ * 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
+ * increment this.
+ */
 #define ULTRA_VHBA_CHANNEL_PROTOCOL_VERSIONID 2
 #define ULTRA_VNIC_CHANNEL_PROTOCOL_VERSIONID 2
 #define ULTRA_VSWITCH_CHANNEL_PROTOCOL_VERSIONID 1
                                   ULTRA_VNIC_CHANNEL_PROTOCOL_SIGNATURE))
 
 /*
-* Everything necessary to handle SCSI & NIC traffic between Guest Partition and
-* IO Partition is defined below.  */
+ * Everything necessary to handle SCSI & NIC traffic between Guest Partition and
+ * IO Partition is defined below.
+ */
 
 /*
-* Defines and enums.
-*/
+ * Defines and enums.
+ */
 
 #define MINNUM(a, b) (((a) < (b)) ? (a) : (b))
 #define MAXNUM(a, b) (((a) > (b)) ? (a) : (b))
 
 /* these define the two queues per data channel between iopart and
- * ioguestparts */
+ * ioguestparts
+ */
 #define IOCHAN_TO_IOPART 0 /* used by ioguestpart to 'insert' signals to
                            * iopart */
 
@@ -120,7 +118,7 @@ enum net_types {
        /* uisnic -> virtnic */
        NET_MACADDR,            /* indicates the client has requested to update
                                 * its MAC addr */
-       NET_MACADDR_ACK,        /* MAC address  */
+       NET_MACADDR_ACK,        /* MAC address */
 
 };
 
@@ -149,8 +147,7 @@ enum vdisk_mgmt_types {
        VDISK_MGMT_RELEASE,
 };
 
-/*
- * structs with pragma pack  */
+/* structs with pragma pack  */
 
 /* ///////////// BEGIN PRAGMA PACK PUSH 1 ///////////////////////// */
 /* ///////////// ONLY STRUCT TYPE SHOULD BE BELOW */
@@ -221,17 +218,19 @@ struct uiscmdrsp_scsi {
        /* see that struct for details. */
        void *vdisk; /* contains pointer to the vdisk so that we can clean up
                      * when the IO completes. */
-       int no_disk_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 */
-       /* scsi.linuxstat is SAM_STAT_GOOD */
-       /* That is, there is NO error. */
+       int no_disk_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
+        * scsi.linuxstat is SAM_STAT_GOOD
+        * That is, there is NO error.
+        */
 };
 
-/*
-* Defines to support sending correct inquiry result when no disk is
-* configured.  */
+/* Defines to support sending correct inquiry result when no disk is
+ * configured.
+ */
 
 /* From SCSI SPC2 -
  *
@@ -245,20 +244,21 @@ struct uiscmdrsp_scsi {
  */
 
 #define DEV_NOT_CAPABLE 0x7f   /* peripheral qualifier of 0x3  */
-    /* peripheral type of 0x1f */
-    /* specifies no device but target present */
+                               /* 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_HISUPPORT 0x10     /* HiSup = 1; shows support for report luns */
-    /* must be returned for lun 0. */
+                               /* 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
-* inquiry result. */
+ * 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
+ * inquiry result.
+ */
 #define NO_DISK_INQUIRY_RESULT_LEN 36
 
 #define MIN_INQUIRY_RESULT_LEN 5 /* we need at least 5 bytes minimum for inquiry
@@ -309,21 +309,21 @@ struct uiscmdrsp_scsi {
        } while (0)
 
 /*
-* Struct & Defines to support sense information.
-*/
+ * Struct & Defines to support sense information.
+ */
 
 /* 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:
-* ErrorCode = 0x70             indicates current error
-* Valid = 1                    indicates sense info is valid
-* SenseKey                     contains sense key as defined by SCSI specs.
-* AdditionalSenseCode          contains sense key as defined by SCSI specs.
-* AdditionalSenseCodeQualifier contains qualifier to sense code as defined by
-                             scsi docs.
-* AdditionalSenseLength                contains will be sizeof(sense_data)-8=10.
-*/
+ * initialized in exactly the manner that is recommended in Windows (hence the
+ * odd values).
+ * When set, these fields will have the following values:
+ * ErrorCode = 0x70            indicates current error
+ * Valid = 1                   indicates sense info is valid
+ * SenseKey                    contains sense key as defined by SCSI specs.
+ * AdditionalSenseCode         contains sense key as defined by SCSI specs.
+ * AdditionalSenseCodeQualifier        contains qualifier to sense code as defined by
+ *                             scsi docs.
+ * AdditionalSenseLength       contains will be sizeof(sense_data)-8=10.
+ */
 struct sense_data {
        u8 errorcode:7;
        u8 valid:1;
@@ -375,24 +375,25 @@ struct net_pkt_xmtdone {
 };
 
 /* 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
-* which can only cover page_size. */
+ * 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
+ * which can only cover page_size.
+ */
 #define RCVPOST_BUF_SIZE 4032
 #define MAX_NET_RCV_CHAIN \
        ((ETH_MAX_MTU+ETH_HEADER_SIZE + RCVPOST_BUF_SIZE-1) / RCVPOST_BUF_SIZE)
 
 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 */
+            * ethernet header len - we are choosing 2K because it is guaranteed
+            * to be describable */
            struct phys_info frag;      /* physical page information for the
                                         * single fragment 2K rcv buf */
            u64 unique_num;             /* This is used to make sure that
                                         * receive posts are returned to  */
-           /* the Adapter which sent them origonally. */
+           /* the Adapter which we sent them originally. */
 };
 
 struct net_pkt_rcv {
@@ -424,14 +425,14 @@ struct uiscmdrsp_net {
        enum net_types type;
        void *buf;
        union {
-               struct net_pkt_xmt xmt; /* used for NET_XMIT */
+               struct net_pkt_xmt xmt;         /* used for NET_XMIT */
                struct net_pkt_xmtdone xmtdone; /* used for NET_XMIT_DONE */
                struct net_pkt_rcvpost rcvpost; /* used for NET_RCV_POST */
-               struct net_pkt_rcv rcv; /* used for NET_RCV */
+               struct net_pkt_rcv rcv;         /* used for NET_RCV */
                struct net_pkt_enbdis enbdis;   /* used for NET_RCV_ENBDIS, */
-               /* NET_RCV_ENBDIS_ACK,  */
-               /* NET_RCV_PROMSIC, */
-               /* and NET_CONNECT_STATUS */
+                                               /* NET_RCV_ENBDIS_ACK,  */
+                                               /* NET_RCV_PROMSIC, */
+                                               /* and NET_CONNECT_STATUS */
                struct net_pkt_macaddr macaddr;
        };
 };
@@ -446,24 +447,27 @@ struct uiscmdrsp_scsitaskmgmt {
        void *scsicmd;
 
            /* This is some 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. */
+            * Its value is preserved by iopart & returned as is in the task
+            * mgmt rsp.
+            */
        void *notify;
 
-           /* 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.
            * For windows guests, this is a pointer to a location that a waiting
            * thread is testing 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. */
+           * as is in the task mgmt rsp.
+           */
        void *notifyresult;
 
            /* 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
-           * the task mgmt rsp. */
+            * taskmgmt command (result field) is to saved off when the response
+            * is handled.  Its value is preserved by iopart & returned as is in
+            * the task mgmt rsp.
+            */
        char result;
 
            /* result of taskmgmt command - set by IOPart - values are: */
@@ -474,14 +478,14 @@ struct uiscmdrsp_scsitaskmgmt {
  * Guest */
 /* Note that the vHba pointer is not used by the Client/Guest side. */
 struct uiscmdrsp_disknotify {
-       u8 add;         /* 0-remove, 1-add */
+       u8 add;                 /* 0-remove, 1-add */
        void *v_hba;            /* Pointer to vhba_info for channel info to
                                 * route msg */
        u32 channel, id, lun;   /* SCSI Path of Disk to added or removed */
 };
 
 /* The following is used by virthba/vSCSI to send the Acquire/Release commands
-* to the IOVM.  */
+ * to the IOVM. */
 struct uiscmdrsp_vdiskmgmt {
        enum vdisk_mgmt_types vdisktype;
 
@@ -492,24 +496,27 @@ struct uiscmdrsp_vdiskmgmt {
        void *scsicmd;
 
            /* This is some 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. */
+            * Its value is preserved by iopart & returned as is in the task
+            * mgmt rsp.
+            */
        void *notify;
 
            /* 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.
-           * For windows guests, this is a pointer to a location that a waiting
-           * thread is testing 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. */
+            * thread is waiting on to see if the tskmgmt command has completed.
+            * For win32 guests, this is a pointer to a location that a waiting
+            * thread is testing 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.
+            */
        void *notifyresult;
 
            /* 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
-           * the task mgmt rsp. */
+            * taskmgmt command (result field) is to saved off when the response
+            * is handled.  Its value is preserved by iopart & returned as is in
+            * the task mgmt rsp.
+            */
        char result;
 
            /* result of taskmgmt command - set by IOPart - values are: */
@@ -520,7 +527,7 @@ struct uiscmdrsp_vdiskmgmt {
 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
@@ -534,30 +541,31 @@ struct uiscmdrsp {
                struct uiscmdrsp_vdiskmgmt vdiskmgmt;
        };
        void *private_data;     /* used to send the response when the cmd is
-                                * done (scsi & scsittaskmgmt).  */
+                                * done (scsi & scsittaskmgmt). */
        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_prev; /* Used to track active commands */
 };
 
 /* 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. */
+ * 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.
+ */
 struct spar_io_channel_protocol {
        struct channel_header channel_header;
        struct signal_queue_header cmd_q;
        struct signal_queue_header rsp_q;
        union {
                struct {
-                       struct vhba_wwnn wwnn;  /* 8 bytes */
+                       struct vhba_wwnn wwnn;          /* 8 bytes */
                        struct vhba_config_max max;     /* 20 bytes */
-               } vhba;         /* 28 */
+               } vhba;                                 /* total = 28 bytes */
                struct {
                        u8 macaddr[MAX_MACADDR_LEN];    /* 6 bytes */
-                       u32 num_rcv_bufs;       /* 4 */
-                       u32 mtu;        /* 4 */
-                       uuid_le zone_uuid;      /* 16 */
-               } vnic;         /* total     30 */
+                       u32 num_rcv_bufs;               /* 4 bytes */
+                       u32 mtu;                        /* 4 bytes */
+                       uuid_le zone_uuid;              /* 16 bytes */
+               } vnic;                                 /* total = 30 bytes */
        };
 
 #define MAX_CLIENTSTRING_LEN 1024
@@ -569,8 +577,8 @@ struct spar_io_channel_protocol {
 /* ///////////// END PRAGMA PACK PUSH 1 /////////////////////////// */
 
 /*
-* 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))
@@ -579,9 +587,9 @@ struct spar_io_channel_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.
-*/
+ * INLINE function for expanding a guest's pfn-off-size into multiple 4K page
+ * pfn-off-size entires.
+ */
 
 /* we deal with 4K page sizes when we it comes to passing page information
  * between */