Changeset 8e16454 in mainline


Ignore:
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

Location:
uspace/app/tmon
Files:
7 edited

Legend:

Unmodified
Added
Removed

  • uspace/app/tmon/burst_tests.c

    r59958992 r8e16454  
    4747#define INDENT "      "
    4848
     49/** Generic burst test parameters. */
    4950typedef struct tmon_burst_test_params {
    50         tmon_test_params_t base; /* inheritance */
     51        /** Inherited base. */
     52        tmon_test_params_t base;
     53        /** The count of reads/writes to perform. */
    5154        uint32_t cycles;
     55        /** Size of single read/write. */
    5256        size_t size;
    5357} tmon_burst_test_params_t;
    5458
     59/** Static array of long options, from which test parameters are parsed. */
    5560static struct option long_options[] = {
    5661        {"cycles", required_argument, NULL, 'n'},
    … …  
    5964};
    6065
     66/** String of short options, from which test parameters are parsed. */
    6167static const char *short_options = "n:s:";
    6268
     69/** Common option parser for all burst tests.
     70 * @param[in] argc Number of arguments.
     71 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     72 * @param[out] params Parsed test parameters (if successful).
     73 *
     74 * @return EOK if successful (in such case caller becomes the owner of `params`).
     75 */
    6376static int read_params(int argc, char *argv[], tmon_test_params_t **params)
    6477{
    … …  
    105118}
    106119
     120/** Unit of quantity used for pretty formatting. */
    107121typedef struct tmon_unit {
     122        /** Prefix letter, which is printed before the actual unit. */
    108123        char prefix;
     124        /** Factor of the unit. */
    109125        uint64_t factor;
    110126} tmon_unit_t;
    111127
     128/** Static array of units with decreasing factors. */
    112129static const tmon_unit_t units[] = {
    113130        { .prefix = 'E', .factor = 1ul << 60 },
    … …  
    119136};
    120137
     138/** Format size in bytes for human reading.
     139 * @param[in] size The size to format.
     140 * @param[in] fmt Format string. Must include one double and char.
     141 *
     142 * @return Heap-allocated string if successful (caller becomes its owner), NULL otherwise.
     143 */
    121144static char * format_size(double size, const char *fmt)
    122145{
     146        // Figure out the "tightest" unit.
    123147        unsigned i;
    124148        for (i = 0; i < ARRAY_SIZE(units); ++i) {
    … …  
    135159        }
    136160
     161        // Format the size.
    137162        const double div_size = size / factor;
    138163        char *out = NULL;
    … …  
    142167}
    143168
     169/** Print burst test parameters.
     170 * @param[in] params Test parameters to print.
     171 */
    144172static void print_params(const tmon_burst_test_params_t *params)
    145173{
    … …  
    151179}
    152180
     181/** Print burst test results.
     182 * @param[in] params Test parameters.
     183 * @param[in] duration Duration of the burst test.
     184 */
    153185static void print_results(const tmon_burst_test_params_t *params, usbdiag_dur_t duration)
    154186{
    … …  
    169201}
    170202
     203/** Run "interrupt in" burst test.
     204 * @param[in] exch Open async exchange with the diagnostic device.
     205 * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
     206 *
     207 * @return Exit code
     208 */
    171209static int run_intr_in(async_exch_t *exch, const tmon_test_params_t *generic_params)
    172210{
    … …  
    187225}
    188226
     227/** Run "interrupt out" burst test.
     228 * @param[in] exch Open async exchange with the diagnostic device.
     229 * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
     230 *
     231 * @return Exit code
     232 */
    189233static int run_intr_out(async_exch_t *exch, const tmon_test_params_t *generic_params)
    190234{
    … …  
    205249}
    206250
     251/** Run "bulk in" burst test.
     252 * @param[in] exch Open async exchange with the diagnostic device.
     253 * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
     254 *
     255 * @return Exit code
     256 */
    207257static int run_bulk_in(async_exch_t *exch, const tmon_test_params_t *generic_params)
    208258{
    … …  
    223273}
    224274
     275/** Run "bulk out" burst test.
     276 * @param[in] exch Open async exchange with the diagnostic device.
     277 * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
     278 *
     279 * @return Exit code
     280 */
    225281static int run_bulk_out(async_exch_t *exch, const tmon_test_params_t *generic_params)
    226282{
    … …  
    241297}
    242298
     299/** Run "isochronous in" burst test.
     300 * @param[in] exch Open async exchange with the diagnostic device.
     301 * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
     302 *
     303 * @return Exit code
     304 */
    243305static int run_isoch_in(async_exch_t *exch, const tmon_test_params_t *generic_params)
    244306{
    … …  
    259321}
    260322
     323/** Run "isochronous out" burst test.
     324 * @param[in] exch Open async exchange with the diagnostic device.
     325 * @param[in] generic_params Test parameters. Must point to 'tmon_burst_test_params_t'.
     326 *
     327 * @return Exit code
     328 */
    261329static int run_isoch_out(async_exch_t *exch, const tmon_test_params_t *generic_params)
    262330{
    … …  
    277345}
    278346
     347/** Interrupt in burst test command handler.
     348 * @param[in] argc Number of arguments.
     349 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     350 *
     351 * @return Exit code
     352 */
    279353int tmon_burst_intr_in(int argc, char *argv[])
    280354{
    … …  
    287361}
    288362
     363/** Interrupt out burst test command handler.
     364 * @param[in] argc Number of arguments.
     365 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     366 *
     367 * @return Exit code
     368 */
    289369int tmon_burst_intr_out(int argc, char *argv[])
    290370{
    … …  
    297377}
    298378
     379/** Interrupt bulk burst test command handler.
     380 * @param[in] argc Number of arguments.
     381 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     382 *
     383 * @return Exit code
     384 */
    299385int tmon_burst_bulk_in(int argc, char *argv[])
    300386{
    … …  
    307393}
    308394
     395/** Bulk out burst test command handler.
     396 * @param[in] argc Number of arguments.
     397 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     398 *
     399 * @return Exit code
     400 */
    309401int tmon_burst_bulk_out(int argc, char *argv[])
    310402{
    … …  
    317409}
    318410
     411/** Isochronous in burst test command handler.
     412 * @param[in] argc Number of arguments.
     413 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     414 *
     415 * @return Exit code
     416 */
    319417int tmon_burst_isoch_in(int argc, char *argv[])
    320418{
    … …  
    327425}
    328426
     427/** Isochronous out burst test command handler.
     428 * @param[in] argc Number of arguments.
     429 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     430 *
     431 * @return Exit code
     432 */
    329433int tmon_burst_isoch_out(int argc, char *argv[])
    330434{

  • uspace/app/tmon/commands.h

    r59958992 r8e16454  
    3737#define TMON_COMMANDS_H_
    3838
     39/* All commands are just versions of int main(int, char **). */
     40
     41/* List command just prints compatible devices. */
    3942int tmon_list(int, char **);
    4043

  • uspace/app/tmon/list.c

    r59958992 r8e16454  
    4444#define MAX_PATH_LENGTH 1024
    4545
     46/** Print a single item of the device list.
     47 * @param[in] svc Service ID of the devman function.
     48 */
    4649static void print_list_item(service_id_t svc)
    4750{
    … …  
    6366}
    6467
     68/** List command handler.
     69 * @param[in] argc Number of arguments.
     70 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     71 *
     72 * @return Exit code
     73 */
    6574int tmon_list(int argc, char *argv[])
    6675{

  • uspace/app/tmon/main.c

    r59958992 r8e16454  
    4242#define INDENT "      "
    4343
     44/** Command which is executed by tmon. */
    4445typedef struct tmon_cmd {
     46        /** Unique name, by which the command is executed. */
    4547        const char *name;
     48        /** Description of the command, which is displayed in the usage string. */
    4649        const char *description;
     50        /** Function, which executes the command. Same as int main(int, char**). */
    4751        int (*action)(int, char **);
    4852} tmon_cmd_t;
    4953
     54/** Static array of commands supported by tmon. */
    5055static tmon_cmd_t commands[] = {
    5156        {
    … …  
    8691};
    8792
     93/** Option shown in the usage string. */
    8894typedef struct tmon_opt {
     95        /** Long name of the option without "--" prefix. */
    8996        const char *long_name;
     97        /** Short name of the option without "-" prefix. */
    9098        char short_name;
     99        /** Description of the option displayed in the usage string. */
    91100        const char *description;
    92101} tmon_opt_t;
    93102
     103/** Static array of options displayed in the tmon usage string. */
    94104static tmon_opt_t options[] = {
    95105        {
    … …  
    105115};
    106116
     117/** Print usage string.
     118 * @param[in] app_name Name to print in the invocation example.
     119 */
    107120static void print_usage(char *app_name)
    108121{
    … …  
    122135}
    123136
     137/** Main tmon entry point.
     138 * @param[in] argc Number of arguments.
     139 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     140 *
     141 * @return Exit code
     142 */
    124143int main(int argc, char *argv[])
    125144{

  • uspace/app/tmon/resolve.c

    r59958992 r8e16454  
    4444#define NAME "tmon"
    4545
     46/** Resolve a single function by its class (fail if there is more/less than 1).
     47 * @param[out] fun Resolved function handle (if found).
     48 *
     49 * @return EOK if the function was resolved successfully.
     50 */
    4651int tmon_resolve_default(devman_handle_t *fun)
    4752{
    … …  
    7984}
    8085
     86/** Resolve a function by its name or device path.
     87 * @param[in] dev_path Name or device path (see `devman_fun_get_handle` for possible values).
     88 * @param[out] fun Resolved function handle (if found).
     89 *
     90 * @return EOK if the function was resolved successfully.
     91 */
    8192int tmon_resolve_named(const char *dev_path, devman_handle_t *fun)
    8293{

  • uspace/app/tmon/tf.c

    r59958992 r8e16454  
    4545#define MAX_PATH_LENGTH 1024
    4646
    47 int tmon_test_main(int argc, char *argv[], const tmon_test_ops_t *ops) {
     47/** Common command handler for all test commands.
     48 * @param[in] argc Number of arguments.
     49 * @param[in] argv Argument values. Must point to exactly `argc` strings.
     50 *
     51 * @return Exit code
     52 */
     53int tmon_test_main(int argc, char *argv[], const tmon_test_ops_t *ops)
     54{
     55        // Resolve device function.
    4856        devman_handle_t fun = -1;
    4957
    … …  
    6775        printf("Using device: %s\n", path);
    6876
     77        // Read test parameters from options.
    6978        tmon_test_params_t *params = NULL;
    7079        if ((rc = ops->read_params(argc, argv, &params))) {
    … …  
    7382        }
    7483
     84        // Run the test body.
    7585        async_sess_t *sess = usbdiag_connect(fun);
    7686        if (!sess) {

  • uspace/app/tmon/tf.h

    r59958992 r8e16454  
    4141/** Parameters common for all tests. */
    4242typedef struct tmon_test_params {
     43        /* Nothing here. */
    4344} tmon_test_params_t;
    4445
Note: See TracChangeset for help on using the changeset viewer.