cmdline: make implementation logically opaque

struct cmdline exposes platform-specific members it contains, most
notably struct termios that is only available on Unix. While ABI
considerations prevent from hinding the definition on already supported
platforms, struct cmdline is considered logically opaque from now on.
Add a deprecation notice targeted at 20.11.

* Remove tests checking struct cmdline content as meaningless.

* Fix missing cmdline_free() in unit test.

* Add cmdline_get_rdline() to access history buffer indirectly.
  The new function is currently used only in tests.

Suggested-by: Olivier Matz <olivier.matz@6wind.com>
Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
Acked-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Olivier Matz <olivier.matz@6wind.com>

diff --git a/app/test-cmdline/commands.c b/app/test-cmdline/commands.c
index d67c0ca6ac78e39750bc7e62478c8355580ac22f..ff7ac973e1b73547ace7ad12b85ef8e82de42ce2 100644 (file)
--- a/app/test-cmdline/commands.c
+++ b/app/test-cmdline/commands.c
@@ -294,8 +294,10 @@ cmd_get_history_bufsize_parsed(__rte_unused void *parsed_result,
                struct cmdline *cl,
                __rte_unused void *data)
 {
+       struct rdline *rdl = cmdline_get_rdline(cl);
+
        cmdline_printf(cl, "History buffer size: %zu\n",
-                       sizeof(cl->rdl.history_buf));
+                       sizeof(rdl->history_buf));
 }
 
 cmdline_parse_token_string_t cmd_get_history_bufsize_tok =
@@ -326,7 +328,9 @@ cmd_clear_history_parsed(__rte_unused void *parsed_result,
                struct cmdline *cl,
                __rte_unused void *data)
 {
-       rdline_clear_history(&cl->rdl);
+       struct rdline *rdl = cmdline_get_rdline(cl);
+
+       rdline_clear_history(rdl);
 }
 
 cmdline_parse_token_string_t cmd_clear_history_tok =

diff --git a/app/test/test_cmdline_lib.c b/app/test/test_cmdline_lib.c
index dec465da5f7368ee4f1eef1f2bdb7a396f3fcbe8..bd72df0da2b4d9ef1b17b38637eca79d3c0f3219 100644 (file)
--- a/app/test/test_cmdline_lib.c
+++ b/app/test/test_cmdline_lib.c
@@ -46,22 +46,29 @@ complete_buffer(__rte_unused struct rdline *rdl,
 static int
 test_cmdline_parse_fns(void)
 {
-       struct cmdline cl;
+       struct cmdline *cl;
+       cmdline_parse_ctx_t ctx;
        int i = 0;
        char dst[CMDLINE_TEST_BUFSIZE];
 
+       cl = cmdline_new(&ctx, "prompt", -1, -1);
+       if (cl == NULL) {
+               printf("Error: cannot create cmdline to test parse fns!\n");
+               return -1;
+       }
+
        if (cmdline_parse(NULL, "buffer") >= 0)
                goto error;
-       if (cmdline_parse(&cl, NULL) >= 0)
+       if (cmdline_parse(cl, NULL) >= 0)
                goto error;
 
        if (cmdline_complete(NULL, "buffer", &i, dst, sizeof(dst)) >= 0)
                goto error;
-       if (cmdline_complete(&cl, NULL, &i, dst, sizeof(dst)) >= 0)
+       if (cmdline_complete(cl, NULL, &i, dst, sizeof(dst)) >= 0)
                goto error;
-       if (cmdline_complete(&cl, "buffer", NULL, dst, sizeof(dst)) >= 0)
+       if (cmdline_complete(cl, "buffer", NULL, dst, sizeof(dst)) >= 0)
                goto error;
-       if (cmdline_complete(&cl, "buffer", &i, NULL, sizeof(dst)) >= 0)
+       if (cmdline_complete(cl, "buffer", &i, NULL, sizeof(dst)) >= 0)
                goto error;
 
        return 0;
@@ -166,11 +173,11 @@ static int
 test_cmdline_fns(void)
 {
        cmdline_parse_ctx_t ctx;
-       struct cmdline cl, *tmp;
+       struct cmdline *cl;
 
        memset(&ctx, 0, sizeof(ctx));
-       tmp = cmdline_new(&ctx, "test", -1, -1);
-       if (tmp == NULL)
+       cl = cmdline_new(&ctx, "test", -1, -1);
+       if (cl == NULL)
                goto error;
 
        if (cmdline_new(NULL, "prompt", 0, 0) != NULL)
@@ -179,7 +186,7 @@ test_cmdline_fns(void)
                goto error;
        if (cmdline_in(NULL, "buffer", CMDLINE_TEST_BUFSIZE) >= 0)
                goto error;
-       if (cmdline_in(&cl, NULL, CMDLINE_TEST_BUFSIZE) >= 0)
+       if (cmdline_in(cl, NULL, CMDLINE_TEST_BUFSIZE) >= 0)
                goto error;
        if (cmdline_write_char(NULL, 0) >= 0)
                goto error;
@@ -188,30 +195,15 @@ test_cmdline_fns(void)
        cmdline_set_prompt(NULL, "prompt");
        cmdline_free(NULL);
        cmdline_printf(NULL, "format");
-       /* this should fail as stream handles are invalid */
-       cmdline_printf(tmp, "format");
        cmdline_interact(NULL);
        cmdline_quit(NULL);
 
-       /* check if void calls change anything when they should fail */
-       cl = *tmp;
-
-       cmdline_printf(&cl, NULL);
-       if (memcmp(&cl, tmp, sizeof(cl))) goto mismatch;
-       cmdline_set_prompt(&cl, NULL);
-       if (memcmp(&cl, tmp, sizeof(cl))) goto mismatch;
-       cmdline_in(&cl, NULL, CMDLINE_TEST_BUFSIZE);
-       if (memcmp(&cl, tmp, sizeof(cl))) goto mismatch;
-
-       cmdline_free(tmp);
-
        return 0;
 
 error:
        printf("Error: function accepted null parameter!\n");
-       return -1;
-mismatch:
-       printf("Error: data changed!\n");
+       if (cl != NULL)
+               cmdline_free(cl);
        return -1;
 }
 

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index efd771056f75d09b76b00a67377dd9f49ca17413..e9f37f3ceb89346b44a188c61a65166d1ba247dd 100644 (file)
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -222,6 +222,10 @@ Deprecation Notices
   In this case the function will return -1 unless the environment is unset first
   (using ``rte_power_unset_env``). Other function usage scenarios will not change.
 
+* cmdline: ``cmdline`` structure will be made opaque to hide platform-specific
+  content. On Linux and FreeBSD, supported prior to DPDK 20.11,
+  original structure will be kept until DPDK 21.11.
+
 * dpdk-setup.sh: This old script relies on deprecated stuff, and especially
   ``make``. Given environments are too much variables for such a simple script,
   it will be removed in DPDK 20.11.

diff --git a/lib/librte_cmdline/cmdline.c b/lib/librte_cmdline/cmdline.c
index cfd703e5b3728f823fa7e04fafdf2614b364dfbd..41f50cc56e3ad84cf80affbefefd2ffc87f3d4c4 100644 (file)
--- a/lib/librte_cmdline/cmdline.c
+++ b/lib/librte_cmdline/cmdline.c
@@ -13,13 +13,10 @@
 #include <fcntl.h>
 #include <poll.h>
 #include <errno.h>
-#include <termios.h>
 #include <netinet/in.h>
 
 #include <rte_string_fns.h>
 
-#include "cmdline_parse.h"
-#include "cmdline_rdline.h"
 #include "cmdline.h"
 
 static void
@@ -103,6 +100,12 @@ cmdline_new(cmdline_parse_ctx_t *ctx, const char *prompt, int s_in, int s_out)
        return cl;
 }
 
+struct rdline*
+cmdline_get_rdline(struct cmdline *cl)
+{
+       return &cl->rdl;
+}
+
 void
 cmdline_free(struct cmdline *cl)
 {

diff --git a/lib/librte_cmdline/cmdline.h b/lib/librte_cmdline/cmdline.h
index 243f99d2045ab5da22334892544d421f0856f89f..c29762ddae7dd24044fa16bbb6c0d0e425d8f19a 100644 (file)
--- a/lib/librte_cmdline/cmdline.h
+++ b/lib/librte_cmdline/cmdline.h
@@ -7,9 +7,13 @@
 #ifndef _CMDLINE_H_
 #define _CMDLINE_H_
 
+#ifndef RTE_EXEC_ENV_WINDOWS
+#include <termios.h>
+#endif
+
 #include <rte_common.h>
+#include <rte_compat.h>
 
-#include <termios.h>
 #include <cmdline_rdline.h>
 #include <cmdline_parse.h>
 
@@ -23,6 +27,8 @@
 extern "C" {
 #endif
 
+#ifndef RTE_EXEC_ENV_WINDOWS
+
 struct cmdline {
        int s_in;
        int s_out;
@@ -32,6 +38,12 @@ struct cmdline {
        struct termios oldterm;
 };
 
+#else
+
+struct cmdline;
+
+#endif /* RTE_EXEC_ENV_WINDOWS */
+
 struct cmdline *cmdline_new(cmdline_parse_ctx_t *ctx, const char *prompt, int s_in, int s_out);
 void cmdline_set_prompt(struct cmdline *cl, const char *prompt);
 void cmdline_free(struct cmdline *cl);
@@ -40,6 +52,10 @@ void cmdline_printf(const struct cmdline *cl, const char *fmt, ...)
 int cmdline_in(struct cmdline *cl, const char *buf, int size);
 int cmdline_write_char(struct rdline *rdl, char c);
 
+__rte_experimental
+struct rdline *
+cmdline_get_rdline(struct cmdline *cl);
+
 /**
  * This function is nonblocking equivalent of ``cmdline_interact()``. It polls
  * *cl* for one character and interpret it. If return value is *RDLINE_EXITED*

diff --git a/lib/librte_cmdline/cmdline_parse.c b/lib/librte_cmdline/cmdline_parse.c
index b57b30e8f7cb1a1f93a95491c116ed5757172bd3..f120f19dd4232be80f7b5e56ed36a1749b268fc9 100644 (file)
--- a/lib/librte_cmdline/cmdline_parse.c
+++ b/lib/librte_cmdline/cmdline_parse.c
@@ -10,14 +10,11 @@
 #include <string.h>
 #include <inttypes.h>
 #include <ctype.h>
-#include <termios.h>
 
 #include <netinet/in.h>
 
 #include <rte_string_fns.h>
 
-#include "cmdline_rdline.h"
-#include "cmdline_parse.h"
 #include "cmdline.h"
 
 #ifdef RTE_LIBRTE_CMDLINE_DEBUG

diff --git a/lib/librte_cmdline/cmdline_socket.c b/lib/librte_cmdline/cmdline_socket.c
index ecb3d82b64aa5c128a574ad7783285a4c578c1a0..6c89d2171ae7442c1c99fb465bcc1990b076dde4 100644 (file)
--- a/lib/librte_cmdline/cmdline_socket.c
+++ b/lib/librte_cmdline/cmdline_socket.c
@@ -11,12 +11,9 @@
 #include <stdarg.h>
 #include <inttypes.h>
 #include <fcntl.h>
-#include <termios.h>
 
-#include "cmdline_parse.h"
-#include "cmdline_rdline.h"
-#include "cmdline_socket.h"
 #include "cmdline.h"
+#include "cmdline_socket.h"
 
 struct cmdline *
 cmdline_file_new(cmdline_parse_ctx_t *ctx, const char *prompt, const char *path)

diff --git a/lib/librte_cmdline/rte_cmdline_version.map b/lib/librte_cmdline/rte_cmdline_version.map
index a99104457fd58de27972cc925b426eb49c64f29a..9df02721526782e990852f4ec67bc971f5b60453 100644 (file)
--- a/lib/librte_cmdline/rte_cmdline_version.map
+++ b/lib/librte_cmdline/rte_cmdline_version.map
@@ -69,3 +69,11 @@ DPDK_21 {
 
        local: *;
 };
+
+EXPERIMENTAL {
+       global:
+
+       cmdline_get_rdline;
+
+       local: *;
+};