diff --git a/include/spdk/endian.h b/include/spdk/endian.h index 1941b0fd5..a6fae07bf 100644 --- a/include/spdk/endian.h +++ b/include/spdk/endian.h @@ -32,9 +32,9 @@ */ /** -* \file -* Endian conversion functions -*/ + * \file + * Endian conversion functions + */ #ifndef SPDK_ENDIAN_H #define SPDK_ENDIAN_H diff --git a/include/spdk/env.h b/include/spdk/env.h index b164ffcfc..70dce6322 100644 --- a/include/spdk/env.h +++ b/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); /** diff --git a/include/spdk/event.h b/include/spdk/event.h index b30d57ef2..59366a412 100644 --- a/include/spdk/event.h +++ b/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); /** diff --git a/include/spdk/gpt_spec.h b/include/spdk/gpt_spec.h index 32906cbfe..19880bb2b 100644 --- a/include/spdk/gpt_spec.h +++ b/include/spdk/gpt_spec.h @@ -32,9 +32,9 @@ */ /** -* \file -* GUID Partition Table (GPT) specification definitions -*/ + * \file + * GUID Partition Table (GPT) specification definitions + */ #ifndef SPDK_GPT_SPEC_H #define SPDK_GPT_SPEC_H diff --git a/include/spdk/scsi.h b/include/spdk/scsi.h index f99be677a..73eafe6a0 100644 --- a/include/spdk/scsi.h +++ b/include/spdk/scsi.h @@ -184,16 +184,14 @@ struct spdk_scsi_dev { }; /** - -\brief Represents a SCSI LUN. - -LUN modules will implement the function pointers specifically for the LUN -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. -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. - -*/ + * \brief Represents a SCSI LUN. + * + * LUN modules will implement the function pointers specifically for the LUN + * 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. + * 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. + */ 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. - -\param name Name for the SCSI device. -\param queue_depth Queue depth for the SCSI device. This queue depth is - a combined queue depth for all LUNs in the device. -\param lun_list List of LUN objects for the SCSI device. Caller is - 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 - responsible for managing the memory containing this list. - 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. -\return The constructed spdk_scsi_dev object. - -*/ + * \brief Constructs a SCSI device object using the given parameters. + * + * \param name Name for the SCSI device. + * \param queue_depth Queue depth for the SCSI device. This queue depth is + * a combined queue depth for all LUNs in the device. + * \param lun_list List of LUN objects for the SCSI device. Caller is + * 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 + * responsible for managing the memory containing this list. + * 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. + * \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, diff --git a/include/spdk_internal/bdev.h b/include/spdk_internal/bdev.h index 30bc98c82..b0e03f1e2 100644 --- a/include/spdk_internal/bdev.h +++ b/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 -dictated by struct spdk_bdev_fn_table must be provided. - -The module should register itself using SPDK_BDEV_MODULE_REGISTER or -SPDK_VBDEV_MODULE_REGISTER to define the parameters for the module. - -Use SPDK_BDEV_MODULE_REGISTER for all block backends that are real disks. -Any virtual backends such as RAID, partitioning, etc. should use -SPDK_VBDEV_MODULE_REGISTER. - -
- -In the module initialization code, the config file sections can be parsed to -acquire custom configuration parameters. For example, if the config file has -a section such as below: -
-[MyBE]
-  MyParam 1234
-
- -The value can be extracted as the example below: -
-struct spdk_conf_section *sp = spdk_conf_find_section(NULL, "MyBe");
-int my_param = spdk_conf_section_get_intval(sp, "MyParam");
-
- -The backend initialization routine also need to create "disks". A virtual -representation of each LUN must be constructed. Mainly a struct spdk_bdev -must be passed to the bdev database via spdk_bdev_register(). - -*/ + * + * To implement a backend block device driver, a number of functions + * dictated by struct spdk_bdev_fn_table must be provided. + * + * The module should register itself using SPDK_BDEV_MODULE_REGISTER or + * SPDK_VBDEV_MODULE_REGISTER to define the parameters for the module. + * + * Use SPDK_BDEV_MODULE_REGISTER for all block backends that are real disks. + * Any virtual backends such as RAID, partitioning, etc. should use + * SPDK_VBDEV_MODULE_REGISTER. + * + *
+ * + * In the module initialization code, the config file sections can be parsed to + * acquire custom configuration parameters. For example, if the config file has + * a section such as below: + * 
+ * [MyBE]
+ * MyParam 1234
+ *
+ * + * The value can be extracted as the example below: + * 
+ * struct spdk_conf_section *sp = spdk_conf_find_section(NULL, "MyBe");
+ * int my_param = spdk_conf_section_get_intval(sp, "MyParam");
+ *
+ * + * The backend initialization routine also need to create "disks". A virtual + * representation of each LUN must be constructed. Mainly a struct spdk_bdev + * must be passed to the bdev database via spdk_bdev_register(). + */ /** Block device module */ struct spdk_bdev_module_if { diff --git a/lib/env_dpdk/pci.c b/lib/env_dpdk/pci.c index 08e545404..49b82d8e5 100644 --- a/lib/env_dpdk/pci.c +++ b/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, diff --git a/lib/event/reactor.c b/lib/event/reactor.c index 12e3b3fac..f0ad588d7 100644 --- a/lib/event/reactor.c +++ b/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 ". - -This makes the reactor threads distinguishable in top and gdb. - -*/ + * + * \brief Set current reactor thread name to "reactor ". + * + * 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. - -\code - -while (1) - if (events to run) - dequeue and run a batch of events - - if (active pollers) - run the first poller in the list and move it to the back - - if (first timer poller has expired) - run the first timer poller and reinsert it in the timer list - - if (idle for at least SPDK_REACTOR_SPIN_TIME_US) - sleep until next timer poller is scheduled to expire -\endcode - -*/ + * + * \brief This is the main function of the reactor thread. + * + * \code + * + * while (1) + * if (events to run) + * dequeue and run a batch of events + * + * if (active pollers) + * run the first poller in the list and move it to the back + * + * if (first timer poller has expired) + * run the first timer poller and reinsert it in the timer list + * + * if (idle for at least SPDK_REACTOR_SPIN_TIME_US) + * sleep until next timer poller is scheduled to expire + * \endcode + * + */ static int _spdk_reactor_run(void *arg) { diff --git a/lib/iscsi/conn.c b/lib/iscsi/conn.c index ce3018820..67424662f 100644 --- a/lib/iscsi/conn.c +++ b/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 - on a reactor. - -\code - -# identify reactor where the new connections work item will be scheduled -reactor = spdk_iscsi_conn_allocate_reactor() -allocate spdk_iscsi_conn object -initialize spdk_iscsi_conn object -schedule iSCSI connection work item on reactor - -\endcode - -*/ + * \brief Create an iSCSI connection from the given parameters and schedule it + * on a reactor. + * + * \code + * + * # identify reactor where the new connections work item will be scheduled + * reactor = spdk_iscsi_conn_allocate_reactor() + * allocate spdk_iscsi_conn object + * initialize spdk_iscsi_conn object + * schedule iSCSI connection work item on reactor + * + * \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. - - The TCP socket is marked as non-blocking, so this function may not read - all data requested. - - Returns SPDK_ISCSI_CONNECTION_FATAL if the recv() operation indicates a fatal - error with the TCP connection (including if the TCP connection was closed - unexpectedly. - - Otherwise returns the number of bytes successfully read. - -*/ - + * \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 + * all data requested. + * + * Returns SPDK_ISCSI_CONNECTION_FATAL if the recv() operation indicates a fatal + * error with the TCP connection (including if the TCP connection was closed + * unexpectedly. + * + * 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. - - Builds a list of iovecs for response PDUs that must be sent back to the - initiator and passes it to writev(). - - 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 - case, the partially flushed PDU will remain on the write_pdu_list with - an offset pointing to the next byte to be flushed. - - Returns 0 if no exceptional error encountered. This includes cases where - there are no PDUs to flush or not all PDUs could be flushed. - - Returns -1 if an exception error occurred indicating the TCP connection - should be closed. - -*/ + * \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 + * initiator and passes it to writev(). + * + * 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 + * case, the partially flushed PDU will remain on the write_pdu_list with + * an offset pointing to the next byte to be flushed. + * + * Returns 0 if no exceptional error encountered. This includes cases where + * there are no PDUs to flush or not all PDUs could be flushed. + * + * Returns -1 if an exception error occurred indicating the TCP connection + * 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. - - This function may return without all PDUs having flushed to the - underlying TCP socket buffer - for example, in the case where the - socket buffer is already full. - - During normal RUNNING connection state, if not all PDUs are flushed, - then subsequent calls to this routine will eventually flush - remaining PDUs. - - During other connection states (EXITING or LOGGED_OUT), this - function will spin until all PDUs have successfully been flushed. - - Returns 0 for success. - - Returns -1 for an exceptional error indicating the TCP connection - should be closed. - -*/ + * \brief Flushes response PDUs back to the initiator. + * + * This function may return without all PDUs having flushed to the + * underlying TCP socket buffer - for example, in the case where the + * socket buffer is already full. + * + * During normal RUNNING connection state, if not all PDUs are flushed, + * then subsequent calls to this routine will eventually flush + * remaining PDUs. + * + * During other connection states (EXITING or LOGGED_OUT), this + * function will spin until all PDUs have successfully been flushed. + * + * Returns 0 for success. + * + * Returns -1 for an exceptional error indicating the TCP connection + * 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 -work item. - -This function handles processing of connecitons whose state have -been determined as 'idle' for lack of activity. These connections -no longer reside in the reactor's poller ring, instead they have -been staged into an idle list. This function utilizes the use of -epoll as a non-blocking means to test for new socket connection -events that indicate the connection should be moved back into the -active ring. - -While in the idle list, this function must scan these connections -to process required timer based actions that must be maintained -even though the connection is considered 'idle'. - -*/ + * \brief This is the main routine for the iSCSI 'idle' connection + * work item. + * + * This function handles processing of connecitons whose state have + * been determined as 'idle' for lack of activity. These connections + * no longer reside in the reactor's poller ring, instead they have + * been staged into an idle list. This function utilizes the use of + * epoll as a non-blocking means to test for new socket connection + * events that indicate the connection should be moved back into the + * active ring. + * + * While in the idle list, this function must scan these connections + * to process required timer based actions that must be maintained + * even though the connection is considered 'idle'. + */ void spdk_iscsi_conn_idle_do_work(void *arg) { uint64_t tsc; diff --git a/lib/iscsi/iscsi.h b/lib/iscsi/iscsi.h index bd6d36024..0a07bc450 100644 --- a/lib/iscsi/iscsi.h +++ b/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 /* diff --git a/lib/iscsi/tgt_node.h b/lib/iscsi/tgt_node.h index 99d888605..df036edb4 100644 --- a/lib/iscsi/tgt_node.h +++ b/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 * diff --git a/lib/nvme/nvme_uevent.c b/lib/nvme/nvme_uevent.c index 097de22fe..8eec0ed64 100644 --- a/lib/nvme/nvme_uevent.c +++ b/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) { diff --git a/lib/scsi/dev.c b/lib/scsi/dev.c index 15db10671..41624fc55 100644 --- a/lib/scsi/dev.c +++ b/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 * diff --git a/lib/scsi/lun.c b/lib/scsi/lun.c index 2a4946be6..5890b7d5a 100644 --- a/lib/scsi/lun.c +++ b/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. - -\param name Name for the SCSI LUN. -\param blockdev Blockdev associated with this LUN - -\return NULL if blockdev == NULL -\return pointer to the new spdk_scsi_lun object otherwise - -*/ + * \brief Constructs a new spdk_scsi_lun object based on the provided parameters. + * + * \param name Name for the SCSI LUN. + * \param blockdev Blockdev associated with this LUN + * + * \return NULL if blockdev == NULL + * \return pointer to the new spdk_scsi_lun object otherwise + */ _spdk_scsi_lun * spdk_scsi_lun_construct(const char *name, struct spdk_bdev *bdev) { diff --git a/scripts/check_format.sh b/scripts/check_format.sh index efe1e3b98..e067c620f 100755 --- a/scripts/check_format.sh +++ b/scripts/check_format.sh @@ -38,8 +38,9 @@ fi echo -n "Checking comment style..." -git grep -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 +git grep --line-number -e '^[*]' -- '*.[ch]' >> comment.log || true if [ -s comment.log ]; then echo " Incorrect comment formatting detected"