From 209e3500ef7bf9414eb21c86027712d57229c6b8 Mon Sep 17 00:00:00 2001 From: Erik Arfvidson Date: Mon, 21 Nov 2016 12:15:40 -0500 Subject: [PATCH] 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 Signed-off-by: David Kershner Signed-off-by: Greg Kroah-Hartman --- drivers/staging/unisys/include/iochannel.h | 323 ++++++++++++++++------------- 1 file changed, 176 insertions(+), 147 deletions(-) diff --git a/drivers/staging/unisys/include/iochannel.h b/drivers/staging/unisys/include/iochannel.h index cba4433..eeca16e 100644 --- a/drivers/staging/unisys/include/iochannel.h +++ b/drivers/staging/unisys/include/iochannel.h @@ -1,20 +1,20 @@ -/* Copyright (C) 2010 - 2013 UNISYS CORPORATION */ +/* Copyright (C) 2010 - 2016 UNISYS CORPORATION */ /* All rights reserved. */ #ifndef __IOCHANNEL_H__ #define __IOCHANNEL_H__ /* * Everything needed for IOPart-GuestPart communication is define in - * this file. Note: Everything is OS-independent because this file is + * 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: + * 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 - * 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 +/* + * 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. */ #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; @@ -156,9 +160,9 @@ struct guest_phys_info { #define GPI_ENTRIES_PER_PAGE (PAGE_SIZE / sizeof(struct guest_phys_info)) struct uisscsi_dest { - u32 channel; /* channel == bus number */ - u32 id; /* id == target number */ - u32 lun; /* lun == logical unit number */ + u32 channel; /* channel == bus number */ + u32 id; /* id == target number */ + u32 lun; /* lun == logical unit number */ } __packed; struct vhba_wwnn { @@ -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 */ @@ -189,23 +194,24 @@ struct uiscmdrsp_scsi { * information for each * fragment */ - enum dma_data_direction data_dir; /* direction of the data, if any */ + enum dma_data_direction data_dir; /* direction of the data, if any */ 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 @@ -250,11 +265,12 @@ struct uiscmdrsp_scsi { #define MIN_INQUIRY_RESULT_LEN 5 /* 5 bytes minimum for inquiry result */ /* SCSI device version for no disk inquiry result */ -#define SCSI_SPC2_VER 4 /* indicates SCSI SPC2 (SPC3 is 5) */ +#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 @@ -311,14 +328,15 @@ struct net_pkt_xmt { } __packed; struct net_pkt_xmtdone { - u32 xmt_done_result; /* result of NET_XMIT */ + 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 - */ - 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. */ + /* 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. + */ + u64 unique_num; + } __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. */ - void *rcvbuf[MAX_NET_RCV_CHAIN]; /* list of chained rcvbufs */ - /* each entry is a receive buffer provided by NET_RCV_POST. */ + u32 rcv_done_len; /* length of received data */ + + /* + * 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. */ /* NOTE: first rcvbuf in the chain will also be provided in net.buf. */ u64 unique_num; u32 rcvs_dropped_delta; @@ -353,12 +383,12 @@ struct net_pkt_rcv { struct net_pkt_enbdis { void *context; - u16 enable; /* 1 = enable, 0 = disable */ + u16 enable; /* 1 = enable, 0 = disable */ } __packed; struct net_pkt_macaddr { void *context; - u8 macaddr[MAX_MACADDR_LEN]; /* 6 bytes */ + u8 macaddr[MAX_MACADDR_LEN]; /* 6 bytes */ } __packed; /* cmd rsp packet used for VNIC network traffic */ @@ -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 */ + /* + * 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 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. - */ + /* + * 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. It's value is preserved by iopart and returned + * as in the task mgmt rsp. + */ u64 notify_handle; - /* 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. - */ + /* + * 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; - /* 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. - */ + /* 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 */ + /* + * 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 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. - */ + /* + * 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. It's value is preserved by iopart and returned + * as in the task mgmt rsp. + */ u64 notify_handle; - /* 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. - */ + /* + * 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; - /* 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. - */ + /* 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,31 +544,23 @@ 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) - */ -static inline u16 +/* 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) @@ -567,4 +596,4 @@ add_physinfo_entries(u64 inp_pfn, u16 inp_off, u32 inp_len, u16 index, return index + i; } -#endif /* __IOCHANNEL_H__ */ +#endif /* __IOCHANNEL_H__ */ -- 2.7.4