Rewrite the QoS metering and QoS scheduler documentation for clarity and correctness.
Changes to qos_metering.rst: - Correct duplicate "srTCM" entries to "trTCM" in the mode list - Simplify and clarify introductory text - Use imperative mood for instructions - Add Oxford commas for consistency - Remove unnecessary empty rows in tables Changes to qos_sched.rst: - Rewrite command descriptions for clarity - Improve formatting of command syntax using inline literals - Streamline bullet point structure - Remove unnecessary empty rows in tables - Make language more concise throughout Signed-off-by: Stephen Hemminger <[email protected]> --- doc/guides/sample_app_ug/qos_metering.rst | 95 ++++----- doc/guides/sample_app_ug/qos_scheduler.rst | 214 +++++++++++---------- 2 files changed, 158 insertions(+), 151 deletions(-) diff --git a/doc/guides/sample_app_ug/qos_metering.rst b/doc/guides/sample_app_ug/qos_metering.rst index e7101559aa..c6ab8f78ab 100644 --- a/doc/guides/sample_app_ug/qos_metering.rst +++ b/doc/guides/sample_app_ug/qos_metering.rst @@ -4,19 +4,22 @@ QoS Metering Sample Application =============================== -The QoS meter sample application is an example that demonstrates the use of DPDK to provide QoS marking and metering, -as defined by RFC2697 for Single Rate Three Color Marker (srTCM) and RFC 2698 for Two Rate Three Color Marker (trTCM) algorithm. +The QoS meter sample application demonstrates DPDK QoS marking and metering +using the Single Rate Three Color Marker (srTCM) algorithm defined in RFC 2697 +and the Two Rate Three Color Marker (trTCM) algorithm defined in RFC 2698. Overview -------- -The application uses a single thread for reading the packets from the RX port, -metering, marking them with the appropriate color (green, yellow or red) and writing them to the TX port. +The application uses a single thread to read packets from the RX port, +meter them, mark them with the appropriate color (green, yellow, or red), +and write them to the TX port. -A policing scheme can be applied before writing the packets to the TX port by dropping or -changing the color of the packet in a static manner depending on both the input and output colors of the packets that are processed by the meter. +A policing scheme can apply before writing packets to the TX port by dropping +or changing the packet color statically. The scheme depends on both the input +and output colors of packets processed by the meter. -The operation mode can be selected as compile time out of the following options: +Select the operation mode at compile time from the following options: * Simple forwarding @@ -24,60 +27,64 @@ The operation mode can be selected as compile time out of the following options: * srTCM color aware -* srTCM color blind +* trTCM color blind -* srTCM color aware +* trTCM color aware -Please refer to RFC2697 and RFC2698 for details about the srTCM and trTCM configurable parameters -(CIR, CBS and EBS for srTCM; CIR, PIR, CBS and PBS for trTCM). +See RFC 2697 and RFC 2698 for details about the srTCM and trTCM configurable +parameters (CIR, CBS, and EBS for srTCM; CIR, PIR, CBS, and PBS for trTCM). -The color blind modes are functionally equivalent with the color-aware modes when -all the incoming packets are colored as green. +The color blind modes function equivalently to the color aware modes when +all incoming packets are green. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. -The application is located in the ``qos_meter`` sub-directory. +The application source resides in the ``qos_meter`` sub-directory. Running the Application ----------------------- -The application execution command line is as below: +Run the application with the following command line: .. code-block:: console ./dpdk-qos_meter [EAL options] -- -p PORTMASK -The application is constrained to use a single core in the EAL core mask and 2 ports only in the application port mask -(first port from the port mask is used for RX and the other port in the core mask is used for TX). +The application requires a single core in the EAL core mask and exactly +two ports in the application port mask. The first port in the mask handles RX; +the second port handles TX. -Refer to *DPDK Getting Started Guide* for general information on running applications and -the Environment Abstraction Layer (EAL) options. +Refer to the *DPDK Getting Started Guide* for general information on running +applications and the Environment Abstraction Layer (EAL) options. Explanation ----------- -Selecting one of the metering modes is done with these defines: +Select the metering mode with these defines: .. literalinclude:: ../../../examples/qos_meter/main.c :language: c :start-after: Traffic metering configuration. 8< :end-before: >8 End of traffic metering configuration. -To simplify debugging (for example, by using the traffic generator RX side MAC address based packet filtering feature), -the color is defined as the LSB byte of the destination MAC address. +To simplify debugging (for example, when using the traffic generator's +MAC address-based packet filtering on the RX side), the application encodes +the color in the LSB of the destination MAC address. -The traffic meter parameters are configured in the application source code with following default values: +The application source code configures traffic meter parameters with the +following default values: .. literalinclude:: ../../../examples/qos_meter/main.c :language: c :start-after: Traffic meter parameters are configured in the application. 8< :end-before: >8 End of traffic meter parameters are configured in the application. -Assuming the input traffic is generated at line rate and all packets are 64 bytes Ethernet frames (IPv4 packet size of 46 bytes) -and green, the expected output traffic should be marked as shown in the following table: +Assuming the input traffic arrives at line rate with all packets as +64-byte Ethernet frames (46-byte IPv4 payload) colored green, the meter +marks the output traffic as shown in the following table: .. _table_qos_metering_1: @@ -85,53 +92,49 @@ and green, the expected output traffic should be marked as shown in the followin +-------------+------------------+-------------------+----------------+ | **Mode** | **Green (Mpps)** | **Yellow (Mpps)** | **Red (Mpps)** | - | | | | | +=============+==================+===================+================+ | srTCM blind | 1 | 1 | 12.88 | - | | | | | +-------------+------------------+-------------------+----------------+ | srTCM color | 1 | 1 | 12.88 | - | | | | | +-------------+------------------+-------------------+----------------+ | trTCM blind | 1 | 0.5 | 13.38 | - | | | | | +-------------+------------------+-------------------+----------------+ | trTCM color | 1 | 0.5 | 13.38 | - | | | | | +-------------+------------------+-------------------+----------------+ | FWD | 14.88 | 0 | 0 | - | | | | | +-------------+------------------+-------------------+----------------+ -To set up the policing scheme as desired, it is necessary to modify the main.h source file, -where this policy is implemented as a static structure, as follows: +To configure the policing scheme, modify the static structure in the main.h +source file: .. literalinclude:: ../../../examples/qos_meter/main.h :language: c :start-after: Policy implemented as a static structure. 8< :end-before: >8 End of policy implemented as a static structure. -Where rows indicate the input color, columns indicate the output color, -and the value that is stored in the table indicates the action to be taken for that particular case. +Rows indicate the input color, columns indicate the output color, and each +table entry specifies the action for that combination. -There are four different actions: +The four available actions are: -* GREEN: The packet's color is changed to green. +* GREEN: Change the packet color to green. -* YELLOW: The packet's color is changed to yellow. +* YELLOW: Change the packet color to yellow. -* RED: The packet's color is changed to red. +* RED: Change the packet color to red. -* DROP: The packet is dropped. +* DROP: Drop the packet. In this particular case: -* Every packet which input and output color are the same, keeps the same color. +* When input and output colors match, keep the same color. -* Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used). +* When the color improves (output greener than input), drop the packet. + This case cannot occur in practice, so these values go unused. -* For the rest of the cases, the color is changed to red. +* For all other cases, change the color to red. .. note:: - * In color blind mode, first row GREEN color is only valid. - * To drop the packet, policer_table action has to be set to DROP. + + In color blind mode, only the GREEN input row applies. + To drop packets, set the policer_table action to DROP. diff --git a/doc/guides/sample_app_ug/qos_scheduler.rst b/doc/guides/sample_app_ug/qos_scheduler.rst index cd33beecb0..caa2fb84cb 100644 --- a/doc/guides/sample_app_ug/qos_scheduler.rst +++ b/doc/guides/sample_app_ug/qos_scheduler.rst @@ -4,12 +4,12 @@ QoS Scheduler Sample Application ================================ -The QoS sample application demonstrates the use of the DPDK to provide QoS scheduling. +The QoS sample application demonstrates DPDK QoS scheduling. Overview -------- -The architecture of the QoS scheduler application is shown in the following figure. +The following figure shows the architecture of the QoS scheduler application. .. _figure_qos_sched_app_arch: @@ -18,110 +18,113 @@ The architecture of the QoS scheduler application is shown in the following figu QoS Scheduler Application Architecture -There are two flavors of the runtime execution for this application, -with two or three threads per each packet flow configuration being used. -The RX thread reads packets from the RX port, -classifies the packets based on the double VLAN (outer and inner) and -the lower byte of the IP destination address and puts them into the ring queue. -The worker thread dequeues the packets from the ring and calls the QoS scheduler enqueue/dequeue functions. -If a separate TX core is used, these are sent to the TX ring. -Otherwise, they are sent directly to the TX port. -The TX thread, if present, reads from the TX ring and write the packets to the TX port. +The application supports two runtime configurations: two or three threads +per packet flow. + +The RX thread reads packets from the RX port, classifies them based on +double VLAN tags (outer and inner) and the lower byte of the IP destination +address, then enqueues them to the ring. + +The worker thread dequeues packets from the ring and calls the QoS scheduler +enqueue/dequeue functions. With a separate TX core, the worker sends packets +to the TX ring. Otherwise, it sends them directly to the TX port. +The TX thread, when present, reads from the TX ring and writes packets to +the TX port. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. +To compile the sample application, see :doc:`compiling`. -The application is located in the ``qos_sched`` sub-directory. +The application source resides in the ``qos_sched`` sub-directory. - .. note:: +.. note:: - This application is intended as a linux only. + This application supports Linux only. .. note:: - Number of grinders is currently set to 8. - This can be modified by specifying RTE_SCHED_PORT_N_GRINDERS=N - in CFLAGS, where N is number of grinders. + The number of grinders defaults to 8. Modify this value by specifying + ``RTE_SCHED_PORT_N_GRINDERS=N`` in CFLAGS, where N is the desired count. Running the Application ----------------------- .. note:: - In order to run the application, a total of at least 4 - G of huge pages must be set up for each of the used sockets (depending on the cores in use). + The application requires at least 4 GB of huge pages per socket + (depending on which cores are in use). -The application has a number of command line options: +The application accepts the following command line options: .. code-block:: console ./<build_dir>/examples/dpdk-qos_sched [EAL options] -- <APP PARAMS> -Mandatory application parameters include: +Mandatory application parameters: -* --pfc "RX PORT, TX PORT, RX LCORE, WT LCORE, TX CORE": Packet flow configuration. - Multiple pfc entities can be configured in the command line, - having 4 or 5 items (if TX core defined or not). +* ``--pfc "RX PORT, TX PORT, RX LCORE, WT LCORE, TX CORE"``: Packet flow + configuration. Specify multiple pfc entries on the command line with + 4 or 5 items (depending on whether a TX core is defined). -Optional application parameters include: +Optional application parameters: -* -i: It makes the application to start in the interactive mode. - In this mode, the application shows a command line that can be used for obtaining statistics while - scheduling is taking place (see interactive mode below for more information). +* ``-i``: Start the application in interactive mode. This mode displays + a command line for obtaining statistics while scheduling runs + (see `Interactive mode`_ for details). -* --mnc n: Main core index (the default value is 1). +* ``--mnc n``: Main core index (default: 1). -* --rsz "A, B, C": Ring sizes: +* ``--rsz "A, B, C"``: Ring sizes: -* A = Size (in number of buffer descriptors) of each of the NIC RX rings read - by the I/O RX lcores (the default value is 128). + * A = Size (in buffer descriptors) of each NIC RX ring read by I/O RX + lcores (default: 128). -* B = Size (in number of elements) of each of the software rings used - by the I/O RX lcores to send packets to worker lcores (the default value is 8192). + * B = Size (in elements) of each software ring that I/O RX lcores use + to send packets to worker lcores (default: 8192). -* C = Size (in number of buffer descriptors) of each of the NIC TX rings written - by worker lcores (the default value is 256) + * C = Size (in buffer descriptors) of each NIC TX ring written by + worker lcores (default: 256). -* --bsz "A, B, C, D": Burst sizes +* ``--bsz "A, B, C, D"``: Burst sizes: -* A = I/O RX lcore read burst size from the NIC RX (the default value is 64) + * A = I/O RX lcore read burst size from NIC RX (default: 64). -* B = I/O RX lcore write burst size to the output software rings, - worker lcore read burst size from input software rings,QoS enqueue size (the default value is 64) + * B = I/O RX lcore write burst size to output software rings, worker + lcore read burst size from input software rings, and QoS enqueue + size (default: 64). -* C = QoS dequeue size (the default value is 63) + * C = QoS dequeue size (default: 63). -* D = Worker lcore write burst size to the NIC TX (the default value is 64) + * D = Worker lcore write burst size to NIC TX (default: 64). -* --msz M: Mempool size (in number of mbufs) for each pfc (default 2097152) +* ``--msz M``: Mempool size (in mbufs) for each pfc (default: 2097152). -* --rth "A, B, C": The RX queue threshold parameters +* ``--rth "A, B, C"``: RX queue threshold parameters: -* A = RX prefetch threshold (the default value is 8) + * A = RX prefetch threshold (default: 8). -* B = RX host threshold (the default value is 8) + * B = RX host threshold (default: 8). -* C = RX write-back threshold (the default value is 4) + * C = RX write-back threshold (default: 4). -* --tth "A, B, C": TX queue threshold parameters +* ``--tth "A, B, C"``: TX queue threshold parameters: -* A = TX prefetch threshold (the default value is 36) + * A = TX prefetch threshold (default: 36). -* B = TX host threshold (the default value is 0) + * B = TX host threshold (default: 0). -* C = TX write-back threshold (the default value is 0) + * C = TX write-back threshold (default: 0). -* --cfg FILE: Profile configuration to load +* ``--cfg FILE``: Profile configuration file to load. -Refer to *DPDK Getting Started Guide* for general information on running applications and -the Environment Abstraction Layer (EAL) options. +Refer to the *DPDK Getting Started Guide* for general information on running +applications and the Environment Abstraction Layer (EAL) options. -The profile configuration file defines all the port/subport/pipe/traffic class/queue parameters -needed for the QoS scheduler configuration. +The profile configuration file defines all port/subport/pipe/traffic class/queue +parameters for the QoS scheduler. -The profile file has the following format: +The profile file uses the following format: .. literalinclude:: ../../../examples/qos_sched/profile.cfg :start-after: Data Plane Development Kit (DPDK) Programmer's Guide @@ -129,89 +132,94 @@ The profile file has the following format: Interactive mode ~~~~~~~~~~~~~~~~ -These are the commands that are currently working under the command line interface: - -* Control Commands +The interactive mode supports these commands: -* --quit: Quits the application. +* Control commands: -* General Statistics + * ``quit``: Exit the application. - * stats app: Shows a table with in-app calculated statistics. +* General statistics: - * stats port X subport Y: For a specific subport, it shows the number of packets that - went through the scheduler properly and the number of packets that were dropped. - The same information is shown in bytes. - The information is displayed in a table separating it in different traffic classes. + * ``stats app``: Display a table of in-application statistics. - * stats port X subport Y pipe Z: For a specific pipe, it shows the number of packets that - went through the scheduler properly and the number of packets that were dropped. - The same information is shown in bytes. - This information is displayed in a table separating it in individual queues. + * ``stats port X subport Y``: For a specific subport, display the number + of packets (and bytes) that passed through the scheduler and the + number dropped. The table separates results by traffic class. -* Average queue size + * ``stats port X subport Y pipe Z``: For a specific pipe, display the + number of packets (and bytes) that passed through the scheduler and + the number dropped. The table separates results by queue. -All of these commands work the same way, averaging the number of packets throughout a specific subset of queues. +* Average queue size: -Two parameters can be configured for this prior to calling any of these commands: + These commands average packet counts across a subset of queues. + Configure two parameters before using these commands: - * qavg n X: n is the number of times that the calculation will take place. - Bigger numbers provide higher accuracy. The default value is 10. + * ``qavg n X``: Set the number of calculation iterations. Higher values + improve accuracy (default: 10). - * qavg period X: period is the number of microseconds that will be allowed between each calculation. - The default value is 100. + * ``qavg period X``: Set the interval in microseconds between + calculations (default: 100). -The commands that can be used for measuring average queue size are: + The queue size measurement commands are: -* qavg port X subport Y: Show average queue size per subport. + * ``qavg port X subport Y``: Display average queue size per subport. -* qavg port X subport Y tc Z: Show average queue size per subport for a specific traffic class. + * ``qavg port X subport Y tc Z``: Display average queue size per subport + for a specific traffic class. -* qavg port X subport Y pipe Z: Show average queue size per pipe. + * ``qavg port X subport Y pipe Z``: Display average queue size per pipe. -* qavg port X subport Y pipe Z tc A: Show average queue size per pipe for a specific traffic class. + * ``qavg port X subport Y pipe Z tc A``: Display average queue size per + pipe for a specific traffic class. -* qavg port X subport Y pipe Z tc A q B: Show average queue size of a specific queue. + * ``qavg port X subport Y pipe Z tc A q B``: Display average queue size + for a specific queue. Example ~~~~~~~ -The following is an example command with a single packet flow configuration: +The following command configures a single packet flow: .. code-block:: console ./<build_dir>/examples/dpdk-qos_sched -l 1,5,7 -- --pfc "3,2,5,7" --cfg ./profile.cfg -This example uses a single packet flow configuration which creates one RX thread on lcore 5 reading -from port 3 and a worker thread on lcore 7 writing to port 2. +This example creates one RX thread on lcore 5 reading from port 3 and a +worker thread on lcore 7 writing to port 2. -Another example with 2 packet flow configurations using different ports but sharing the same core for QoS scheduler is given below: +The following command configures two packet flows using different ports but +sharing the same QoS scheduler core: .. code-block:: console ./<build_dir>/examples/dpdk-qos_sched -l 1,2,6,7 -- --pfc "3,2,2,6,7" --pfc "1,0,2,6,7" --cfg ./profile.cfg -Note that independent cores for the packet flow configurations for each of the RX, WT and TX thread are also supported, -providing flexibility to balance the work. +The application also supports independent cores for RX, WT, and TX threads +in each packet flow configuration, providing flexibility to balance workloads. -The EAL corelist is constrained to contain the default main core 1 and the RX, WT and TX cores only. +The EAL corelist must contain only the default main core 1 plus the RX, WT, +and TX cores. Explanation ----------- -The Port/Subport/Pipe/Traffic Class/Queue are the hierarchical entities in a typical QoS application: +The Port/Subport/Pipe/Traffic Class/Queue hierarchy represents entities in +a typical QoS application: * A subport represents a predefined group of users. -* A pipe represents an individual user/subscriber. +* A pipe represents an individual user or subscriber. -* A traffic class is the representation of a different traffic type with a specific loss rate, - delay and jitter requirements; such as data voice, video or data transfers. +* A traffic class represents a traffic type with specific loss rate, delay, + and jitter requirements, such as voice, video, or data transfers. -* A queue hosts packets from one or multiple connections of the same type belonging to the same user. +* A queue hosts packets from one or more connections of the same type + belonging to the same user. -The traffic flows that need to be configured are application dependent. -This application classifies based on the QinQ double VLAN tags and the IP destination address as indicated in the following table. +Traffic flow configuration depends on the application. This application +classifies packets based on QinQ double VLAN tags and IP destination address +as shown in the following table. .. _table_qos_scheduler_1: @@ -219,22 +227,18 @@ This application classifies based on the QinQ double VLAN tags and the IP destin +----------------+-------------------------+--------------------------------------------------+----------------------------------+ | **Level Name** | **Siblings per Parent** | **QoS Functional Description** | **Selected By** | - | | | | | +================+=========================+==================================================+==================================+ | Port | - | Ethernet port | Physical port | - | | | | | +----------------+-------------------------+--------------------------------------------------+----------------------------------+ | Subport | Config (8) | Traffic shaped (token bucket) | Outer VLAN tag | - | | | | | +----------------+-------------------------+--------------------------------------------------+----------------------------------+ | Pipe | Config (4k) | Traffic shaped (token bucket) | Inner VLAN tag | - | | | | | +----------------+-------------------------+--------------------------------------------------+----------------------------------+ | Traffic Class | 13 | TCs of the same pipe services in strict priority | Destination IP address (0.0.0.X) | - | | | | | +----------------+-------------------------+--------------------------------------------------+----------------------------------+ | Queue | High Priority TC: 1, | Queue of lowest priority traffic | Destination IP address (0.0.0.X) | | | Lowest Priority TC: 4 | class (Best effort) serviced in WRR | | +----------------+-------------------------+--------------------------------------------------+----------------------------------+ -Please refer to the "QoS Scheduler" chapter in the *DPDK Programmer's Guide* for more information about these parameters. +For more information about these parameters, see the "QoS Scheduler" chapter +in the *DPDK Programmer's Guide*. -- 2.51.0
