Changeset 8e16454 in mainline for uspace/app/tmon/burst_tests.c

Timestamp:

2017-12-27T16:46:27Z (6 years ago)

Author:

Petr Manek <petr.manek@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

f4b83cc

Parents:

59958992

git-author:

Petr Manek <petr.manek@…> (2017-12-27 16:43:34)

git-committer:

Petr Manek <petr.manek@…> (2017-12-27 16:46:27)

Message:

tmon: add in-code docs and method docstrings

File:

• uspace/app/tmon/burst_tests.c (modified) (19 diffs)

uspace/app/tmon/burst_tests.c

@@ -47 +47 @@
 #define INDENT "      "
 
+/** Generic burst test parameters. */
 typedef struct tmon_burst_test_params {
-        tmon_test_params_t base; /* inheritance */
+        /** Inherited base. */
+        tmon_test_params_t base;
+        /** The count of reads/writes to perform. */
         uint32_t cycles;
+        /** Size of single read/write. */
         size_t size;
 } tmon_burst_test_params_t;
 
+/** Static array of long options, from which test parameters are parsed. */
 static struct option long_options[] = {
         {"cycles", required_argument, NULL, 'n'},
@@ -59 +64 @@
 };
 
+/** String of short options, from which test parameters are parsed. */
 static const char *short_options = "n:s:";
 
+/** Common option parser for all burst tests.
+ * @param[in] argc Number of arguments.
+ * @param[in] argv Argument values. Must point to exactly `argc` strings.
+ * @param[out] params Parsed test parameters (if successful).
+ *
+ * @return EOK if successful (in such case caller becomes the owner of `params`).
+ */
 static int read_params(int argc, char *argv[], tmon_test_params_t **params)
 {
@@ -105 +118 @@
 }
 
+/** Unit of quantity used for pretty formatting. */
 typedef struct tmon_unit {
+        /** Prefix letter, which is printed before the actual unit. */
         char prefix;
+        /** Factor of the unit. */
         uint64_t factor;
 } tmon_unit_t;
 
+/** Static array of units with decreasing factors. */
 static const tmon_unit_t units[] = {
         { .prefix = 'E', .factor = 1ul << 60 },
@@ -119 +136 @@
 };
 
+/** Format size in bytes for human reading.
+ * @param[in] size The size to format.
+ * @param[in] fmt Format string. Must include one double and char.
+ *
+ * @return Heap-allocated string if successful (caller becomes its owner), NULL otherwise.
+ */
 static char * format_size(double size, const char *fmt)
 {
+        // Figure out the "tightest" unit.
         unsigned i;
         for (i = 0; i < ARRAY_SIZE(units); ++i) {
@@ -135 +159 @@
         }
 
+        // Format the size.
         const double div_size = size / factor;
         char *out = NULL;
@@ -142 +167 @@
 }
 
+/** Print burst test parameters.
+ * @param[in] params Test parameters to print.
+ */
 static void print_params(const tmon_burst_test_params_t *params)
 {
@@ -151 +179 @@
 }
 
+/** Print burst test results.
+ * @param[in] params Test parameters.
+ * @param[in] duration Duration of the burst test.
+ */
 static void print_results(const tmon_burst_test_params_t *params, usbdiag_dur_t duration)
 {
@@ -169 +201 @@
 }
 
+/** Run "interrupt in" burst test.
+ * @param[in] exch Open async exchange with the diagnostic device.
+ * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
+ *
+ * @return Exit code
+ */
 static int run_intr_in(async_exch_t *exch, const tmon_test_params_t *generic_params)
 {
@@ -187 +225 @@
 }
 
+/** Run "interrupt out" burst test.
+ * @param[in] exch Open async exchange with the diagnostic device.
+ * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
+ *
+ * @return Exit code
+ */
 static int run_intr_out(async_exch_t *exch, const tmon_test_params_t *generic_params)
 {
@@ -205 +249 @@
 }
 
+/** Run "bulk in" burst test.
+ * @param[in] exch Open async exchange with the diagnostic device.
+ * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
+ *
+ * @return Exit code
+ */
 static int run_bulk_in(async_exch_t *exch, const tmon_test_params_t *generic_params)
 {
@@ -223 +273 @@
 }
 
+/** Run "bulk out" burst test.
+ * @param[in] exch Open async exchange with the diagnostic device.
+ * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
+ *
+ * @return Exit code
+ */
 static int run_bulk_out(async_exch_t *exch, const tmon_test_params_t *generic_params)
 {
@@ -241 +297 @@
 }
 
+/** Run "isochronous in" burst test.
+ * @param[in] exch Open async exchange with the diagnostic device.
+ * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
+ *
+ * @return Exit code
+ */
 static int run_isoch_in(async_exch_t *exch, const tmon_test_params_t *generic_params)
 {
@@ -259 +321 @@
 }
 
+/** Run "isochronous out" burst test.
+ * @param[in] exch Open async exchange with the diagnostic device.
+ * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
+ *
+ * @return Exit code
+ */
 static int run_isoch_out(async_exch_t *exch, const tmon_test_params_t *generic_params)
 {
@@ -277 +345 @@
 }
 
+/** Interrupt in burst test command handler.
+ * @param[in] argc Number of arguments.
+ * @param[in] argv Argument values. Must point to exactly `argc` strings.
+ *
+ * @return Exit code
+ */
 int tmon_burst_intr_in(int argc, char *argv[])
 {
@@ -287 +361 @@
 }
 
+/** Interrupt out burst test command handler.
+ * @param[in] argc Number of arguments.
+ * @param[in] argv Argument values. Must point to exactly `argc` strings.
+ *
+ * @return Exit code
+ */
 int tmon_burst_intr_out(int argc, char *argv[])
 {
@@ -297 +377 @@
 }
 
+/** Interrupt bulk burst test command handler.
+ * @param[in] argc Number of arguments.
+ * @param[in] argv Argument values. Must point to exactly `argc` strings.
+ *
+ * @return Exit code
+ */
 int tmon_burst_bulk_in(int argc, char *argv[])
 {
@@ -307 +393 @@
 }
 
+/** Bulk out burst test command handler.
+ * @param[in] argc Number of arguments.
+ * @param[in] argv Argument values. Must point to exactly `argc` strings.
+ *
+ * @return Exit code
+ */
 int tmon_burst_bulk_out(int argc, char *argv[])
 {
@@ -317 +409 @@
 }
 
+/** Isochronous in burst test command handler.
+ * @param[in] argc Number of arguments.
+ * @param[in] argv Argument values. Must point to exactly `argc` strings.
+ *
+ * @return Exit code
+ */
 int tmon_burst_isoch_in(int argc, char *argv[])
 {
@@ -327 +425 @@
 }
 
+/** Isochronous out burst test command handler.
+ * @param[in] argc Number of arguments.
+ * @param[in] argv Argument values. Must point to exactly `argc` strings.
+ *
+ * @return Exit code
+ */
 int tmon_burst_isoch_out(int argc, char *argv[])
 {