Skip to contentSkip to conversation

doc/sample_app_ug: use code snippets in sample app guides

PATCH In review Conor Fogarty 5 participants 6 messages Jul 14, 2021 – Jul 31, 2021

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc/sample_app_ug: use code snippets in sample app guides

Currently the sample app user guides use hard coded code snippets, this patch changes these to use literalinclude which will dynamically update the snippets as changes are made to the code.
This was introduced in commit 413c75c33c40 ("doc: show how to include code in guides"). Comments within the sample apps were updated to accommodate this as part of this patch. This will help to ensure that the code within the sample app user guides is up to date and not out of sync with the actual code.

---
 doc/guides/contributing/documentation.rst     |   4 +-
 doc/guides/sample_app_ug/cmd_line.rst         |  64 +--
 doc/guides/sample_app_ug/flow_classify.rst    | 435 +++--------------
 doc/guides/sample_app_ug/flow_filtering.rst   | 441 ++++-------------
 doc/guides/sample_app_ug/hello_world.rst      |  53 +-
 doc/guides/sample_app_ug/ioat.rst             | 415 ++++------------
 doc/guides/sample_app_ug/ip_frag.rst          |  32 +-
 doc/guides/sample_app_ug/ip_reassembly.rst    |  67 +--
 doc/guides/sample_app_ug/ipv4_multicast.rst   | 194 ++------
 doc/guides/sample_app_ug/keep_alive.rst       |  38 +-
 doc/guides/sample_app_ug/l2_forward_cat.rst   |  20 +-
 .../sample_app_ug/l2_forward_crypto.rst       | 214 ++-------
 doc/guides/sample_app_ug/l2_forward_event.rst | 453 ++++--------------
 .../sample_app_ug/l2_forward_job_stats.rst    | 350 +++-----------
 .../sample_app_ug/l2_forward_real_virtual.rst | 260 ++--------
 doc/guides/sample_app_ug/l3_forward.rst       |  89 +---
 doc/guides/sample_app_ug/l3_forward_graph.rst | 167 +------
 .../sample_app_ug/l3_forward_power_man.rst    | 159 +-----
 doc/guides/sample_app_ug/link_status_intr.rst | 267 +++--------
 doc/guides/sample_app_ug/multi_process.rst    |  31 +-
 doc/guides/sample_app_ug/ptpclient.rst        | 116 ++---
 doc/guides/sample_app_ug/qos_metering.rst     |  42 +-
 doc/guides/sample_app_ug/qos_scheduler.rst    | 143 +-----
 doc/guides/sample_app_ug/rxtx_callbacks.rst   | 108 +----
 doc/guides/sample_app_ug/server_node_efd.rst  | 306 ++----------
 doc/guides/sample_app_ug/service_cores.rst    |  52 +-
 doc/guides/sample_app_ug/skeleton.rst         | 210 ++------
 doc/guides/sample_app_ug/timer.rst            | 133 ++---
 .../sample_app_ug/vmdq_dcb_forwarding.rst     | 144 +-----
 doc/guides/sample_app_ug/vmdq_forwarding.rst  | 113 +----
 examples/cmdline/commands.c                   |   5 +-
 examples/cmdline/main.c                       |   4 +
 examples/flow_classify/flow_classify.c        |  60 ++-
 examples/flow_filtering/flow_blocks.c         |  33 +-
 examples/flow_filtering/main.c                |  35 +-
 examples/helloworld/main.c                    |   9 +-
 examples/ioat/ioatfwd.c                       |  57 ++-
 examples/ip_fragmentation/main.c              |   7 +-
 examples/ip_reassembly/main.c                 |  13 +-
 examples/ipv4_multicast/main.c                |  43 +-
 examples/l2fwd-cat/l2fwd-cat.c                |   8 +-
 examples/l2fwd-crypto/main.c                  |  30 +-
 examples/l2fwd-event/l2fwd_common.c           |  10 +-
 examples/l2fwd-event/l2fwd_event.c            |  11 +-
 examples/l2fwd-event/l2fwd_event_generic.c    |  11 +-
 .../l2fwd-event/l2fwd_event_internal_port.c   |   3 +-
 examples/l2fwd-event/l2fwd_poll.c             |  11 +-
 examples/l2fwd-event/main.c                   |  14 +-
 examples/l2fwd-jobstats/main.c                |  60 ++-
 examples/l2fwd-keepalive/main.c               |   7 +-
 examples/l2fwd/main.c                         |  36 +-
 examples/l3fwd-graph/main.c                   |  11 +-
 examples/l3fwd-power/main.c                   |   8 +-
 examples/l3fwd/l3fwd_em.c                     |  10 +-
 examples/l3fwd/l3fwd_fib.c                    |   6 +-
 examples/l3fwd/l3fwd_lpm.c                    |   2 +
 examples/link_status_interrupt/main.c         |  48 +-
 examples/multi_process/simple_mp/main.c       |   2 +
 examples/multi_process/symmetric_mp/main.c    |   4 +-
 examples/ptpclient/ptpclient.c                |  28 +-
 examples/qos_meter/main.c                     |  10 +-
 examples/qos_meter/main.h                     |   4 +-
 examples/rxtx_callbacks/main.c                |  12 +-
 examples/server_node_efd/node/node.c          |  10 +-
 examples/server_node_efd/server/init.c        |   5 +-
 examples/server_node_efd/server/main.c        |  14 +-
 examples/service_cores/main.c                 |   2 +
 examples/skeleton/basicfwd.c                  |  30 +-
 examples/timer/main.c                         |  23 +-
 examples/vmdq/main.c                          |  16 +-
 examples/vmdq_dcb/main.c                      |  10 +-
 71 files changed, 1482 insertions(+), 4360 deletions(-)
doc/guides/contributing/documentation.rst +2 -2
index 8cbd4a0f6f..0d7c847408 100644
@@ -390,7 +390,7 @@ Code and Literal block sections
       .. literalinclude:: ../../../examples/skeleton/basicfwd.c
          :language: c
          :start-after: Display the port MAC address.
-         :end-before: Enable RX in promiscuous mode for the Ethernet device.
+         :end-before: RX port is set in promiscuous mode. 8<
          :dedent: 1
 
   This would be rendered as:
@@ -398,7 +398,7 @@ Code and Literal block sections
   .. literalinclude:: ../../../examples/skeleton/basicfwd.c
      :language: c
      :start-after: Display the port MAC address.
-     :end-before: Enable RX in promiscuous mode for the Ethernet device.
+     :end-before: RX port is set in promiscuous mode. 8<
      :dedent: 1
 
   Specifying ``:language:`` will enable syntax highlighting for the specified language.
doc/guides/sample_app_ug/cmd_line.rst +17 -47

85 lines not on this page · raw message

doc/guides/sample_app_ug/flow_classify.rst +69 -366

503 lines not on this page · raw message

doc/guides/sample_app_ug/flow_filtering.rst +100 -341

530 lines not on this page · raw message

doc/guides/sample_app_ug/hello_world.rst +18 -35

70 lines not on this page · raw message

doc/guides/sample_app_ug/ioat.rst +80 -335

506 lines not on this page · raw message

doc/guides/sample_app_ug/ip_frag.rst +8 -24
index 92d5e4aeae..5fdeb2a84e 100644
@@ -101,33 +101,17 @@ l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
 
 The default l3fwd_ipv4_route_array table is:
 
-.. code-block:: c
-
-    struct l3fwd_ipv4_route l3fwd_ipv4_route_array[] = {
-        {RTE_IPV4(100, 10, 0, 0), 16, 0},
-        {RTE_IPV4(100, 20, 0, 0), 16, 1},
-        {RTE_IPV4(100, 30, 0, 0), 16, 2},
-        {RTE_IPV4(100, 40, 0, 0), 16, 3},
-        {RTE_IPV4(100, 50, 0, 0), 16, 4},
-        {RTE_IPV4(100, 60, 0, 0), 16, 5},
-        {RTE_IPV4(100, 70, 0, 0), 16, 6},
-        {RTE_IPV4(100, 80, 0, 0), 16, 7},
-    };
+.. literalinclude:: ../../../examples/ip_fragmentation/main.c
+    :language: c
+    :start-after: Default l3fwd_ipv4_route_array table. 8<
+    :end-before: >8 End of default l3fwd_ipv4_route_array table
 
 The default l3fwd_ipv6_route_array table is:
 
-.. code-block:: c
-
-    struct l3fwd_ipv6_route l3fwd_ipv6_route_array[] = {
-        {{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 0},
-        {{2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 1},
-        {{3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 2},
-        {{4, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 3},
-        {{5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 4},
-        {{6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 5},
-        {{7, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 6},
-        {{8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 7},
-    };
+.. literalinclude:: ../../../examples/ip_fragmentation/main.c
+    :language: c
+    :start-after: Default l3fwd_ipv6_route_array table. 8<
+    :end-before: >8 End of default l3fwd_ipv6_route_array table.
 
 For example, for the input IPv4 packet with destination address: 100.10.1.1 and packet length 9198 bytes,
 seven IPv4 packets will be sent out from port #0 to the destination address 100.10.1.1:
doc/guides/sample_app_ug/ip_reassembly.rst +18 -49

88 lines not on this page · raw message

doc/guides/sample_app_ug/ipv4_multicast.rst +50 -144

242 lines not on this page · raw message

doc/guides/sample_app_ug/keep_alive.rst +15 -23
index c9392c9951..b6d75c8a80 100644
@@ -99,39 +99,31 @@ The keepalive functionality is initialized with a struct
 rte_keepalive and the callback function to invoke in the
 case of a timeout.
 
-.. code-block:: c
-
-    rte_global_keepalive_info = rte_keepalive_create(&dead_core, NULL);
-    if (rte_global_keepalive_info == NULL)
-        rte_exit(EXIT_FAILURE, "keepalive_create() failed");
+.. literalinclude:: ../../../examples/l2fwd-keepalive/main.c
+    :language: c
+    :start-after: Initialize keepalive functionality. 8<
+    :end-before: >8 End of initializing keepalive functionality.
+    :dedent: 2
 
 The function that issues the pings keepalive_dispatch_pings()
 is configured to run every check_period milliseconds.
 
-.. code-block:: c
-
-    if (rte_timer_reset(&hb_timer,
-            (check_period * rte_get_timer_hz()) / 1000,
-            PERIODICAL,
-            rte_lcore_id(),
-            &rte_keepalive_dispatch_pings,
-            rte_global_keepalive_info
-            ) != 0 )
-        rte_exit(EXIT_FAILURE, "Keepalive setup failure.\n");
+.. literalinclude:: ../../../examples/l2fwd-keepalive/main.c
+    :language: c
+    :start-after: Issues the pings keepalive_dispatch_pings(). 8<
+    :end-before: >8 End of issuing the pings keepalive_dispatch_pings().
+    :dedent: 2
 
 The rest of the initialization and run-time path follows
 the same paths as the L2 forwarding application. The only
 addition to the main processing loop is the mark alive
 functionality and the example random failures.
 
-.. code-block:: c
-
-    rte_keepalive_mark_alive(&rte_global_keepalive_info);
-    cur_tsc = rte_rdtsc();
-
-    /* Die randomly within 7 secs for demo purposes.. */
-    if (cur_tsc - tsc_initial > tsc_lifetime)
-    break;
+.. literalinclude:: ../../../examples/l2fwd-keepalive/main.c
+    :language: c
+    :start-after: Keepalive heartbeat. 8<
+    :end-before: >8 End of keepalive heartbeat.
+    :dedent: 2
 
 The rte_keepalive_mark_alive function simply sets the core state to alive.
 
doc/guides/sample_app_ug/l2_forward_cat.rst +10 -10
index c1be2d7dff..440642ef7c 100644
@@ -173,21 +173,21 @@ The first task is to initialize the Environment Abstraction Layer (EAL).  The
 ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
 function. The value returned is the number of parsed arguments:
 
-.. code-block:: c
-
-    int ret = rte_eal_init(argc, argv);
-    if (ret < 0)
-        rte_exit(EXIT_FAILURE, "Error with EAL initialization\n");
+.. literalinclude:: ../../../examples/l2fwd-cat/l2fwd-cat.c
+    :language: c
+    :start-after: Initialize the Environment Abstraction Layer (EAL). 8<
+    :end-before: >8 End of initializion the Environment Abstraction Layer (EAL).
+    :dedent: 1
 
 The next task is to initialize the PQoS library and configure CAT. The
 ``argc`` and ``argv`` arguments are provided to the ``cat_init()``
 function. The value returned is the number of parsed arguments:
 
-.. code-block:: c
-
-    int ret = cat_init(argc, argv);
-    if (ret < 0)
-        rte_exit(EXIT_FAILURE, "PQOS: L3CA init failed!\n");
+.. literalinclude:: ../../../examples/l2fwd-cat/l2fwd-cat.c
+    :language: c
+    :start-after: Initialize the PQoS. 8<
+    :end-before: >8 End of initialization of PQoS.
+    :dedent: 1
 
 ``cat_init()`` is a wrapper function which parses the command, validates
 the requested parameters and configures CAT accordingly.
doc/guides/sample_app_ug/l2_forward_crypto.rst +32 -182

245 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_event.rst +93 -360

557 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_job_stats.rst +76 -274

32 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_real_virtual.rst +52 -208

260 lines not on this page · raw message

doc/guides/sample_app_ug/l3_forward.rst +14 -75

89 lines not on this page · raw message

doc/guides/sample_app_ug/l3_forward_graph.rst +19 -148

167 lines not on this page · raw message

doc/guides/sample_app_ug/l3_forward_power_man.rst +8 -151

159 lines not on this page · raw message

doc/guides/sample_app_ug/link_status_intr.rst +59 -208

267 lines not on this page · raw message

doc/guides/sample_app_ug/multi_process.rst +10 -21
index 5eda939b82..c53331def3 100644

Lines of this file are not shown. View the raw message.

doc/guides/sample_app_ug/ptpclient.rst +34 -82

116 lines not on this page · raw message

doc/guides/sample_app_ug/qos_metering.rst +12 -30

42 lines not on this page · raw message

doc/guides/sample_app_ug/qos_scheduler.rst +2 -141

143 lines not on this page · raw message

doc/guides/sample_app_ug/rxtx_callbacks.rst +17 -91

108 lines not on this page · raw message

doc/guides/sample_app_ug/server_node_efd.rst +29 -277

306 lines not on this page · raw message

doc/guides/sample_app_ug/service_cores.rst +10 -42

52 lines not on this page · raw message

doc/guides/sample_app_ug/skeleton.rst +47 -163

210 lines not on this page · raw message

doc/guides/sample_app_ug/timer.rst +33 -100

133 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst +14 -130

144 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_forwarding.rst +18 -95

113 lines not on this page · raw message

examples/cmdline/commands.c +4 -1
index 9ce8ef389f..a81e51f698 100644

Lines of this file are not shown. View the raw message.

examples/cmdline/main.c +4 -0
index 94002f0582..c04a782507 100644

Lines of this file are not shown. View the raw message.

examples/flow_classify/flow_classify.c +40 -20

60 lines not on this page · raw message

examples/flow_filtering/flow_blocks.c +21 -12
index 575d792810..d3d46f587a 100644

Lines of this file are not shown. View the raw message.

examples/flow_filtering/main.c +32 -3
index f1940bc88d..73dc209c2a 100644

Lines of this file are not shown. View the raw message.

examples/helloworld/main.c +8 -1
index ac72145c73..af509138da 100644

Lines of this file are not shown. View the raw message.

examples/ioat/ioatfwd.c +42 -15

57 lines not on this page · raw message

examples/ip_fragmentation/main.c +4 -3
index 77a6a18d19..085dec9c77 100644

Lines of this file are not shown. View the raw message.

examples/ip_reassembly/main.c +8 -5
index ce8882a458..fce9e06a1f 100644

Lines of this file are not shown. View the raw message.

examples/ipv4_multicast/main.c +30 -13

43 lines not on this page · raw message

examples/l2fwd-cat/l2fwd-cat.c +5 -3
index 8e7eb32485..fe84a0c741 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-crypto/main.c +24 -6
index 4f51616492..a547be314b 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_common.c +7 -3
index ab341e55b2..220cb4ed88 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_event.c +8 -3
index 38d590c14c..584eef7490 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_event_generic.c +8 -3
index ca7ea11118..5680315a84 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_event_internal_port.c +2 -1
index c9a8430d00..16a52d67c9 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_poll.c +7 -4
index f7d8945a12..95dc6b8895 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/main.c +7 -7
index 0acfee4c92..aa4efe4be2 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-jobstats/main.c +44 -16

60 lines not on this page · raw message

examples/l2fwd-keepalive/main.c +6 -1
index be6616288f..4e1a17cfe4 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd/main.c +25 -11
index b775670ced..547c1a01c0 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd-graph/main.c +8 -3
index 75c2e0ef3f..a0de8ca9b4 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd-power/main.c +6 -2
index 6ce0f829dc..f761c10db4 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd/l3fwd_em.c +6 -4
index 43fc7612e7..5cc22e1d0e 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd/l3fwd_fib.c +4 -2
index d083ddfdd5..9ace6286b8 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd/l3fwd_lpm.c +2 -0
index ff1c18a442..7200160164 100644

Lines of this file are not shown. View the raw message.

examples/link_status_interrupt/main.c +33 -15

48 lines not on this page · raw message

examples/multi_process/simple_mp/main.c +2 -0
index a05404f7ed..df996f0f84 100644

Lines of this file are not shown. View the raw message.

examples/multi_process/symmetric_mp/main.c +3 -1
index 79e5c61e40..a93a6e7277 100644

Lines of this file are not shown. View the raw message.

examples/ptpclient/ptpclient.c +17 -11
index 173451eedc..3379dfa041 100644

Lines of this file are not shown. View the raw message.

examples/qos_meter/main.c +5 -5
index 6e724f3783..cbfdd4c169 100644

Lines of this file are not shown. View the raw message.

examples/qos_meter/main.h +2 -2
index ab20151eb6..24afc9e1d8 100644

Lines of this file are not shown. View the raw message.

examples/rxtx_callbacks/main.c +9 -3
index 192521c3c6..16bba582c9 100644

Lines of this file are not shown. View the raw message.

examples/server_node_efd/node/node.c +7 -3
index e68606e0ca..b050e05889 100644

Lines of this file are not shown. View the raw message.

examples/server_node_efd/server/init.c +4 -1
index 347737cb98..4c2926470c 100644

Lines of this file are not shown. View the raw message.

examples/server_node_efd/server/main.c +11 -3
index 39b7b6370f..15eb11ca56 100644

Lines of this file are not shown. View the raw message.

examples/service_cores/main.c +2 -0
index 2b57a52b16..83915b9a53 100644

Lines of this file are not shown. View the raw message.

examples/skeleton/basicfwd.c +23 -7
index 43b9d17a3c..478e9276d9 100644

Lines of this file are not shown. View the raw message.

examples/timer/main.c +16 -7
index d270ce49dc..5d3cf10c7a 100644

Lines of this file are not shown. View the raw message.

examples/vmdq/main.c +14 -2
index a19f7db739..1160ebea5d 100644

Lines of this file are not shown. View the raw message.

examples/vmdq_dcb/main.c +6 -4
index ba992802e9..3829654a96 100644

Lines of this file are not shown. View the raw message.

The rest of this diff is not shown. View the raw message.

Signature · 13 lines
2.25.1

--------------------------------------------------------------
Intel Research and Development Ireland Limited
Registered in Ireland
Registered Office: Collinstown Industrial Park, Leixlip, County Kildare
Registered Number: 308263


This e-mail and any attachments may contain confidential material for the sole
use of the intended recipient(s). Any review or distribution by others is
strictly prohibited. If you are not the intended recipient, please contact the
sender and delete all copies.

Part of the diff is not shown here. View the raw message.

#1 lore raw

Hello,

Quoted 11 lines · Conor Fogarty

Currently the sample app user guides use hard coded code snippets, this patch changes these to use literalinclude which will dynamically update the snippets as changes are made to the code.
This was introduced in commit 413c75c33c40 ("doc: show how to include code in guides"). Comments within the sample apps were updated to accommodate this as part of this patch. This will help to ensure that the code within the sample app user guides is up to date and not out of sync with the actual code.

Thanks for working on this cleanup.

- I see the CI reported failure on doc generation, please have a look.

- I just had a quick look at the patch, and noticed some added "cutting" comments have been merged with existing ones, even if unrelated.
Like:

+ /* Pattern 8< */
existing code we want to extract
- /* Some comments unrelated to above block */
+ /* >8 End of Pattern
+ * Some comments unrelated to above block
+ */

This will just generate code churn when such unrelated blocks (and their comments) are touched.
I would simply add /* >8 End of Pattern */ and leave existing comments untouched.

- Did you check this patch generate the same doc outputs?

Quoted 65 lines
---
 doc/guides/contributing/documentation.rst     |   4 +-
 doc/guides/sample_app_ug/cmd_line.rst         |  64 +--
 doc/guides/sample_app_ug/flow_classify.rst    | 435 +++--------------
 doc/guides/sample_app_ug/flow_filtering.rst   | 441 ++++-------------
 doc/guides/sample_app_ug/hello_world.rst      |  53 +-
 doc/guides/sample_app_ug/ioat.rst             | 415 ++++------------
 doc/guides/sample_app_ug/ip_frag.rst          |  32 +-
 doc/guides/sample_app_ug/ip_reassembly.rst    |  67 +--
 doc/guides/sample_app_ug/ipv4_multicast.rst   | 194 ++------
 doc/guides/sample_app_ug/keep_alive.rst       |  38 +-
 doc/guides/sample_app_ug/l2_forward_cat.rst   |  20 +-
 .../sample_app_ug/l2_forward_crypto.rst       | 214 ++-------
 doc/guides/sample_app_ug/l2_forward_event.rst | 453 ++++--------------
 .../sample_app_ug/l2_forward_job_stats.rst    | 350 +++-----------
 .../sample_app_ug/l2_forward_real_virtual.rst | 260 ++--------
 doc/guides/sample_app_ug/l3_forward.rst       |  89 +---
 doc/guides/sample_app_ug/l3_forward_graph.rst | 167 +------
 .../sample_app_ug/l3_forward_power_man.rst    | 159 +-----
 doc/guides/sample_app_ug/link_status_intr.rst | 267 +++--------
 doc/guides/sample_app_ug/multi_process.rst    |  31 +-
 doc/guides/sample_app_ug/ptpclient.rst        | 116 ++---
 doc/guides/sample_app_ug/qos_metering.rst     |  42 +-
 doc/guides/sample_app_ug/qos_scheduler.rst    | 143 +-----
 doc/guides/sample_app_ug/rxtx_callbacks.rst   | 108 +----
 doc/guides/sample_app_ug/server_node_efd.rst  | 306 ++----------
 doc/guides/sample_app_ug/service_cores.rst    |  52 +-
 doc/guides/sample_app_ug/skeleton.rst         | 210 ++------
 doc/guides/sample_app_ug/timer.rst            | 133 ++---
 .../sample_app_ug/vmdq_dcb_forwarding.rst     | 144 +-----
 doc/guides/sample_app_ug/vmdq_forwarding.rst  | 113 +----
 examples/cmdline/commands.c                   |   5 +-
 examples/cmdline/main.c                       |   4 +
 examples/flow_classify/flow_classify.c        |  60 ++-
 examples/flow_filtering/flow_blocks.c         |  33 +-
 examples/flow_filtering/main.c                |  35 +-
 examples/helloworld/main.c                    |   9 +-
 examples/ioat/ioatfwd.c                       |  57 ++-
 examples/ip_fragmentation/main.c              |   7 +-
 examples/ip_reassembly/main.c                 |  13 +-
 examples/ipv4_multicast/main.c                |  43 +-
 examples/l2fwd-cat/l2fwd-cat.c                |   8 +-
 examples/l2fwd-crypto/main.c                  |  30 +-
 examples/l2fwd-event/l2fwd_common.c           |  10 +-
 examples/l2fwd-event/l2fwd_event.c            |  11 +-
 examples/l2fwd-event/l2fwd_event_generic.c    |  11 +-
 .../l2fwd-event/l2fwd_event_internal_port.c   |   3 +-
 examples/l2fwd-event/l2fwd_poll.c             |  11 +-
 examples/l2fwd-event/main.c                   |  14 +-
 examples/l2fwd-jobstats/main.c                |  60 ++-
 examples/l2fwd-keepalive/main.c               |   7 +-
 examples/l2fwd/main.c                         |  36 +-
 examples/l3fwd-graph/main.c                   |  11 +-
 examples/l3fwd-power/main.c                   |   8 +-
 examples/l3fwd/l3fwd_em.c                     |  10 +-
 examples/l3fwd/l3fwd_fib.c                    |   6 +-
 examples/l3fwd/l3fwd_lpm.c                    |   2 +
 examples/link_status_interrupt/main.c         |  48 +-
 examples/multi_process/simple_mp/main.c       |   2 +
 examples/multi_process/symmetric_mp/main.c    |   4 +-
 examples/ptpclient/ptpclient.c                |  28 +-
 examples/qos_meter/main.c                     |  10 +-
 examples/qos_meter/main.h                     |   4 +-
 examples/rxtx_callbacks/main.c                |  12 +-
 examples/server_node_efd/node/node.c          |  10 +-
Quoted 8 lines
 examples/server_node_efd/server/init.c        |   5 +-
 examples/server_node_efd/server/main.c        |  14 +-
 examples/service_cores/main.c                 |   2 +
 examples/skeleton/basicfwd.c                  |  30 +-
 examples/timer/main.c                         |  23 +-
 examples/vmdq/main.c                          |  16 +-
 examples/vmdq_dcb/main.c                      |  10 +-
 71 files changed, 1482 insertions(+), 4360 deletions(-)

Nice diffstat.

[snip]

doc/guides/sample_app_ug/flow_classify.rst ACL field definitions for the IPv4 5 tuple rule · line 67

Quoted 10 lines
doc/guides/sample_app_ug/flow_classify.rst +1 -1
index 01915971ae..812aaa87b0 100644
@@ -64,81 +64,12 @@ ACL field definitions for the IPv4 5 tuple rule
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following field definitions are used when creating the ACL table during
-initialisation of the ``Flow Classify`` application..
+initialisation of the ``Flow Classify`` application

It seems unrelated.
At least leave one final '.'.

Quoted 6 lines
doc/guides/sample_app_ug/flow_classify.rst +0 -5
-.. code-block:: c
-
-     enum {
-         PROTO_FIELD_IPV4,
-         SRC_FIELD_IPV4,

[snip]

Quoted 8 lines

--------------------------------------------------------------
Intel Research and Development Ireland Limited
Registered in Ireland
Registered Office: Collinstown Industrial Park, Leixlip, County Kildare Registered Number: 308263

Quoted 4 lines

This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.

Please get this trailer removed.

Signature · 1 line
David Marchand
#2 lore raw
Quoted 1 line

Hello,

Hi David, thanks for your reply I will be handling this as Conor Fogarty is OOO.

Quoted 13 lines
Quoted 10 lines · Conor Fogarty

Currently the sample app user guides use hard coded code snippets, this patch changes these to use literalinclude which will dynamically update the snippets as changes are made to the code.
This was introduced in commit 413c75c33c40 ("doc: show how to include code in guides"). Comments within the sample apps were updated to accommodate this as part of this patch. This will help to ensure that the code within the sample app user guides is up to date and not out of sync with the actual code.

Quoted 5 lines
Quoted 1 line

Thanks for working on this cleanup.

- I see the CI reported failure on doc generation, please have a look.

This will be fixed in v2

Quoted 14 lines

- I just had a quick look at the patch, and noticed some added "cutting" comments have been merged with existing ones, even if unrelated.
Like:

+ /* Pattern 8< */
existing code we want to extract
- /* Some comments unrelated to above block */
+ /* >8 End of Pattern

(quoted diff) +2 -0
+  * Some comments unrelated to above block
+  */
Quoted 4 lines

This will just generate code churn when such unrelated blocks (and their comments) are touched.
I would simply add /* >8 End of Pattern */ and leave existing comments untouched.

I will change this in v2, unrelated comments and doc tags will not be entangled.

Quoted 3 lines

- Did you check this patch generate the same doc outputs?

The output seems to be the same, some code snippets that no longer exist in the code base have been removed, So that should be the only difference observable from the doc output.

V2 coming soon!

Thanks,
Conor.

Quoted 125 lines
Quoted 67 lines

---
 doc/guides/contributing/documentation.rst     |   4 +-
 doc/guides/sample_app_ug/cmd_line.rst         |  64 +--
 doc/guides/sample_app_ug/flow_classify.rst    | 435 +++--------------
 doc/guides/sample_app_ug/flow_filtering.rst   | 441 ++++-------------
 doc/guides/sample_app_ug/hello_world.rst      |  53 +-
 doc/guides/sample_app_ug/ioat.rst             | 415 ++++------------
 doc/guides/sample_app_ug/ip_frag.rst          |  32 +-
 doc/guides/sample_app_ug/ip_reassembly.rst    |  67 +--
 doc/guides/sample_app_ug/ipv4_multicast.rst   | 194 ++------
 doc/guides/sample_app_ug/keep_alive.rst       |  38 +-
 doc/guides/sample_app_ug/l2_forward_cat.rst   |  20 +-
 .../sample_app_ug/l2_forward_crypto.rst       | 214 ++-------
 doc/guides/sample_app_ug/l2_forward_event.rst | 453 ++++--------------
 .../sample_app_ug/l2_forward_job_stats.rst    | 350 +++-----------
 .../sample_app_ug/l2_forward_real_virtual.rst | 260 ++--------
 doc/guides/sample_app_ug/l3_forward.rst       |  89 +---
 doc/guides/sample_app_ug/l3_forward_graph.rst | 167 +------
 .../sample_app_ug/l3_forward_power_man.rst    | 159 +-----
 doc/guides/sample_app_ug/link_status_intr.rst | 267 +++--------
 doc/guides/sample_app_ug/multi_process.rst    |  31 +-
 doc/guides/sample_app_ug/ptpclient.rst        | 116 ++---
 doc/guides/sample_app_ug/qos_metering.rst     |  42 +-
 doc/guides/sample_app_ug/qos_scheduler.rst    | 143 +-----
 doc/guides/sample_app_ug/rxtx_callbacks.rst   | 108 +----
 doc/guides/sample_app_ug/server_node_efd.rst  | 306 ++----------
 doc/guides/sample_app_ug/service_cores.rst    |  52 +-
 doc/guides/sample_app_ug/skeleton.rst         | 210 ++------
 doc/guides/sample_app_ug/timer.rst            | 133 ++---
 .../sample_app_ug/vmdq_dcb_forwarding.rst     | 144 +-----
 doc/guides/sample_app_ug/vmdq_forwarding.rst  | 113 +----
 examples/cmdline/commands.c                   |   5 +-
 examples/cmdline/main.c                       |   4 +
 examples/flow_classify/flow_classify.c        |  60 ++-
 examples/flow_filtering/flow_blocks.c         |  33 +-
 examples/flow_filtering/main.c                |  35 +-
 examples/helloworld/main.c                    |   9 +-
 examples/ioat/ioatfwd.c                       |  57 ++-
 examples/ip_fragmentation/main.c              |   7 +-
 examples/ip_reassembly/main.c                 |  13 +-
 examples/ipv4_multicast/main.c                |  43 +-
 examples/l2fwd-cat/l2fwd-cat.c                |   8 +-
 examples/l2fwd-crypto/main.c                  |  30 +-
 examples/l2fwd-event/l2fwd_common.c           |  10 +-
 examples/l2fwd-event/l2fwd_event.c            |  11 +-
 examples/l2fwd-event/l2fwd_event_generic.c    |  11 +-
 .../l2fwd-event/l2fwd_event_internal_port.c   |   3 +-
 examples/l2fwd-event/l2fwd_poll.c             |  11 +-
 examples/l2fwd-event/main.c                   |  14 +-
 examples/l2fwd-jobstats/main.c                |  60 ++-
 examples/l2fwd-keepalive/main.c               |   7 +-
 examples/l2fwd/main.c                         |  36 +-
 examples/l3fwd-graph/main.c                   |  11 +-
 examples/l3fwd-power/main.c                   |   8 +-
 examples/l3fwd/l3fwd_em.c                     |  10 +-
 examples/l3fwd/l3fwd_fib.c                    |   6 +-
 examples/l3fwd/l3fwd_lpm.c                    |   2 +
 examples/link_status_interrupt/main.c         |  48 +-
 examples/multi_process/simple_mp/main.c       |   2 +
 examples/multi_process/symmetric_mp/main.c    |   4 +-
 examples/ptpclient/ptpclient.c                |  28 +-
 examples/qos_meter/main.c                     |  10 +-
 examples/qos_meter/main.h                     |   4 +-
 examples/rxtx_callbacks/main.c                |  12 +-
 examples/server_node_efd/node/node.c          |  10 +-
Quoted 8 lines
 examples/server_node_efd/server/init.c        |   5 +-
 examples/server_node_efd/server/main.c        |  14 +-
 examples/service_cores/main.c                 |   2 +
 examples/skeleton/basicfwd.c                  |  30 +-
 examples/timer/main.c                         |  23 +-
 examples/vmdq/main.c                          |  16 +-
 examples/vmdq_dcb/main.c                      |  10 +-
 71 files changed, 1482 insertions(+), 4360 deletions(-)

Nice diffstat.

[snip]

Review

Quoted 1 line
(quoted diff) +0 -0

b/doc/guides/sample_app_ug/flow_classify.rst

doc/guides/sample_app_ug/flow_classify.rst ACL field definitions for the IPv4 5 tuple rule · line 67

Quoted 9 lines

index 01915971ae..812aaa87b0 100644

doc/guides/sample_app_ug/flow_classify.rst +1 -1
@@ -64,81 +64,12 @@ ACL field definitions for the IPv4 5 tuple rule
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following field definitions are used when creating the ACL table during
-initialisation of the ``Flow Classify`` application..
+initialisation of the ``Flow Classify`` application

It seems unrelated.
At least leave one final '.'.

Quoted 6 lines
doc/guides/sample_app_ug/flow_classify.rst +0 -5
-.. code-block:: c
-
-     enum {
-         PROTO_FIELD_IPV4,
-         SRC_FIELD_IPV4,

[snip]

Quoted 9 lines

--------------------------------------------------------------
Intel Research and Development Ireland Limited
Registered in Ireland
Registered Office: Collinstown Industrial Park, Leixlip, County Kildare Registered Number: 308263

This e-mail and any attachments may contain confidential material for the

sole

Quoted 3 lines

use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.

Please get this trailer removed.

--
David Marchand

#3 lore raw

PATCH v2 1/1 doc/sample_app_ug: use code snippets in sample app guides

In reply to Conor Fogarty

From: Conor Fogarty <[email protected]>

Currently the sample app user guides use hard coded code snippets, this patch changes these to use literalinclude which will dynamically update the snippets as changes are made to the code.
This was introduced in commit 413c75c33c40 ("doc: show how to include code in guides"). Comments within the sample apps were updated to accommodate this as part of this patch. This will help to ensure that the code within the sample app user guides is up to date and not out of sync with the actual code.

---

v2:
- Fixed compile warning.
- Unrelated comments and end tags are now separate.

---
 doc/guides/sample_app_ug/cmd_line.rst         |  64 +--
 doc/guides/sample_app_ug/flow_classify.rst    | 435 +++--------------
 doc/guides/sample_app_ug/flow_filtering.rst   | 441 ++++-------------
 doc/guides/sample_app_ug/hello_world.rst      |  53 +-
 doc/guides/sample_app_ug/ioat.rst             | 415 ++++------------
 doc/guides/sample_app_ug/ip_frag.rst          |  32 +-
 doc/guides/sample_app_ug/ip_reassembly.rst    |  67 +--
 doc/guides/sample_app_ug/ipv4_multicast.rst   | 194 ++------
 doc/guides/sample_app_ug/keep_alive.rst       |  38 +-
 doc/guides/sample_app_ug/l2_forward_cat.rst   |  20 +-
 .../sample_app_ug/l2_forward_crypto.rst       | 214 ++-------
 doc/guides/sample_app_ug/l2_forward_event.rst | 453 ++++--------------
 .../sample_app_ug/l2_forward_job_stats.rst    | 350 +++-----------
 .../sample_app_ug/l2_forward_real_virtual.rst | 260 ++--------
 doc/guides/sample_app_ug/l3_forward.rst       |  89 +---
 doc/guides/sample_app_ug/l3_forward_graph.rst | 167 +------
 .../sample_app_ug/l3_forward_power_man.rst    | 159 +-----
 doc/guides/sample_app_ug/link_status_intr.rst | 267 +++--------
 doc/guides/sample_app_ug/multi_process.rst    |  31 +-
 doc/guides/sample_app_ug/ptpclient.rst        | 116 ++---
 doc/guides/sample_app_ug/qos_metering.rst     |  42 +-
 doc/guides/sample_app_ug/qos_scheduler.rst    | 143 +-----
 doc/guides/sample_app_ug/rxtx_callbacks.rst   | 108 +----
 doc/guides/sample_app_ug/server_node_efd.rst  | 306 ++----------
 doc/guides/sample_app_ug/service_cores.rst    |  52 +-
 doc/guides/sample_app_ug/skeleton.rst         | 210 ++------
 doc/guides/sample_app_ug/timer.rst            | 133 ++---
 .../sample_app_ug/vmdq_dcb_forwarding.rst     | 144 +-----
 doc/guides/sample_app_ug/vmdq_forwarding.rst  | 113 +----
 examples/cmdline/commands.c                   |   4 +
 examples/cmdline/main.c                       |   4 +
 examples/flow_classify/flow_classify.c        |  43 +-
 examples/flow_filtering/flow_blocks.c         |  22 +-
 examples/flow_filtering/main.c                |  27 +-
 examples/helloworld/main.c                    |   9 +-
 examples/ioat/ioatfwd.c                       |  36 +-
 examples/ip_fragmentation/main.c              |   4 +
 examples/ip_reassembly/main.c                 |   8 +
 examples/ipv4_multicast/main.c                |  31 +-
 examples/l2fwd-cat/l2fwd-cat.c                |   6 +-
 examples/l2fwd-crypto/main.c                  |  21 +-
 examples/l2fwd-event/l2fwd_common.c           |   8 +-
 examples/l2fwd-event/l2fwd_event.c            |   9 +-
 examples/l2fwd-event/l2fwd_event_generic.c    |   8 +
 .../l2fwd-event/l2fwd_event_internal_port.c   |   3 +-
 examples/l2fwd-event/l2fwd_poll.c             |   9 +-
 examples/l2fwd-event/main.c                   |   9 +-
 examples/l2fwd-jobstats/main.c                |  50 +-
 examples/l2fwd-keepalive/main.c               |   7 +-
 examples/l2fwd/main.c                         |  27 +-
 examples/l3fwd-graph/main.c                   |  11 +-
 examples/l3fwd-power/main.c                   |   5 +-
 examples/l3fwd/l3fwd_em.c                     |   7 +-
 examples/l3fwd/l3fwd_fib.c                    |   3 +-
 examples/l3fwd/l3fwd_lpm.c                    |   2 +
 examples/link_status_interrupt/main.c         |  31 +-
 examples/multi_process/simple_mp/main.c       |   2 +
 examples/multi_process/symmetric_mp/main.c    |   2 +
 examples/ptpclient/ptpclient.c                |  19 +-
 examples/qos_meter/main.c                     |   8 +-
 examples/qos_meter/main.h                     |   2 +
 examples/rxtx_callbacks/main.c                |   9 +
 examples/server_node_efd/node/node.c          |   7 +
 examples/server_node_efd/server/init.c        |   3 +
 examples/server_node_efd/server/main.c        |  11 +-
 examples/service_cores/main.c                 |   2 +
 examples/skeleton/basicfwd.c                  |  27 +-
 examples/timer/main.c                         |  21 +-
 examples/vmdq/main.c                          |  13 +
 examples/vmdq_dcb/main.c                      |   8 +-
 70 files changed, 1406 insertions(+), 4248 deletions(-)
doc/guides/sample_app_ug/cmd_line.rst +17 -47
index 5e3a25a317..6655b1e5a7 100644
@@ -68,21 +68,18 @@ EAL Initialization and cmdline Start
 The first task is the initialization of the Environment Abstraction Layer (EAL).
 This is achieved as follows:
 
-.. code-block:: c
-
-    int main(int argc, char **argv)
-    {
-        ret = rte_eal_init(argc, argv);
-        if (ret < 0)
-            rte_panic("Cannot init EAL\n");
+.. literalinclude:: ../../../examples/cmdline/main.c
+    :language: c
+    :start-after: Initialization of the Environment Abstraction Layer (EAL). 8<
+    :end-before: >8 End of initialization of Environment Abstraction Layer (EAL).
 
 Then, a new command line object is created and started to interact with the user through the console:
 
-.. code-block:: c
-
-    cl = cmdline_stdin_new(main_ctx, "example> ");
-    cmdline_interact(cl);
-    cmdline_stdin_exit(cl);
+.. literalinclude:: ../../../examples/cmdline/main.c
+    :language: c
+    :start-after: Creating a new command line object. 8<
+    :end-before: >8 End of creating a new command line object.
+    :dedent: 1
 
 The cmd line_interact() function returns when the user types **Ctrl-d** and in this case,
 the application exits.
@@ -92,14 +89,10 @@ Defining a cmdline Context
 
 A cmdline context is a list of commands that are listed in a NULL-terminated table, for example:
 
-.. code-block:: c
-
-    cmdline_parse_ctx_t main_ctx[] = {
-        (cmdline_parse_inst_t *) &cmd_obj_del_show,
-        (cmdline_parse_inst_t *) &cmd_obj_add,
-        (cmdline_parse_inst_t *) &cmd_help,
-         NULL,
-    };
+.. literalinclude:: ../../../examples/cmdline/commands.c
+    :language: c
+    :start-after: Cmdline context list of commands in NULL-terminated table. 8<
+    :end-before: >8 End of context list.
 
 Each command (of type cmdline_parse_inst_t) is defined statically.
 It contains a pointer to a callback function that is executed when the command is parsed,
@@ -120,33 +113,10 @@ in the parse_obj_list.c and parse_obj_list.h files.
 
 For example, the cmd_obj_del_show command is defined as shown below:
 
-.. code-block:: c
-
-    struct cmd_obj_add_result {
-        cmdline_fixed_string_t action;
-        cmdline_fixed_string_t name;
-        struct object *obj;
-    };
-
-    static void cmd_obj_del_show_parsed(void *parsed_result, struct cmdline *cl, __rte_unused void *data)
-    {
-       /* ... */
-    }
-
-    cmdline_parse_token_string_t cmd_obj_action = TOKEN_STRING_INITIALIZER(struct cmd_obj_del_show_result, action, "show#del");
-
-    parse_token_obj_list_t cmd_obj_obj = TOKEN_OBJ_LIST_INITIALIZER(struct cmd_obj_del_show_result, obj, &global_obj_list);
-
-    cmdline_parse_inst_t cmd_obj_del_show = {
-        .f = cmd_obj_del_show_parsed, /* function to call */
-        .data = NULL,  /* 2nd arg of func */
-        .help_str = "Show/del an object",
-        .tokens = { /* token list, NULL terminated */
-            (void *)&cmd_obj_action,
-            (void *)&cmd_obj_obj,
-             NULL,
-        },
-    };
+.. literalinclude:: ../../../examples/cmdline/commands.c
+    :language: c
+    :start-after: Show or delete tokens. 8<
+    :end-before: >8 End of show or delete tokens.
 
 This command is composed of two tokens:
 
doc/guides/sample_app_ug/flow_classify.rst +69 -366

503 lines not on this page · raw message

doc/guides/sample_app_ug/flow_filtering.rst +100 -341

530 lines not on this page · raw message

doc/guides/sample_app_ug/hello_world.rst +18 -35

70 lines not on this page · raw message

doc/guides/sample_app_ug/ioat.rst +80 -335

506 lines not on this page · raw message

doc/guides/sample_app_ug/ip_frag.rst +8 -24
index 92d5e4aeae..5fdeb2a84e 100644
@@ -101,33 +101,17 @@ l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
 
 The default l3fwd_ipv4_route_array table is:
 
-.. code-block:: c
-
-    struct l3fwd_ipv4_route l3fwd_ipv4_route_array[] = {
-        {RTE_IPV4(100, 10, 0, 0), 16, 0},
-        {RTE_IPV4(100, 20, 0, 0), 16, 1},
-        {RTE_IPV4(100, 30, 0, 0), 16, 2},
-        {RTE_IPV4(100, 40, 0, 0), 16, 3},
-        {RTE_IPV4(100, 50, 0, 0), 16, 4},
-        {RTE_IPV4(100, 60, 0, 0), 16, 5},
-        {RTE_IPV4(100, 70, 0, 0), 16, 6},
-        {RTE_IPV4(100, 80, 0, 0), 16, 7},
-    };
+.. literalinclude:: ../../../examples/ip_fragmentation/main.c
+    :language: c
+    :start-after: Default l3fwd_ipv4_route_array table. 8<
+    :end-before: >8 End of default l3fwd_ipv4_route_array table
 
 The default l3fwd_ipv6_route_array table is:
 
-.. code-block:: c
-
-    struct l3fwd_ipv6_route l3fwd_ipv6_route_array[] = {
-        {{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 0},
-        {{2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 1},
-        {{3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 2},
-        {{4, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 3},
-        {{5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 4},
-        {{6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 5},
-        {{7, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 6},
-        {{8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 7},
-    };
+.. literalinclude:: ../../../examples/ip_fragmentation/main.c
+    :language: c
+    :start-after: Default l3fwd_ipv6_route_array table. 8<
+    :end-before: >8 End of default l3fwd_ipv6_route_array table.
 
 For example, for the input IPv4 packet with destination address: 100.10.1.1 and packet length 9198 bytes,
 seven IPv4 packets will be sent out from port #0 to the destination address 100.10.1.1:
doc/guides/sample_app_ug/ip_reassembly.rst +18 -49

88 lines not on this page · raw message

doc/guides/sample_app_ug/ipv4_multicast.rst +50 -144

242 lines not on this page · raw message

doc/guides/sample_app_ug/keep_alive.rst +15 -23
index c9392c9951..b6d75c8a80 100644
@@ -99,39 +99,31 @@ The keepalive functionality is initialized with a struct
 rte_keepalive and the callback function to invoke in the
 case of a timeout.
 
-.. code-block:: c
-
-    rte_global_keepalive_info = rte_keepalive_create(&dead_core, NULL);
-    if (rte_global_keepalive_info == NULL)
-        rte_exit(EXIT_FAILURE, "keepalive_create() failed");
+.. literalinclude:: ../../../examples/l2fwd-keepalive/main.c
+    :language: c
+    :start-after: Initialize keepalive functionality. 8<
+    :end-before: >8 End of initializing keepalive functionality.
+    :dedent: 2
 
 The function that issues the pings keepalive_dispatch_pings()
 is configured to run every check_period milliseconds.
 
-.. code-block:: c
-
-    if (rte_timer_reset(&hb_timer,
-            (check_period * rte_get_timer_hz()) / 1000,
-            PERIODICAL,
-            rte_lcore_id(),
-            &rte_keepalive_dispatch_pings,
-            rte_global_keepalive_info
-            ) != 0 )
-        rte_exit(EXIT_FAILURE, "Keepalive setup failure.\n");
+.. literalinclude:: ../../../examples/l2fwd-keepalive/main.c
+    :language: c
+    :start-after: Issues the pings keepalive_dispatch_pings(). 8<
+    :end-before: >8 End of issuing the pings keepalive_dispatch_pings().
+    :dedent: 2
 
 The rest of the initialization and run-time path follows
 the same paths as the L2 forwarding application. The only
 addition to the main processing loop is the mark alive
 functionality and the example random failures.
 
-.. code-block:: c
-
-    rte_keepalive_mark_alive(&rte_global_keepalive_info);
-    cur_tsc = rte_rdtsc();
-
-    /* Die randomly within 7 secs for demo purposes.. */
-    if (cur_tsc - tsc_initial > tsc_lifetime)
-    break;
+.. literalinclude:: ../../../examples/l2fwd-keepalive/main.c
+    :language: c
+    :start-after: Keepalive heartbeat. 8<
+    :end-before: >8 End of keepalive heartbeat.
+    :dedent: 2
 
 The rte_keepalive_mark_alive function simply sets the core state to alive.
 
doc/guides/sample_app_ug/l2_forward_cat.rst +10 -10
index c1be2d7dff..440642ef7c 100644
@@ -173,21 +173,21 @@ The first task is to initialize the Environment Abstraction Layer (EAL).  The
 ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
 function. The value returned is the number of parsed arguments:
 
-.. code-block:: c
-
-    int ret = rte_eal_init(argc, argv);
-    if (ret < 0)
-        rte_exit(EXIT_FAILURE, "Error with EAL initialization\n");
+.. literalinclude:: ../../../examples/l2fwd-cat/l2fwd-cat.c
+    :language: c
+    :start-after: Initialize the Environment Abstraction Layer (EAL). 8<
+    :end-before: >8 End of initializion the Environment Abstraction Layer (EAL).
+    :dedent: 1
 
 The next task is to initialize the PQoS library and configure CAT. The
 ``argc`` and ``argv`` arguments are provided to the ``cat_init()``
 function. The value returned is the number of parsed arguments:
 
-.. code-block:: c
-
-    int ret = cat_init(argc, argv);
-    if (ret < 0)
-        rte_exit(EXIT_FAILURE, "PQOS: L3CA init failed!\n");
+.. literalinclude:: ../../../examples/l2fwd-cat/l2fwd-cat.c
+    :language: c
+    :start-after: Initialize the PQoS. 8<
+    :end-before: >8 End of initialization of PQoS.
+    :dedent: 1
 
 ``cat_init()`` is a wrapper function which parses the command, validates
 the requested parameters and configures CAT accordingly.
doc/guides/sample_app_ug/l2_forward_crypto.rst +32 -182

245 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_event.rst +93 -360

557 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_job_stats.rst +76 -274

48 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_real_virtual.rst +52 -208

260 lines not on this page · raw message

doc/guides/sample_app_ug/l3_forward.rst +14 -75

89 lines not on this page · raw message

doc/guides/sample_app_ug/l3_forward_graph.rst +19 -148

167 lines not on this page · raw message

doc/guides/sample_app_ug/l3_forward_power_man.rst +8 -151

159 lines not on this page · raw message

doc/guides/sample_app_ug/link_status_intr.rst +59 -208

267 lines not on this page · raw message

doc/guides/sample_app_ug/multi_process.rst +10 -21
index 5eda939b82..c53331def3 100644

Lines of this file are not shown. View the raw message.

doc/guides/sample_app_ug/ptpclient.rst +34 -82

116 lines not on this page · raw message

doc/guides/sample_app_ug/qos_metering.rst +12 -30

42 lines not on this page · raw message

doc/guides/sample_app_ug/qos_scheduler.rst +2 -141

143 lines not on this page · raw message

doc/guides/sample_app_ug/rxtx_callbacks.rst +17 -91

108 lines not on this page · raw message

doc/guides/sample_app_ug/server_node_efd.rst +29 -277

306 lines not on this page · raw message

doc/guides/sample_app_ug/service_cores.rst +10 -42

52 lines not on this page · raw message

doc/guides/sample_app_ug/skeleton.rst +47 -163

210 lines not on this page · raw message

doc/guides/sample_app_ug/timer.rst +33 -100

133 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst +14 -130

144 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_forwarding.rst +18 -95

113 lines not on this page · raw message

examples/cmdline/commands.c +4 -0
index 9ce8ef389f..aec151d089 100644

Lines of this file are not shown. View the raw message.

examples/cmdline/main.c +4 -0
index 94002f0582..c04a782507 100644

Lines of this file are not shown. View the raw message.

examples/flow_classify/flow_classify.c +34 -9

43 lines not on this page · raw message

examples/flow_filtering/flow_blocks.c +17 -5
index 575d792810..3251ed9f8f 100644

Lines of this file are not shown. View the raw message.

examples/flow_filtering/main.c +26 -1
index f1940bc88d..29fb4b3d55 100644

Lines of this file are not shown. View the raw message.

examples/helloworld/main.c +8 -1
index ac72145c73..af509138da 100644

Lines of this file are not shown. View the raw message.

examples/ioat/ioatfwd.c +30 -6
index 2e377e2d4b..0c413180f8 100644

Lines of this file are not shown. View the raw message.

examples/ip_fragmentation/main.c +4 -0
index 77a6a18d19..f245369720 100644

Lines of this file are not shown. View the raw message.

examples/ip_reassembly/main.c +8 -0
index ce8882a458..8645ac790b 100644

Lines of this file are not shown. View the raw message.

examples/ipv4_multicast/main.c +26 -5
index fd6207a18b..cc527d7f6b 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-cat/l2fwd-cat.c +5 -1
index 8e7eb32485..95de29b868 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-crypto/main.c +18 -3
index 4f51616492..fb113a0971 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_common.c +7 -1
index ab341e55b2..b8c1e02d75 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_event.c +8 -1
index 38d590c14c..7ba5311d66 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_event_generic.c +8 -0
index ca7ea11118..c19b6f1411 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_event_internal_port.c +2 -1
index c9a8430d00..16a52d67c9 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/l2fwd_poll.c +6 -3
index f7d8945a12..73fefac67b 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-event/main.c +6 -3
index 0acfee4c92..1db89f2bd1 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd-jobstats/main.c +38 -12

50 lines not on this page · raw message

examples/l2fwd-keepalive/main.c +6 -1
index be6616288f..4e1a17cfe4 100644

Lines of this file are not shown. View the raw message.

examples/l2fwd/main.c +21 -6
index b775670ced..911e40c66e 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd-graph/main.c +8 -3
index 75c2e0ef3f..a0de8ca9b4 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd-power/main.c +4 -1
index 6ce0f829dc..aa7b8db44a 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd/l3fwd_em.c +4 -3
index 43fc7612e7..2a8ab6aab5 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd/l3fwd_fib.c +2 -1
index d083ddfdd5..f8d6a3ac39 100644

Lines of this file are not shown. View the raw message.

examples/l3fwd/l3fwd_lpm.c +2 -0
index ff1c18a442..7200160164 100644

Lines of this file are not shown. View the raw message.

examples/link_status_interrupt/main.c +24 -7
index d8ff5f133b..7470aa539a 100644

Lines of this file are not shown. View the raw message.

examples/multi_process/simple_mp/main.c +2 -0
index a05404f7ed..df996f0f84 100644

Lines of this file are not shown. View the raw message.

examples/multi_process/symmetric_mp/main.c +2 -0
index 79e5c61e40..01dc3acf34 100644

Lines of this file are not shown. View the raw message.

examples/ptpclient/ptpclient.c +15 -4
index 173451eedc..4f32ade7fb 100644

Lines of this file are not shown. View the raw message.

examples/qos_meter/main.c +4 -4
index 6e724f3783..7ffccc8369 100644

Lines of this file are not shown. View the raw message.

examples/qos_meter/main.h +2 -0
index ab20151eb6..864f019f69 100644

Lines of this file are not shown. View the raw message.

examples/rxtx_callbacks/main.c +9 -0
index 192521c3c6..6f20f98b2b 100644

Lines of this file are not shown. View the raw message.

examples/server_node_efd/node/node.c +7 -0
index e68606e0ca..4580a44e3e 100644

Lines of this file are not shown. View the raw message.

examples/server_node_efd/server/init.c +3 -0
index 347737cb98..9ebd88bac2 100644

Lines of this file are not shown. View the raw message.

examples/server_node_efd/server/main.c +10 -1
index 39b7b6370f..7d07131dbf 100644

Lines of this file are not shown. View the raw message.

examples/service_cores/main.c +2 -0
index 2b57a52b16..83915b9a53 100644

Lines of this file are not shown. View the raw message.

examples/skeleton/basicfwd.c +22 -5
index 43b9d17a3c..ae08261bef 100644

Lines of this file are not shown. View the raw message.

examples/timer/main.c +15 -6
index d270ce49dc..a349846c7c 100644

Lines of this file are not shown. View the raw message.

examples/vmdq/main.c +13 -0
index a19f7db739..d3bc19f78e 100644

Lines of this file are not shown. View the raw message.

examples/vmdq_dcb/main.c +6 -2
index ba992802e9..685a03bdd1 100644

Lines of this file are not shown. View the raw message.

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.25.1

Part of the diff is not shown here. View the raw message.

#5 lore raw
Quoted 9 lines

Currently the sample app user guides use hard coded code snippets, this patch changes these to use literalinclude which will dynamically update the snippets as changes are made to the code.
This was introduced in commit 413c75c33c40 ("doc: show how to include code in guides"). Comments within the sample apps were updated to accommodate this as part of this patch. This will help to ensure that the code within the sample app user guides is up to date and not out of sync with the actual code.

Quoted 3 lines

Applied, thanks