doc/eventdev: correct grammar and style issues
PATCH 1/1 doc/eventdev: correct grammar and style issues
Use AI review to find and address various documentation issues in the eventdev programmer's guide:
Grammar
- Fix subject-verb agreement in multiple places
- Fix article usage ("a" vs "an" before consonant/vowel sounds)
- Fix relative pronoun usage ("which" vs "that")
- Replace nonstandard verb "invocated" with "invoked"
Spelling
- Fix "setup up" to "set up"
- Fix "as show below" to "as shown below" (multiple files)
- Fix "rte mbuf" to "rte_mbuf"
- Fix "rte_mbufs" to "rte_mbuf"
- Fix missing backtick in RST markup
Style
- Capitalize "api" to "API"
- Replace informal "For e.g," with "For example,"
- Remove extra whitespace
- Fix "benefit of" to "benefit from"
- Clarify awkward phrasing
Code example
- Fix invalid switch syntax "case default:" to "default:"
Path corrections
- Update outdated library path from libs/librte_eventdev to lib/eventdev
--- .../prog_guide/eventdev/dispatcher_lib.rst | 10 ++++----- .../eventdev/event_crypto_adapter.rst | 8 +++---- .../prog_guide/eventdev/event_dma_adapter.rst | 4 ++-- .../eventdev/event_ethernet_rx_adapter.rst | 18 +++++++-------- .../eventdev/event_ethernet_tx_adapter.rst | 4 ++-- doc/guides/prog_guide/eventdev/eventdev.rst | 22 +++++++++---------- 6 files changed, 33 insertions(+), 33 deletions(-)
doc/guides/prog_guide/eventdev/dispatcher_lib.rst +5 -5
@@ -191,7 +191,7 @@ The event handler interface consists of two function pointers: An event handler registration is valid on all lcores. -The functions pointed to by the match and process callbacks resides in +The functions pointed to by the match and process callbacks reside in the application's domain logic, with one or more handlers per application module.
@@ -215,7 +215,7 @@ An event is routed to no more than one handler. Thus, if a match function returns true, no further match functions will be invoked for that event. -Match functions must not depend on being invocated in any particular +Match functions must not depend on being invoked in any particular order (e.g., in the handler registration order). Events failing to match any handler are dropped, and the
@@ -224,15 +224,15 @@ Events failing to match any handler are dropped, and the Event Delivery ^^^^^^^^^^^^^^ -The handler callbacks are invocated by the dispatcher's service +The handler callbacks are invoked by the dispatcher's service function, upon the arrival of events to the event ports bound to the running service lcore. A particular event is delivered to at most one handler. The application must not depend on all match callback invocations for -a particular event batch being made prior to any process calls are -being made. For example, if the dispatcher dequeues two events from +a particular event batch being made before any process calls are +made. For example, if the dispatcher dequeues two events from the event device, it may choose to find out the destination for the first event, and deliver it, and then continue to find out the destination for the second, and then deliver that event as well. The
doc/guides/prog_guide/eventdev/event_crypto_adapter.rst +4 -4
@@ -7,8 +7,8 @@ Event Crypto Adapter Library The DPDK :doc:`Eventdev library <eventdev>` provides event driven programming model with features to schedule events. The :doc:`../cryptodev_lib` provides an interface to -the crypto poll mode drivers which supports different crypto operations. -The Event Crypto Adapter is one of the adapter which is intended to +the crypto poll mode drivers that support different crypto operations. +The Event Crypto Adapter is one of the adapters that is intended to bridge between the event device and the crypto device. The packet flow from crypto device to the event device can be accomplished
@@ -115,7 +115,7 @@ Adapter can be started in ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` or If the application desires to have finer control of eventdev port allocation and setup, it can use the ``rte_event_crypto_adapter_create_ext()`` function. -The ``rte_event_crypto_adapter_create_ext()`` function is passed as a callback +The ``rte_event_crypto_adapter_create_ext()`` function is passed a callback function. The callback function is invoked if the adapter needs to use a service function and needs to create an event port for it. The callback is expected to fill the ``struct rte_event_crypto_adapter_conf`` structure
@@ -229,7 +229,7 @@ Configure the service function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the adapter uses a service function, the application is required to assign -a service core to the service function as show below. +a service core to the service function as shown below. .. code-block:: c
doc/guides/prog_guide/eventdev/event_dma_adapter.rst +2 -2
@@ -36,7 +36,7 @@ RTE_EVENT_DMA_ADAPTER_OP_NEW mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the ``RTE_EVENT_DMA_ADAPTER_OP_NEW`` mode, -application submits DMA operations directly to an DMA device. +application submits DMA operations directly to a DMA device. The adapter then dequeues DMA completions from the DMA device and enqueues them as events to the event device. This mode does not ensure ingress ordering
@@ -230,7 +230,7 @@ Configuring service function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the adapter uses a service function, the application is required -to assign a service core to the service function as show below. +to assign a service core to the service function as shown below. .. code-block:: c
doc/guides/prog_guide/eventdev/event_ethernet_rx_adapter.rst +9 -9
@@ -63,7 +63,7 @@ expected to fill the ``struct rte_event_eth_rx_adapter_conf structure`` passed to it. If the application desires to control the event buffer size at adapter level, -it can use the ``rte_event_eth_rx_adapter_create_with_params()`` api. The event +it can use the ``rte_event_eth_rx_adapter_create_with_params()`` API. The event buffer size is specified using ``struct rte_event_eth_rx_adapter_params:: event_buf_size``. To configure the event buffer size at queue level, the boolean flag ``struct rte_event_eth_rx_adapter_params::use_queue_event_buf`` need to be
@@ -170,7 +170,7 @@ Querying Adapter Capabilities The ``rte_event_eth_rx_adapter_caps_get()`` function allows the application to query the adapter capabilities for an eventdev and ethdev -combination. For e.g, if the ``RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID`` +combination. For example, if the ``RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID`` is set, the application can override the adapter generated flow ID in the event using ``rx_queue_flags`` field in ``struct rte_event_eth_rx_adapter_queue_conf`` which is passed as a parameter to the ``rte_event_eth_rx_adapter_queue_add()``
@@ -191,7 +191,7 @@ Configuring the Service Function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the adapter uses a service function, the application is required to assign -a service core to the service function as show below. +a service core to the service function as shown below. .. code-block:: c
@@ -216,7 +216,7 @@ service function if one exists. Getting Adapter Statistics ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``rte_event_eth_rx_adapter_stats_get()`` function reports counters defined +The ``rte_event_eth_rx_adapter_stats_get()`` function reports counters defined in struct ``rte_event_eth_rx_adapter_stats``. The received packet and enqueued event counts are a sum of the counts from the eventdev PMD callbacks if the callback is supported, and the counts maintained by the service function,
@@ -248,7 +248,7 @@ adapter queue counters defined in struct ``rte_event_eth_rx_adapter_queue_stats` This function reports queue level stats only when queue level event buffer is used otherwise it returns -EINVAL. -The ``rte_event_eth_rx_adapter_queue_stats_reset`` function can be used to +The ``rte_event_eth_rx_adapter_queue_stats_reset()`` function can be used to reset queue level stats when queue level event buffer is in use. Getting Adapter Instance ID
@@ -294,7 +294,7 @@ monitor the buffer fill level and instruct the service function to selectively enqueue packets to the event device. The application may also use some other criteria to decide which packets should enter the event device even when the event buffer fill level is low. The -``rte_event_eth_rx_adapter_cb_register()`` function allow the application +``rte_event_eth_rx_adapter_cb_register()`` function allows the application to register a callback that selects which packets to enqueue to the event device.
@@ -330,14 +330,14 @@ A loop processing ``rte_event_vector`` containing mbufs is shown below. switch (ev.event_type) { case RTE_EVENT_TYPE_ETH_RX_ADAPTER_VECTOR: case RTE_EVENT_TYPE_ETHDEV_VECTOR: - struct rte_mbufs **mbufs; + struct rte_mbuf **mbufs; - mbufs = (struct rte_mbufs **)ev[i].vec->mbufs; + mbufs = (struct rte_mbuf **)ev[i].vec->mbufs; for (i = 0; i < ev.vec->nb_elem; i++) { /* Process each mbuf. */ } break; - case default: + default: /* Handle other event_types. */ }
doc/guides/prog_guide/eventdev/event_ethernet_tx_adapter.rst +2 -2
@@ -137,7 +137,7 @@ Enqueuing Packets to the Adapter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The application needs to notify the adapter about the transmit port and queue used -to send the packet. The transmit port is set in the ``struct rte mbuf::port`` field +to send the packet. The transmit port is set in the ``struct rte_mbuf::port`` field and the transmit queue is set using the ``rte_event_eth_tx_adapter_txq_set()`` function.
@@ -196,7 +196,7 @@ The event device, ethernet device pairs which support the capability ``RTE_EVENT_ETH_TX_ADAPTER_CAP_EVENT_VECTOR`` can process event vector of mbufs. Additionally, application can provide a hint to the Tx adapter that all the mbufs are destined to the same ethernet port and queue by setting the bit -``rte_event_vector::attr_valid`` and filling `rte_event_vector::port`` and +``rte_event_vector::attr_valid`` and filling ``rte_event_vector::port`` and ``rte_event_vector::queue``. If ``rte_event_vector::attr_valid`` is not set then the Tx adapter should peek into each mbuf and transmit them to the requested ethernet port and queue pair.
doc/guides/prog_guide/eventdev/eventdev.rst +11 -11
@@ -24,7 +24,7 @@ and event driven programming models for packet processing, and applications are free to choose whatever model (or combination of the two) best suits their needs. -Step-by-step instructions of the eventdev design is available in the `API +Step-by-step instructions of the eventdev design are available in the `API Walk-through`_ section later in this document. Event struct
@@ -33,7 +33,7 @@ Event struct The eventdev API represents each event with a generic struct, which contains a payload and metadata required for scheduling by an eventdev. The ``rte_event`` struct is a 16 byte C structure, defined in -``libs/librte_eventdev/rte_eventdev.h``. +``lib/eventdev/rte_eventdev.h``. Event Metadata ~~~~~~~~~~~~~~
@@ -67,8 +67,8 @@ the actual event being scheduled is. The payload is a union of the following: These four items in a union occupy the same 64 bits at the end of the rte_event structure. The application can utilize the 64 bits directly by accessing the -u64 variable, while the event_ptr, mbuf, vec are provided as a convenience -variables. For example the mbuf pointer in the union can used to schedule a +u64 variable, while the event_ptr, mbuf, vec are provided as convenience +variables. For example, the mbuf pointer in the union can be used to schedule a DPDK packet. Event Vector
@@ -320,8 +320,8 @@ can be achieved like this: Linking Queues to Ports with link profiles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -An application can use link profiles if supported by the underlying event device to setup up -multiple link profile per port and change them run time depending up on heuristic data. +An application can use link profiles if supported by the underlying event device to set up +multiple link profiles per port and change them at runtime depending on heuristic data. Using Link profiles can reduce the overhead of linking/unlinking and wait for unlinks in progress in fast-path and gives applications the ability to switch between preset profiles on the fly.
@@ -397,11 +397,11 @@ it will be treated as a no-op. // Disable pre-scheduling if thread is about to be scheduled out // and issue dequeue() to drain pending events. -Application may provide a hint to the eventdev PMD +Application may provide a hint to the eventdev PMD to pre-schedule the next event without releasing the current flow context. Event device that support this feature advertises the capability via the ``RTE_EVENT_DEV_CAP_PRESCHEDULE_EXPLICIT`` flag. -If pre-scheduling is already enabled at a event device or event port level +If pre-scheduling is already enabled at an event device or event port level or if the capability is not supported then the hint is ignored. .. code-block:: c
@@ -412,8 +412,8 @@ Starting the EventDev ~~~~~~~~~~~~~~~~~~~~~ A single function call tells the eventdev instance to start processing -events. Note that all queues must be linked to for the instance to start, as -if any queue is not linked to, enqueuing to that queue will cause the +events. Note that all queues must be linked to at least one port for the instance to start, as +if any queue is not linked, enqueuing to that queue will cause the application to backpressure and eventually stall due to no space in the eventdev.
@@ -572,5 +572,5 @@ The eventdev library allows an application to easily schedule events as it requires, either using a run-to-completion or pipeline processing model. The queues and ports abstract the logical functionality of an eventdev, providing the application with a generic method to schedule events. With the flexible -PMD infrastructure applications benefit of improvements in existing eventdevs +PMD infrastructure applications benefit from improvements in existing eventdevs and additions of new ones without modification.
Signature · 1 line
2.51.0
Jerin Jacob
AppliedQuoted 24 lines · Stephen Hemminger
Use AI review to find and address various documentation issues in the eventdev programmer's guide:
Grammar
- Fix subject-verb agreement in multiple places
- Fix article usage ("a" vs "an" before consonant/vowel sounds)
- Fix relative pronoun usage ("which" vs "that")
- Replace nonstandard verb "invocated" with "invoked"Spelling
- Fix "setup up" to "set up"
- Fix "as show below" to "as shown below" (multiple files)
- Fix "rte mbuf" to "rte_mbuf"
- Fix "rte_mbufs" to "rte_mbuf"
- Fix missing backtick in RST markupStyle
- Capitalize "api" to "API"
- Replace informal "For e.g," with "For example,"
- Remove extra whitespace
- Fix "benefit of" to "benefit from"
- Clarify awkward phrasing
Quoted 7 lines
Code example
- Fix invalid switch syntax "case default:" to "default:"Path corrections
- Update outdated library path from libs/librte_eventdev to lib/eventdevSigned-off-by Stephen Hemminger <[email protected]>
Applied to dpdk-next-eventdev/for-main. Thanks