doc/sample_app_ug: use code snippets in sample app guides
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
@@ -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
@@ -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
@@ -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
@@ -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
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/flow_classify/flow_classify.c +40 -20
60 lines not on this page · raw message
examples/flow_filtering/flow_blocks.c +21 -12
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/ipv4_multicast/main.c +30 -13
43 lines not on this page · raw message
examples/l2fwd-event/l2fwd_event_generic.c +8 -3
Lines of this file are not shown. View the raw message.
examples/l2fwd-event/l2fwd_event_internal_port.c +2 -1
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/link_status_interrupt/main.c +33 -15
48 lines not on this page · raw message
examples/multi_process/simple_mp/main.c +2 -0
Lines of this file are not shown. View the raw message.
examples/multi_process/symmetric_mp/main.c +3 -1
Lines of this file are not shown. View the raw message.
examples/server_node_efd/server/main.c +11 -3
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.
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 commit413c75c33c40("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.Signed-off-by Conor Fogarty <[email protected]>
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@@ -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
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 commit413c75c33c40("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
Signed-off-by Conor Fogarty <[email protected]>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.rstdoc/guides/sample_app_ug/flow_classify.rst ACL field definitions for the IPv4 5 tuple rule · line 67
Quoted 9 lines
index
01915971ae..812aaa87b0100644doc/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`` applicationIt 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: 308263This 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
PATCH v2 1/1 doc/sample_app_ug: use code snippets in sample app guides
In reply to Conor FogartyFrom: 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
@@ -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
@@ -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
@@ -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
@@ -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
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/flow_classify/flow_classify.c +34 -9
43 lines not on this page · raw message
examples/l2fwd-event/l2fwd_event_generic.c +8 -0
Lines of this file are not shown. View the raw message.
examples/l2fwd-event/l2fwd_event_internal_port.c +2 -1
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/multi_process/simple_mp/main.c +2 -0
Lines of this file are not shown. View the raw message.
examples/multi_process/symmetric_mp/main.c +2 -0
Lines of this file are not shown. View the raw message.
examples/server_node_efd/server/main.c +10 -1
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.
Thomas Monjalon
AppliedQuoted 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 commit413c75c33c40("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
Signed-off-by Conor Fogarty <[email protected]>Signed-off-by Conor Walsh <[email protected]>Acked-by John McNamara <[email protected]>
Applied, thanks