-----Original Message-----
> Date: Wed, 18 Oct 2017 15:28:10 +0530
> From: Nikhil Rao <nikhil....@intel.com>
> To: jerin.ja...@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....@intel.com>
CC: John McNamara <john.mcnam...@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.ja...@caviumnetworks.com>
