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

[Jerin Jacob <jerin.jacob@caviumnetworks.com>]

-----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>