log: add option argument help

The option --log-level was not completely described in the usage text,
and it was difficult to guess the names of the log types and levels.

A new value "help" is accepted after --log-level to give more details
about the syntax and listing the log types and levels.

The array "levels" used for level name parsing is replaced with
a (modified) existing function which was used in rte_log_dump().

The new function rte_log_list_types() is exported in the API
for allowing an application to give this info to the user
if not exposing the EAL option --log-level.
The list of log types cannot include all drivers if not linked in the
application (shared object plugin case).

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
Reviewed-by: David Marchand <david.marchand@redhat.com>

diff --git a/lib/librte_eal/common/eal_common_log.c b/lib/librte_eal/common/eal_common_log.c
index b9b982f..4c1d514 100644 (file)
--- a/lib/librte_eal/common/eal_common_log.c
+++ b/lib/librte_eal/common/eal_common_log.c
@@ -397,12 +397,12 @@ RTE_INIT_PRIO(log_init, LOG)
        rte_logs.dynamic_types_len = RTE_LOGTYPE_FIRST_EXT_ID;
 }
 
-static const char *
-loglevel_to_string(uint32_t level)
+const char *
+eal_log_level2str(uint32_t level)
 {
        switch (level) {
        case 0: return "disabled";
-       case RTE_LOG_EMERG: return "emerg";
+       case RTE_LOG_EMERG: return "emergency";
        case RTE_LOG_ALERT: return "alert";
        case RTE_LOG_CRIT: return "critical";
        case RTE_LOG_ERR: return "error";
@@ -414,6 +414,50 @@ loglevel_to_string(uint32_t level)
        }
 }
 
+static int
+log_type_compare(const void *a, const void *b)
+{
+       const struct rte_log_dynamic_type *type_a = a;
+       const struct rte_log_dynamic_type *type_b = b;
+
+       if (type_a->name == NULL && type_b->name == NULL)
+               return 0;
+       if (type_a->name == NULL)
+               return -1;
+       if (type_b->name == NULL)
+               return 1;
+       return strcmp(type_a->name, type_b->name);
+}
+
+/* Dump name of each logtype, one per line. */
+void
+rte_log_list_types(FILE *out, const char *prefix)
+{
+       struct rte_log_dynamic_type *sorted_types;
+       const size_t type_size = sizeof(rte_logs.dynamic_types[0]);
+       const size_t type_count = rte_logs.dynamic_types_len;
+       const size_t total_size = type_size * type_count;
+       size_t type;
+
+       sorted_types = malloc(total_size);
+       if (sorted_types == NULL) {
+               /* no sorting - unlikely */
+               sorted_types = rte_logs.dynamic_types;
+       } else {
+               memcpy(sorted_types, rte_logs.dynamic_types, total_size);
+               qsort(sorted_types, type_count, type_size, log_type_compare);
+       }
+
+       for (type = 0; type < type_count; ++type) {
+               if (sorted_types[type].name == NULL)
+                       continue;
+               fprintf(out, "%s%s\n", prefix, sorted_types[type].name);
+       }
+
+       if (sorted_types != rte_logs.dynamic_types)
+               free(sorted_types);
+}
+
 /* dump global level and registered log types */
 void
 rte_log_dump(FILE *f)
@@ -421,14 +465,14 @@ rte_log_dump(FILE *f)
        size_t i;
 
        fprintf(f, "global log level is %s\n",
-               loglevel_to_string(rte_log_get_global_level()));
+               eal_log_level2str(rte_log_get_global_level()));
 
        for (i = 0; i < rte_logs.dynamic_types_len; i++) {
                if (rte_logs.dynamic_types[i].name == NULL)
                        continue;
                fprintf(f, "id %zu: %s, level is %s\n",
                        i, rte_logs.dynamic_types[i].name,
-                       loglevel_to_string(rte_logs.dynamic_types[i].loglevel));
+                       eal_log_level2str(rte_logs.dynamic_types[i].loglevel));
        }
 }
 

diff --git a/lib/librte_eal/common/eal_common_options.c b/lib/librte_eal/common/eal_common_options.c
index 7075a05..2951b1a 100644 (file)
--- a/lib/librte_eal/common/eal_common_options.c
+++ b/lib/librte_eal/common/eal_common_options.c
@@ -1227,19 +1227,31 @@ eal_parse_syslog(const char *facility, struct internal_config *conf)
 }
 #endif
 
+static void
+eal_log_usage(void)
+{
+       unsigned int level;
+
+       printf("Log type is a pattern matching items of this list"
+                       " (plugins may be missing):\n");
+       rte_log_list_types(stdout, "\t");
+       printf("\n");
+       printf("Syntax using globbing pattern:     ");
+       printf("--"OPT_LOG_LEVEL" pattern:level\n");
+       printf("Syntax using regular expression:   ");
+       printf("--"OPT_LOG_LEVEL" regexp,level\n");
+       printf("Syntax for the global level:       ");
+       printf("--"OPT_LOG_LEVEL" level\n");
+       printf("Logs are emitted if allowed by both global and specific levels.\n");
+       printf("\n");
+       printf("Log level can be a number or the first letters of its name:\n");
+       for (level = 1; level <= RTE_LOG_MAX; level++)
+               printf("\t%d   %s\n", level, eal_log_level2str(level));
+}
+
 static int
 eal_parse_log_priority(const char *level)
 {
-       static const char * const levels[] = {
-               [RTE_LOG_EMERG]   = "emergency",
-               [RTE_LOG_ALERT]   = "alert",
-               [RTE_LOG_CRIT]    = "critical",
-               [RTE_LOG_ERR]     = "error",
-               [RTE_LOG_WARNING] = "warning",
-               [RTE_LOG_NOTICE]  = "notice",
-               [RTE_LOG_INFO]    = "info",
-               [RTE_LOG_DEBUG]   = "debug",
-       };
        size_t len = strlen(level);
        unsigned long tmp;
        char *end;
@@ -1250,7 +1262,7 @@ eal_parse_log_priority(const char *level)
 
        /* look for named values, skip 0 which is not a valid level */
        for (i = 1; i <= RTE_LOG_MAX; i++) {
-               if (strncmp(levels[i], level, len) == 0)
+               if (strncmp(eal_log_level2str(i), level, len) == 0)
                        return i;
        }
 
@@ -1274,6 +1286,11 @@ eal_parse_log_level(const char *arg)
        char *str, *level;
        int priority;
 
+       if (strcmp(arg, "help") == 0) {
+               eal_log_usage();
+               exit(EXIT_SUCCESS);
+       }
+
        str = strdup(arg);
        if (str == NULL)
                return -1;
@@ -2068,9 +2085,10 @@ eal_common_usage(void)
 #ifndef RTE_EXEC_ENV_WINDOWS
               "  --"OPT_SYSLOG"            Set syslog facility\n"
 #endif
-              "  --"OPT_LOG_LEVEL"=<int>   Set global log level\n"
-              "  --"OPT_LOG_LEVEL"=<type-match>:<int>\n"
+              "  --"OPT_LOG_LEVEL"=<level> Set global log level\n"
+              "  --"OPT_LOG_LEVEL"=<type-match>:<level>\n"
               "                      Set specific log level\n"
+              "  --"OPT_LOG_LEVEL"=help    Show log types and levels\n"
 #ifndef RTE_EXEC_ENV_WINDOWS
               "  --"OPT_TRACE"=<regex-match>\n"
               "                      Enable trace based on regular expression trace name.\n"

diff --git a/lib/librte_eal/common/eal_log.h b/lib/librte_eal/common/eal_log.h
index 684650a..c784fa6 100644 (file)
--- a/lib/librte_eal/common/eal_log.h
+++ b/lib/librte_eal/common/eal_log.h
@@ -24,4 +24,9 @@ void eal_log_set_default(FILE *default_log);
 int eal_log_save_regexp(const char *regexp, uint32_t level);
 int eal_log_save_pattern(const char *pattern, uint32_t level);
 
+/*
+ * Convert log level to string.
+ */
+const char *eal_log_level2str(uint32_t level);
+
 #endif /* EAL_LOG_H */

diff --git a/lib/librte_eal/include/rte_log.h b/lib/librte_eal/include/rte_log.h
index 424dfa3..a1c608a 100644 (file)
--- a/lib/librte_eal/include/rte_log.h
+++ b/lib/librte_eal/include/rte_log.h
@@ -240,6 +240,20 @@ int rte_log_register(const char *name);
 __rte_experimental
 int rte_log_register_type_and_pick_level(const char *name, uint32_t level_def);
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Dump name of each logtype, one per line.
+ *
+ * @param out
+ *   Stream where the list is sent.
+ * @param prefix
+ *   String preceding each logtype in the output.
+ */
+__rte_experimental
+void rte_log_list_types(FILE *out, const char *prefix);
+
 /**
  * Dump log information.
  *

diff --git a/lib/librte_eal/version.map b/lib/librte_eal/version.map
index b3b5c43..e7217ae 100644 (file)
--- a/lib/librte_eal/version.map
+++ b/lib/librte_eal/version.map
@@ -411,6 +411,7 @@ EXPERIMENTAL {
 
        # added in 21.05
        rte_intr_callback_unregister_sync;
+       rte_log_list_types;
        rte_thread_key_create;
        rte_thread_key_delete;
        rte_thread_value_get;