[dpdk-dev] [PATCH] doc: add event eth Rx adapter programmer's guide

[dpdk-dev] [PATCH] doc: add event eth Rx adapter programmer's guide

[Nikhil Rao]

Add programmer's guide doc to explain the use of the
Event Ethernet Rx Adapter library.

Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
---
 .../prog_guide/event_ethernet_rx_adapter.rst       | 160 +++++++++++++++++++++
 doc/guides/prog_guide/index.rst                    |   1 +
 2 files changed, 161 insertions(+)
 create mode 100644 doc/guides/prog_guide/event_ethernet_rx_adapter.rst

diff --git a/doc/guides/prog_guide/event_ethernet_rx_adapter.rst b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst
new file mode 100644
index 0000000..1bd4ac7
--- /dev/null
+++ b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst
@@ -0,0 +1,160 @@
+..  BSD LICENSE
+    Copyright(c) 2017 Intel Corporation. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Event Ethernet Rx Adapter Library
+=================================
+
+The DPDK Eventdev API allows the application to use an event driven programming
+model for packet processing. In this model, the application polls an event device
+port for receiving events that reference packets instead of polling Rx queues of
+ethdev ports. Packet transfer between ethdev and the event device can be
+supported in hardware or require a software thread to receive packets from the
+ethdev port using ethdev poll mode APIs and enqueue these as events to the event
+device using the eventdev API. Both transfer mechanisms may be present on the same
+platform depending on the particular combination of the ethdev and the event device.
+
+The Event Ethernet Rx Adapter library is intended for the application code to configure
+both transfer mechanisms using a common API.
+
+API Walk-through
+----------------
+
+This section will introduce the reader to the adapter API. The
+application has to first instantiate an adapter which is associated with
+a single eventdev, next the adapter instance is configured with Rx queues
+that are either polled by a SW thread or linked using hardware support. Finally
+the adapter is started.
+
+For SW based packet transfers from ethdev to eventdev, the the adapter uses a
+DPDK service function and the application is also required to assign a core to the
+service function.
+
+Creating an Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An adapter instance is created using rte_event_eth_rx_adapter_create(). This
+function is passed the event device to be associated with the adapter and port
+configuration for the adapter to setup an event port if the adapter needs to use
+a service function.
+
+.. code-block:: c
+
+	int err;
+	uint8_t dev_id;
+	struct rte_event_dev_info dev_info;
+	struct rte_event_port_conf rx_p_conf;
+
+	err = rte_event_dev_info_get(id, &dev_info);
+
+	rx_p_conf.new_event_threshold = dev_info.max_num_events;
+	rx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
+	rx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
+	err = rte_event_eth_rx_adapter_create(id, dev_id, &rx_p_conf);
+
+If the application desires to have finer control of eventdev port allocation and
+setup, it can use the rte_event_eth_rx_adapter_create_ext() function. The
+rte_event_eth_rx_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_eth_rx_adapter_conf structure passed to it.
+
+Querying Adapter Capabilties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 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 a passed as a parameter to the rte_event_eth_rx_adapter_queue_add() function.
+
+Adding Rx Queues to the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ethdev Rx queues are added to the instance using the
+rte_event_eth_rx_adapter_queue_add() function. Configuration for the Rx queue is
+passed in using a struct rte_event_eth_rx_adapter_queue_conf parameter. Event
+information for packets from this Rx queue is encoded in the ''ev'' field of
+struct rte_event_eth_rx_adapter_queue_conf. The servicing_weight member of
+the struct  rte_event_eth_rx_adapter_queue_conf is the relative polling
+frequency of the Rx queue and is applicable when the adapter uses a service
+core function.
+
+.. code-block:: c
+
+	err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap);
+
+	ev.queue_id = 0;
+	ev.sched_type = RTE_SCHED_TYPE_ATOMIC;
+	ev.priority = 0;
+
+	queue_config.rx_queue_flags = 0;
+	if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) {
+		ev.flow_id = 1;
+		queue_config.rx_queue_flags =
+			RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID;
+	}
+	queue_config.ev = ev;
+	queue_config.servicing_weight = 1;
+
+	err = rte_event_eth_rx_adapter_queue_add(id,
+						eth_dev_id,
+						0, &queue_config);
+
+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.
+
+.. code-block:: c
+
+	uint32_t service_id;
+
+	if (rte_event_eth_rx_adapter_service_id_get(0, &service_id) == 0)
+		rte_service_map_lcore_set(service_id, RX_CORE_ID);
+
+
+Starting the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The application calls rte_event_eth_rx_adapter_start() to start the adapter.
+This function calls the start callbacks of the eventdev PMDs for hardware based
+eventdev-ethdev connections and rte_service_run_state_set() to enable the
+service function if one exists.
+
+Getting Adapter Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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, if one exists. The
+service function also maintains a count of cycles for which it was not able to
+enqueue to the event device.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index b5ad6b8..95fd727 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -63,6 +63,7 @@ Programmer's Guide
     kernel_nic_interface
     thread_safety_dpdk_functions
     eventdev
+    event_ethernet_rx_adapter
     qos_framework
     power_man
     packet_classif_access_ctrl
-- 
2.7.4

[dpdk-dev] [PATCH v2] doc: add event eth Rx adapter programmer's guide

[Nikhil Rao]

Add programmer's guide doc to explain the use of the
Event Ethernet Rx Adapter library.

Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
---
v2: Update MAINTAINERS

 MAINTAINERS                                        |   2 +-
 .../prog_guide/event_ethernet_rx_adapter.rst       | 160 +++++++++++++++++++++
 doc/guides/prog_guide/index.rst                    |   1 +
 3 files changed, 162 insertions(+), 1 deletion(-)
 create mode 100644 doc/guides/prog_guide/event_ethernet_rx_adapter.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 2a58378..7b0eee7 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -274,7 +274,7 @@ M: Nikhil Rao <nikhil.rao@intel.com>
 T: git://dpdk.org/next/dpdk-next-eventdev
 F: lib/librte_eventdev/*eth_rx_adapter*
 F: test/test/test_event_eth_rx_adapter.c
-
+F: doc/guides/prog_guide/event_ethernet_rx_adapter.rst
 
 Networking Drivers
 ------------------
diff --git a/doc/guides/prog_guide/event_ethernet_rx_adapter.rst b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst
new file mode 100644
index 0000000..1bd4ac7
--- /dev/null
+++ b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst
@@ -0,0 +1,160 @@
+..  BSD LICENSE
+    Copyright(c) 2017 Intel Corporation. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Event Ethernet Rx Adapter Library
+=================================
+
+The DPDK Eventdev API allows the application to use an event driven programming
+model for packet processing. In this model, the application polls an event device
+port for receiving events that reference packets instead of polling Rx queues of
+ethdev ports. Packet transfer between ethdev and the event device can be
+supported in hardware or require a software thread to receive packets from the
+ethdev port using ethdev poll mode APIs and enqueue these as events to the event
+device using the eventdev API. Both transfer mechanisms may be present on the same
+platform depending on the particular combination of the ethdev and the event device.
+
+The Event Ethernet Rx Adapter library is intended for the application code to configure
+both transfer mechanisms using a common API.
+
+API Walk-through
+----------------
+
+This section will introduce the reader to the adapter API. The
+application has to first instantiate an adapter which is associated with
+a single eventdev, next the adapter instance is configured with Rx queues
+that are either polled by a SW thread or linked using hardware support. Finally
+the adapter is started.
+
+For SW based packet transfers from ethdev to eventdev, the the adapter uses a
+DPDK service function and the application is also required to assign a core to the
+service function.
+
+Creating an Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An adapter instance is created using rte_event_eth_rx_adapter_create(). This
+function is passed the event device to be associated with the adapter and port
+configuration for the adapter to setup an event port if the adapter needs to use
+a service function.
+
+.. code-block:: c
+
+	int err;
+	uint8_t dev_id;
+	struct rte_event_dev_info dev_info;
+	struct rte_event_port_conf rx_p_conf;
+
+	err = rte_event_dev_info_get(id, &dev_info);
+
+	rx_p_conf.new_event_threshold = dev_info.max_num_events;
+	rx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
+	rx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
+	err = rte_event_eth_rx_adapter_create(id, dev_id, &rx_p_conf);
+
+If the application desires to have finer control of eventdev port allocation and
+setup, it can use the rte_event_eth_rx_adapter_create_ext() function. The
+rte_event_eth_rx_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_eth_rx_adapter_conf structure passed to it.
+
+Querying Adapter Capabilties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 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 a passed as a parameter to the rte_event_eth_rx_adapter_queue_add() function.
+
+Adding Rx Queues to the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ethdev Rx queues are added to the instance using the
+rte_event_eth_rx_adapter_queue_add() function. Configuration for the Rx queue is
+passed in using a struct rte_event_eth_rx_adapter_queue_conf parameter. Event
+information for packets from this Rx queue is encoded in the ''ev'' field of
+struct rte_event_eth_rx_adapter_queue_conf. The servicing_weight member of
+the struct  rte_event_eth_rx_adapter_queue_conf is the relative polling
+frequency of the Rx queue and is applicable when the adapter uses a service
+core function.
+
+.. code-block:: c
+
+	err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap);
+
+	ev.queue_id = 0;
+	ev.sched_type = RTE_SCHED_TYPE_ATOMIC;
+	ev.priority = 0;
+
+	queue_config.rx_queue_flags = 0;
+	if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) {
+		ev.flow_id = 1;
+		queue_config.rx_queue_flags =
+			RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID;
+	}
+	queue_config.ev = ev;
+	queue_config.servicing_weight = 1;
+
+	err = rte_event_eth_rx_adapter_queue_add(id,
+						eth_dev_id,
+						0, &queue_config);
+
+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.
+
+.. code-block:: c
+
+	uint32_t service_id;
+
+	if (rte_event_eth_rx_adapter_service_id_get(0, &service_id) == 0)
+		rte_service_map_lcore_set(service_id, RX_CORE_ID);
+
+
+Starting the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The application calls rte_event_eth_rx_adapter_start() to start the adapter.
+This function calls the start callbacks of the eventdev PMDs for hardware based
+eventdev-ethdev connections and rte_service_run_state_set() to enable the
+service function if one exists.
+
+Getting Adapter Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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, if one exists. The
+service function also maintains a count of cycles for which it was not able to
+enqueue to the event device.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index b5ad6b8..95fd727 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -63,6 +63,7 @@ Programmer's Guide
     kernel_nic_interface
     thread_safety_dpdk_functions
     eventdev
+    event_ethernet_rx_adapter
     qos_framework
     power_man
     packet_classif_access_ctrl
-- 
2.7.4

Re: [dpdk-dev] [PATCH v2] doc: add event eth Rx adapter programmer's guide

[Jerin Jacob]

-----Original Message-----
> Date: Wed, 18 Oct 2017 15:28:10 +0530
> From: Nikhil Rao <nikhil.rao@intel.com>
> To: jerin.jacob@caviumnetworks.com
> CC: dev@dpdk.org
> Subject: [PATCH v2] doc: add event eth Rx adapter programmer's guide
> X-Mailer: git-send-email 2.7.4
> 
> Add programmer's guide doc to explain the use of the
> Event Ethernet Rx Adapter library.
> 
> Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>

CC: John McNamara <john.mcnamara@intel.com>

> ---
> v2: Update MAINTAINERS
> 
> +
> +Event Ethernet Rx Adapter Library
> +=================================
> +
> +The DPDK Eventdev API allows the application to use an event driven programming
> +model for packet processing. In this model, the application polls an event device
> +port for receiving events that reference packets instead of polling Rx queues of
> +ethdev ports. Packet transfer between ethdev and the event device can be
> +supported in hardware or require a software thread to receive packets from the
> +ethdev port using ethdev poll mode APIs and enqueue these as events to the event
> +device using the eventdev API. Both transfer mechanisms may be present on the same
> +platform depending on the particular combination of the ethdev and the event device.
> +
> +The Event Ethernet Rx Adapter library is intended for the application code to configure
> +both transfer mechanisms using a common API.

through event device capabilities(or something similar text)

> +
> +API Walk-through
> +----------------
> +
> +This section will introduce the reader to the adapter API. The
> +application has to first instantiate an adapter which is associated with
> +a single eventdev, next the adapter instance is configured with Rx queues
> +that are either polled by a SW thread or linked using hardware support. Finally
> +the adapter is started.
> +
> +For SW based packet transfers from ethdev to eventdev, the the adapter uses a
> +DPDK service function and the application is also required to assign a core to the
> +service function.
> +
> +Creating an Adapter Instance
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +An adapter instance is created using rte_event_eth_rx_adapter_create(). This
> +function is passed the event device to be associated with the adapter and port
> +configuration for the adapter to setup an event port if the adapter needs to use
> +a service function.
> +
> +.. code-block:: c
> +
> +	int err;
> +	uint8_t dev_id;
> +	struct rte_event_dev_info dev_info;
> +	struct rte_event_port_conf rx_p_conf;
> +
> +	err = rte_event_dev_info_get(id, &dev_info);
> +
> +	rx_p_conf.new_event_threshold = dev_info.max_num_events;
> +	rx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
> +	rx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
> +	err = rte_event_eth_rx_adapter_create(id, dev_id, &rx_p_conf);
> +
> +If the application desires to have finer control of eventdev port allocation and
> +setup, it can use the rte_event_eth_rx_adapter_create_ext() function. The
> +rte_event_eth_rx_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_eth_rx_adapter_conf structure passed to it.
> +
> +Querying Adapter Capabilties
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~

s/Capabilties/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 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 a passed as a parameter to the rte_event_eth_rx_adapter_queue_add() function.
> +
> +Adding Rx Queues to the Adapter Instance
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Ethdev Rx queues are added to the instance using the
> +rte_event_eth_rx_adapter_queue_add() function. Configuration for the Rx queue is
> +passed in using a struct rte_event_eth_rx_adapter_queue_conf parameter. Event
> +information for packets from this Rx queue is encoded in the ''ev'' field of
> +struct rte_event_eth_rx_adapter_queue_conf. The servicing_weight member of
> +the struct  rte_event_eth_rx_adapter_queue_conf is the relative polling
> +frequency of the Rx queue and is applicable when the adapter uses a service
> +core function.
> +
> +.. code-block:: c
> +
> +	err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap);
> +
> +	ev.queue_id = 0;
> +	ev.sched_type = RTE_SCHED_TYPE_ATOMIC;
> +	ev.priority = 0;
> +
> +	queue_config.rx_queue_flags = 0;
> +	if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) {
> +		ev.flow_id = 1;
> +		queue_config.rx_queue_flags =
> +			RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID;
> +	}

IMO, In default configuration, we may not need to add "if (cap &
RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID)". I guess we can add
separate code section to describe the use of
RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID or in general the use of
capabilities in application.


> +	queue_config.ev = ev;
> +	queue_config.servicing_weight = 1;
> +
> +	err = rte_event_eth_rx_adapter_queue_add(id,
> +						eth_dev_id,
> +						0, &queue_config);
> +

With above changes:
Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>

Re: [dpdk-dev] [PATCH v2] doc: add event eth Rx adapter programmer's guide

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Nikhil Rao
> Sent: Wednesday, October 18, 2017 10:58 AM
> To: jerin.jacob@caviumnetworks.com
> Cc: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v2] doc: add event eth Rx adapter programmer's
> guide
> 
> Add programmer's guide doc to explain the use of the Event Ethernet Rx
> Adapter library.
> 
> Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
> +
> +Event Ethernet Rx Adapter Library
> +=================================
> +
> +The DPDK Eventdev API allows the application to use an event driven
> +programming model for packet processing. In this model, the application
> +polls an event device port for receiving events that reference packets
> +instead of polling Rx queues of ethdev ports. Packet transfer between
> +ethdev and the event device can be supported in hardware or require a
> +software thread to receive packets from the ethdev port using ethdev
> +poll mode APIs and enqueue these as events to the event device using
> +the eventdev API. Both transfer mechanisms may be present on the same
> platform depending on the particular combination of the ethdev and the
> event device.

In general the text in paragraphs should be wrapped at 80 chars: 

http://dpdk.org/doc/guides/contributing/documentation.html#line-length



> +
> +For SW based packet transfers from ethdev to eventdev, the the adapter

s/the the/the/


> +.. code-block:: c
> +
> +	int err;
> +	uint8_t dev_id;
> +	struct rte_event_dev_info dev_info;
> +	struct rte_event_port_conf rx_p_conf;


Code in the docs should be indented with spaces not tabs:
http://dpdk.org/doc/guides/contributing/documentation.html#whitespace



> +
> +Querying Adapter Capabilties
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~

s/Capabilties/Capabilities/ Also adjust the underline length to match.


> +Adding Rx Queues to the Adapter Instance
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Ethdev Rx queues are added to the instance using the
> +rte_event_eth_rx_adapter_queue_add() function. Configuration for the Rx
> +queue is passed in using a struct rte_event_eth_rx_adapter_queue_conf
> +parameter. Event information for packets from this Rx queue is encoded
> +in the ''ev'' field of struct rte_event_eth_rx_adapter_queue_conf. The

Probably ''ev'' should be in backquotes: ``ev``. Also all function and
struct names in the doc should be in backquotes.

http://dpdk.org/doc/guides/contributing/documentation.html#code-and-literal-block-sections


Also, could you mark the previous version of this doc as superseded in patchwork:

http://dpdk.org/dev/patchwork/project/dpdk/list/?submitter=&state=&q=doc%3A+add+event+eth+Rx+adapter+programmer&archive=&delegate=


Thanks,

John

[dpdk-dev] [PATCH v3] doc: add event eth Rx adapter programmer's guide

[Nikhil Rao]

Add programmer's guide doc to explain the use of the
Event Ethernet Rx Adapter library.

Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
---
v3:
* Update sample code for capability query (Jerin)
* Various formatting fixes as per doc. standard (John McNamara)

v2: Update MAINTAINERS

 MAINTAINERS                                        |   2 +-
 .../prog_guide/event_ethernet_rx_adapter.rst       | 168 +++++++++++++++++++++
 doc/guides/prog_guide/index.rst                    |   1 +
 3 files changed, 170 insertions(+), 1 deletion(-)
 create mode 100644 doc/guides/prog_guide/event_ethernet_rx_adapter.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 2a58378..7b0eee7 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -274,7 +274,7 @@ M: Nikhil Rao <nikhil.rao@intel.com>
 T: git://dpdk.org/next/dpdk-next-eventdev
 F: lib/librte_eventdev/*eth_rx_adapter*
 F: test/test/test_event_eth_rx_adapter.c
-
+F: doc/guides/prog_guide/event_ethernet_rx_adapter.rst
 
 Networking Drivers
 ------------------
diff --git a/doc/guides/prog_guide/event_ethernet_rx_adapter.rst b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst
new file mode 100644
index 0000000..4e72221
--- /dev/null
+++ b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst
@@ -0,0 +1,168 @@
+..  BSD LICENSE
+    Copyright(c) 2017 Intel Corporation. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Event Ethernet Rx Adapter Library
+=================================
+
+The DPDK Eventdev API allows the application to use an event driven programming
+model for packet processing. In this model, the application polls an event
+device port for receiving events that reference packets instead of polling Rx
+queues of ethdev ports. Packet transfer between ethdev and the event device can
+be supported in hardware or require a software thread to receive packets from
+the ethdev port using ethdev poll mode APIs and enqueue these as events to the
+event device using the eventdev API. Both transfer mechanisms may be present on
+the same platform depending on the particular combination of the ethdev and
+the event device.
+
+The Event Ethernet Rx Adapter library is intended for the application code to
+configure both transfer mechanisms using a common API. A capability API allows
+the eventdev PMD to advertise features supported for a given ethdev and allows
+the application to perform configuration as per supported features.
+
+API Walk-through
+----------------
+
+This section will introduce the reader to the adapter API. The
+application has to first instantiate an adapter which is associated with
+a single eventdev, next the adapter instance is configured with Rx queues
+that are either polled by a SW thread or linked using hardware support. Finally
+the adapter is started.
+
+For SW based packet transfers from ethdev to eventdev, the adapter uses a
+DPDK service function and the application is also required to assign a core to
+the service function.
+
+Creating an Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An adapter instance is created using ``rte_event_eth_rx_adapter_create()``. This
+function is passed the event device to be associated with the adapter and port
+configuration for the adapter to setup an event port if the adapter needs to use
+a service function.
+
+.. code-block:: c
+
+        int err;
+        uint8_t dev_id;
+        struct rte_event_dev_info dev_info;
+        struct rte_event_port_conf rx_p_conf;
+
+        err = rte_event_dev_info_get(id, &dev_info);
+
+        rx_p_conf.new_event_threshold = dev_info.max_num_events;
+        rx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
+        rx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
+        err = rte_event_eth_rx_adapter_create(id, dev_id, &rx_p_conf);
+
+If the application desires to have finer control of eventdev port allocation
+and setup, it can use the ``rte_event_eth_rx_adapter_create_ext()`` function.
+The ``rte_event_eth_rx_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_eth_rx_adapter_conf structure``
+passed to it.
+
+Adding Rx Queues to the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ethdev Rx queues are added to the instance using the
+``rte_event_eth_rx_adapter_queue_add()`` function. Configuration for the Rx
+queue is passed in using a ``struct rte_event_eth_rx_adapter_queue_conf``
+parameter. Event information for packets from this Rx queue is encoded in the
+``ev`` field of ``struct rte_event_eth_rx_adapter_queue_conf``. The
+servicing_weight member of the struct  rte_event_eth_rx_adapter_queue_conf
+is the relative polling frequency of the Rx queue and is applicable when the
+adapter uses a service core function.
+
+.. code-block:: c
+
+        ev.queue_id = 0;
+        ev.sched_type = RTE_SCHED_TYPE_ATOMIC;
+        ev.priority = 0;
+
+        queue_config.rx_queue_flags = 0;
+        queue_config.ev = ev;
+        queue_config.servicing_weight = 1;
+
+        err = rte_event_eth_rx_adapter_queue_add(id,
+                                                eth_dev_id,
+                                                0, &queue_config);
+
+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``
+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()``
+function.
+
+.. code-block:: c
+
+        err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap);
+
+        queue_config.rx_queue_flags = 0;
+        if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) {
+                ev.flow_id = 1;
+                queue_config.rx_queue_flags =
+                        RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID;
+        }
+
+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.
+
+.. code-block:: c
+
+        uint32_t service_id;
+
+        if (rte_event_eth_rx_adapter_service_id_get(0, &service_id) == 0)
+                rte_service_map_lcore_set(service_id, RX_CORE_ID);
+
+Starting the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The application calls ``rte_event_eth_rx_adapter_start()`` to start the adapter.
+This function calls the start callbacks of the eventdev PMDs for hardware based
+eventdev-ethdev connections and ``rte_service_run_state_set()`` to enable the
+service function if one exists.
+
+Getting Adapter Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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,
+if one exists. The service function also maintains a count of cycles for which
+it was not able to enqueue to the event device.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index b5ad6b8..95fd727 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -63,6 +63,7 @@ Programmer's Guide
     kernel_nic_interface
     thread_safety_dpdk_functions
     eventdev
+    event_ethernet_rx_adapter
     qos_framework
     power_man
     packet_classif_access_ctrl
-- 
2.7.4

Re: [dpdk-dev] [PATCH v3] doc: add event eth Rx adapter programmer's guide

[Thomas Monjalon]

24/10/2017 11:13, Nikhil Rao:
> Add programmer's guide doc to explain the use of the
> Event Ethernet Rx Adapter library.
> 
> Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
> Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>

Applied, thanks