scripts/check_format.sh: catch misaligned comments

Fix up the existing comment blocks misaligned in the first column.

Also add line numbers to the comment checks.

Change-Id: I9d28c365271df36e7013d74cbb02d0023ab4f581
Signed-off-by: Daniel Verkamp <daniel.verkamp@intel.com>

include/spdk/endian.h

@@ -32,9 +32,9 @@
  */
 
 /**
-* \file
+ * \file
-* Endian conversion functions
+ * Endian conversion functions
-*/
+ */
 
 #ifndef SPDK_ENDIAN_H
 #define SPDK_ENDIAN_H

include/spdk/env.h

@@ -65,13 +65,13 @@ struct spdk_env_opts {
 
 /**
  * \brief Initialize the default value of opts
-*/
+ */
 void spdk_env_opts_init(struct spdk_env_opts *opts);
 
 /**
  * \brief Initialize the environment library. This must be called prior to using
  * any other functions in this library.
-*/
+ */
 void spdk_env_init(const struct spdk_env_opts *opts);
 
 /**

include/spdk/event.h

@@ -95,24 +95,24 @@ struct spdk_app_opts {
 
 /**
  * \brief Initialize the default value of opts
-*/
+ */
 void spdk_app_opts_init(struct spdk_app_opts *opts);
 
 /**
  * \brief Initialize an application to use the event framework. This must be called prior to using
  * any other functions in this library.
-*/
+ */
 void spdk_app_init(struct spdk_app_opts *opts);
 
 /**
  * \brief Perform final shutdown operations on an application using the event framework.
-*/
+ */
 int spdk_app_fini(void);
 
 /**
  * \brief Start the framework. Once started, the framework will call start_fn on the master
  * core with the arguments provided. This call will block until \ref spdk_app_stop is called.
-*/
+ */
 int spdk_app_start(spdk_event_fn start_fn, void *arg1, void *arg2);
 
 /**
@@ -125,17 +125,17 @@ void spdk_app_start_shutdown(void);
 /**
  * \brief Stop the framework. This does not wait for all threads to exit. Instead, it kicks off
  * the shutdown process and returns. Once the shutdown process is complete, \ref spdk_app_start will return.
-*/
+ */
 void spdk_app_stop(int rc);
 
 /**
  * \brief Generate a configuration file that corresponds to the current running state.
-*/
+ */
 int spdk_app_get_running_config(char **config_str, char *name);
 
 /**
  * \brief Return the shared memory id for this application.
-*/
+ */
 int spdk_app_get_shm_id(void);
 
 /**

include/spdk/gpt_spec.h

@@ -32,9 +32,9 @@
  */
 
 /**
-* \file
+ * \file
-* GUID Partition Table (GPT) specification definitions
+ * GUID Partition Table (GPT) specification definitions
-*/
+ */
 
 #ifndef SPDK_GPT_SPEC_H
 #define SPDK_GPT_SPEC_H

include/spdk/scsi.h

@@ -184,16 +184,14 @@ struct spdk_scsi_dev {
 };
 
 /**
-
+ * \brief Represents a SCSI LUN.
-\brief Represents a SCSI LUN.
+ *
-
+ * LUN modules will implement the function pointers specifically for the LUN
-LUN modules will implement the function pointers specifically for the LUN
+ * type.  For example, NVMe LUNs will implement scsi_execute to translate
-type.  For example, NVMe LUNs will implement scsi_execute to translate
+ * the SCSI task to an NVMe command and post it to the NVMe controller.
-the SCSI task to an NVMe command and post it to the NVMe controller.
+ * malloc LUNs will implement scsi_execute to translate the SCSI task and
-malloc LUNs will implement scsi_execute to translate the SCSI task and
+ * copy the task's data into or out of the allocated memory buffer.
-copy the task's data into or out of the allocated memory buffer.
+ */
-
-*/
 struct spdk_scsi_lun {
 	/** LUN id for this logical unit. */
 	int id;
@@ -244,21 +242,19 @@ int spdk_scsi_dev_allocate_io_channels(struct spdk_scsi_dev *dev);
 void spdk_scsi_dev_free_io_channels(struct spdk_scsi_dev *dev);
 
 /**
-
+ * \brief Constructs a SCSI device object using the given parameters.
-\brief Constructs a SCSI device object using the given parameters.
+ *
-
+ * \param name Name for the SCSI device.
-\param name Name for the SCSI device.
+ * \param queue_depth Queue depth for the SCSI device.  This queue depth is
-\param queue_depth Queue depth for the SCSI device.  This queue depth is
+ * 		      a combined queue depth for all LUNs in the device.
-		   a combined queue depth for all LUNs in the device.
+ * \param lun_list List of LUN objects for the SCSI device.  Caller is
-\param lun_list List of LUN objects for the SCSI device.  Caller is
+ * 		   responsible for managing the memory containing this list.
-		responsible for managing the memory containing this list.
+ * \param lun_id_list List of LUN IDs for the LUN in this SCSI device.  Caller is
-\param lun_id_list List of LUN IDs for the LUN in this SCSI device.  Caller is
+ *		      responsible for managing the memory containing this list.
-		   responsible for managing the memory containing this list.
+ *		      lun_id_list[x] is the LUN ID for lun_list[x].
-		   lun_id_list[x] is the LUN ID for lun_list[x].
+ * \param num_luns Number of entries in lun_list and lun_id_list.
-\param num_luns Number of entries in lun_list and lun_id_list.
+ * \return The constructed spdk_scsi_dev object.
-\return The constructed spdk_scsi_dev object.
+ */
-
-*/
 struct spdk_scsi_dev *spdk_scsi_dev_construct(const char *name,
 		char *lun_name_list[],
 		int *lun_id_list,

include/spdk_internal/bdev.h

@@ -51,38 +51,37 @@
 #include "spdk/scsi_spec.h"
 
 /** \page block_backend_modules Block Device Backend Modules
-
+ *
-To implement a backend block device driver, a number of functions
+ * To implement a backend block device driver, a number of functions
-dictated by struct spdk_bdev_fn_table must be provided.
+ * dictated by struct spdk_bdev_fn_table must be provided.
-
+ *
-The module should register itself using SPDK_BDEV_MODULE_REGISTER or
+ * The module should register itself using SPDK_BDEV_MODULE_REGISTER or
-SPDK_VBDEV_MODULE_REGISTER to define the parameters for the module.
+ * SPDK_VBDEV_MODULE_REGISTER to define the parameters for the module.
-
+ *
-Use SPDK_BDEV_MODULE_REGISTER for all block backends that are real disks.
+ * Use SPDK_BDEV_MODULE_REGISTER for all block backends that are real disks.
-Any virtual backends such as RAID, partitioning, etc. should use
+ * Any virtual backends such as RAID, partitioning, etc. should use
-SPDK_VBDEV_MODULE_REGISTER.
+ * SPDK_VBDEV_MODULE_REGISTER.
-
+ *
-<hr>
+ * <hr>
-
+ *
-In the module initialization code, the config file sections can be parsed to
+ * In the module initialization code, the config file sections can be parsed to
-acquire custom configuration parameters. For example, if the config file has
+ * acquire custom configuration parameters. For example, if the config file has
-a section such as below:
+ * a section such as below:
-<blockquote><pre>
+ * <blockquote><pre>
-[MyBE]
+ * [MyBE]
-  MyParam 1234
+ * MyParam 1234
-</pre></blockquote>
+ * </pre></blockquote>
-
+ *
-The value can be extracted as the example below:
+ * The value can be extracted as the example below:
-<blockquote><pre>
+ * <blockquote><pre>
-struct spdk_conf_section *sp = spdk_conf_find_section(NULL, "MyBe");
+ * struct spdk_conf_section *sp = spdk_conf_find_section(NULL, "MyBe");
-int my_param = spdk_conf_section_get_intval(sp, "MyParam");
+ * int my_param = spdk_conf_section_get_intval(sp, "MyParam");
-</pre></blockquote>
+ * </pre></blockquote>
-
+ *
-The backend initialization routine also need to create "disks". A virtual
+ * The backend initialization routine also need to create "disks". A virtual
-representation of each LUN must be constructed. Mainly a struct spdk_bdev
+ * representation of each LUN must be constructed. Mainly a struct spdk_bdev
-must be passed to the bdev database via spdk_bdev_register().
+ * must be passed to the bdev database via spdk_bdev_register().
-
+ */
-*/
 
 /** Block device module */
 struct spdk_bdev_module_if {

lib/env_dpdk/pci.c

@@ -128,7 +128,7 @@ spdk_pci_device_attach(struct spdk_pci_enum_ctx *ctx,
 /* Note: You can call spdk_pci_enumerate from more than one thread
  *       simultaneously safely, but you cannot call spdk_pci_enumerate
  *       and rte_eal_pci_probe simultaneously.
-*/
+ */
 int
 spdk_pci_enumerate(struct spdk_pci_enum_ctx *ctx,
 		   spdk_pci_enum_cb enum_cb,

lib/event/reactor.c

@@ -132,10 +132,6 @@ static void spdk_reactor_construct(struct spdk_reactor *w, uint32_t lcore,
 
 static struct spdk_mempool *g_spdk_event_mempool[SPDK_MAX_SOCKET];
 
-/** \file
-
-*/
-
 static struct spdk_reactor *
 spdk_reactor_get(uint32_t lcore)
 {
@@ -221,12 +217,11 @@ spdk_event_queue_run_batch(uint32_t lcore)
 }
 
 /**
-
+ *
-\brief Set current reactor thread name to "reactor <cpu #>".
+ * \brief Set current reactor thread name to "reactor <cpu #>".
-
+ *
-This makes the reactor threads distinguishable in top and gdb.
+ * This makes the reactor threads distinguishable in top and gdb.
-
+ */
-*/
 static void set_reactor_thread_name(uint32_t lcore)
 {
 	char thread_name[16];
@@ -277,26 +272,26 @@ _spdk_poller_unregister_complete(struct spdk_poller *poller)
 }
 
 /**
-
+ *
-\brief This is the main function of the reactor thread.
+ * \brief This is the main function of the reactor thread.
-
+ *
-\code
+ * \code
-
+ *
-while (1)
+ * while (1)
-	if (events to run)
+ *	if (events to run)
-		dequeue and run a batch of events
+ *		dequeue and run a batch of events
-
+ *
-	if (active pollers)
+ *	if (active pollers)
-		run the first poller in the list and move it to the back
+ *		run the first poller in the list and move it to the back
-
+ *
-	if (first timer poller has expired)
+ *	if (first timer poller has expired)
-		run the first timer poller and reinsert it in the timer list
+ *		run the first timer poller and reinsert it in the timer list
-
+ *
-	if (idle for at least SPDK_REACTOR_SPIN_TIME_US)
+ *	if (idle for at least SPDK_REACTOR_SPIN_TIME_US)
-		sleep until next timer poller is scheduled to expire
+ *		sleep until next timer poller is scheduled to expire
-\endcode
+ * \endcode
-
+ *
-*/
+ */
 static int
 _spdk_reactor_run(void *arg)
 {

lib/iscsi/conn.c

@@ -292,21 +292,19 @@ int spdk_initialize_iscsi_conns(void)
 }
 
 /**
-
+ * \brief Create an iSCSI connection from the given parameters and schedule it
-\brief Create an iSCSI connection from the given parameters and schedule it
+ *        on a reactor.
-       on a reactor.
+ *
-
+ * \code
-\code
+ *
-
+ * # identify reactor where the new connections work item will be scheduled
-# identify reactor where the new connections work item will be scheduled
+ * reactor = spdk_iscsi_conn_allocate_reactor()
-reactor = spdk_iscsi_conn_allocate_reactor()
+ * allocate spdk_iscsi_conn object
-allocate spdk_iscsi_conn object
+ * initialize spdk_iscsi_conn object
-initialize spdk_iscsi_conn object
+ * schedule iSCSI connection work item on reactor
-schedule iSCSI connection work item on reactor
+ *
-
+ * \endcode
-\endcode
+ */
-
-*/
 int
 spdk_iscsi_conn_construct(struct spdk_iscsi_portal *portal,
 			  int sock)
@@ -811,20 +809,17 @@ spdk_iscsi_drop_conns(struct spdk_iscsi_conn *conn, const char *conn_match,
 }
 
 /**
-
+ * \brief Reads data for the specified iSCSI connection from its TCP socket.
- \brief Reads data for the specified iSCSI connection from its TCP socket.
+ *
-
+ * The TCP socket is marked as non-blocking, so this function may not read
- The TCP socket is marked as non-blocking, so this function may not read
+ * all data requested.
- all data requested.
+ *
-
+ * Returns SPDK_ISCSI_CONNECTION_FATAL if the recv() operation indicates a fatal
- Returns SPDK_ISCSI_CONNECTION_FATAL if the recv() operation indicates a fatal
+ * error with the TCP connection (including if the TCP connection was closed
- error with the TCP connection (including if the TCP connection was closed
+ * unexpectedly.
- unexpectedly.
+ *
-
+ * Otherwise returns the number of bytes successfully read.
- Otherwise returns the number of bytes successfully read.
+ */
-
-*/
-
 int
 spdk_iscsi_conn_read_data(struct spdk_iscsi_conn *conn, int bytes,
 			  void *buf)
@@ -1016,24 +1011,22 @@ spdk_iscsi_conn_handle_nop(struct spdk_iscsi_conn *conn)
 }
 
 /**
-
+ * \brief Makes one attempt to flush response PDUs back to the initiator.
- \brief Makes one attempt to flush response PDUs back to the initiator.
+ *
-
+ * Builds a list of iovecs for response PDUs that must be sent back to the
- Builds a list of iovecs for response PDUs that must be sent back to the
+ * initiator and passes it to writev().
- initiator and passes it to writev().
+ *
-
+ * Since the socket is non-blocking, writev() may not be able to flush all
- Since the socket is non-blocking, writev() may not be able to flush all
+ * of the iovecs, and may even partially flush one of the iovecs.  In this
- of the iovecs, and may even partially flush one of the iovecs.  In this
+ * case, the partially flushed PDU will remain on the write_pdu_list with
- case, the partially flushed PDU will remain on the write_pdu_list with
+ * an offset pointing to the next byte to be flushed.
- an offset pointing to the next byte to be flushed.
+ *
-
+ * Returns 0 if no exceptional error encountered.  This includes cases where
- Returns 0 if no exceptional error encountered.  This includes cases where
+ * there are no PDUs to flush or not all PDUs could be flushed.
- there are no PDUs to flush or not all PDUs could be flushed.
+ *
-
+ * Returns -1 if an exception error occurred indicating the TCP connection
- Returns -1 if an exception error occurred indicating the TCP connection
+ * should be closed.
- should be closed.
+ */
-
-*/
 static int
 spdk_iscsi_conn_flush_pdus_internal(struct spdk_iscsi_conn *conn)
 {
@@ -1140,26 +1133,24 @@ spdk_iscsi_conn_flush_pdus_internal(struct spdk_iscsi_conn *conn)
 }
 
 /**
-
+ * \brief Flushes response PDUs back to the initiator.
- \brief Flushes response PDUs back to the initiator.
+ *
-
+ * This function may return without all PDUs having flushed to the
- This function may return without all PDUs having flushed to the
+ * underlying TCP socket buffer - for example, in the case where the
- underlying TCP socket buffer - for example, in the case where the
+ * socket buffer is already full.
- socket buffer is already full.
+ *
-
+ * During normal RUNNING connection state, if not all PDUs are flushed,
- During normal RUNNING connection state, if not all PDUs are flushed,
+ * then subsequent calls to this routine will eventually flush
- then subsequent calls to this routine will eventually flush
+ * remaining PDUs.
- remaining PDUs.
+ *
-
+ * During other connection states (EXITING or LOGGED_OUT), this
- During other connection states (EXITING or LOGGED_OUT), this
+ * function will spin until all PDUs have successfully been flushed.
- function will spin until all PDUs have successfully been flushed.
+ *
-
+ * Returns 0 for success.
- Returns 0 for success.
+ *
-
+ * Returns -1 for an exceptional error indicating the TCP connection
- Returns -1 for an exceptional error indicating the TCP connection
+ * should be closed.
- should be closed.
+ */
-
-*/
 static int
 spdk_iscsi_conn_flush_pdus(struct spdk_iscsi_conn *conn)
 {
@@ -1351,23 +1342,21 @@ spdk_iscsi_conn_full_feature_do_work(void *arg)
 }
 
 /**
-
+ * \brief This is the main routine for the iSCSI 'idle' connection
-\brief This is the main routine for the iSCSI 'idle' connection
+ * work item.
-work item.
+ *
-
+ * This function handles processing of connecitons whose state have
-This function handles processing of connecitons whose state have
+ * been determined as 'idle' for lack of activity.  These connections
-been determined as 'idle' for lack of activity.  These connections
+ * no longer reside in the reactor's poller ring, instead they have
-no longer reside in the reactor's poller ring, instead they have
+ * been staged into an idle list.  This function utilizes the use of
-been staged into an idle list.  This function utilizes the use of
+ * epoll as a non-blocking means to test for new socket connection
-epoll as a non-blocking means to test for new socket connection
+ * events that indicate the connection should be moved back into the
-events that indicate the connection should be moved back into the
+ * active ring.
-active ring.
+ *
-
+ * While in the idle list, this function must scan these connections
-While in the idle list, this function must scan these connections
+ * to process required timer based actions that must be maintained
-to process required timer based actions that must be maintained
+ * even though the connection is considered 'idle'.
-even though the connection is considered 'idle'.
+ */
-
-*/
 void spdk_iscsi_conn_idle_do_work(void *arg)
 {
 	uint64_t	tsc;

lib/iscsi/iscsi.h

@@ -96,7 +96,7 @@
 /*
  * SPDK iSCSI target will only send a maximum of SPDK_BDEV_LARGE_RBUF_MAX_SIZE data segments, even if the
  * connection can support more.
-*/
+ */
 #define SPDK_ISCSI_MAX_SEND_DATA_SEGMENT_LENGTH SPDK_BDEV_LARGE_RBUF_MAX_SIZE
 
 /*

lib/iscsi/tgt_node.h

@@ -91,7 +91,7 @@ spdk_iscsi_find_init_grp(int tag);
 
 /* This typedef exists to work around an astyle 2.05 bug.
  * Remove it when astyle is fixed.
-*/
+ */
 typedef struct spdk_iscsi_tgt_node _spdk_iscsi_tgt_node;
 
 _spdk_iscsi_tgt_node *

lib/nvme/nvme_uevent.c

@@ -92,7 +92,7 @@ spdk_uevent_connect(void)
  *       action: "add" or "remove"
  *       subsystem: "uio"
  *       dev_path: "/devices/pci0000:80/0000:80:01.0/0000:81:00.0/uio/uio0"
-*/
+ */
 static int
 parse_event(const char *buf, struct spdk_uevent *event)
 {

lib/scsi/dev.c

@@ -134,7 +134,7 @@ spdk_scsi_dev_delete_lun(struct spdk_scsi_dev *dev,
 
 /* This typedef exists to work around an astyle 2.05 bug.
  * Remove it when astyle is fixed.
-*/
+ */
 typedef struct spdk_scsi_dev _spdk_scsi_dev;
 
 _spdk_scsi_dev *

lib/scsi/lun.c

@@ -282,16 +282,14 @@ static void spdk_scsi_lun_hot_remove(void *remove_ctx)
 }
 
 /**
-
+ * \brief Constructs a new spdk_scsi_lun object based on the provided parameters.
-\brief Constructs a new spdk_scsi_lun object based on the provided parameters.
+ *
-
+ * \param name Name for the SCSI LUN.
-\param name Name for the SCSI LUN.
+ * \param blockdev  Blockdev associated with this LUN
-\param blockdev  Blockdev associated with this LUN
+ *
-
+ * \return NULL if blockdev == NULL
-\return NULL if blockdev == NULL
+ * \return pointer to the new spdk_scsi_lun object otherwise
-\return pointer to the new spdk_scsi_lun object otherwise
+ */
-
-*/
 _spdk_scsi_lun *
 spdk_scsi_lun_construct(const char *name, struct spdk_bdev *bdev)
 {

scripts/check_format.sh

@@ -38,8 +38,9 @@ fi
 
 echo -n "Checking comment style..."
 
-git grep -e '/[*][^ *-]' -- '*.[ch]' > comment.log || true
+git grep --line-number -e '/[*][^ *-]' -- '*.[ch]' > comment.log || true
-git grep -e '[^ ][*]/' -- '*.[ch]' >> comment.log || true
+git grep --line-number -e '[^ ][*]/' -- '*.[ch]' >> comment.log || true
+git grep --line-number -e '^[*]' -- '*.[ch]' >> comment.log || true
 
 if [ -s comment.log ]; then
 	echo " Incorrect comment formatting detected"