[dpdk-dev] [PATCH v2 1/6] eventdev: introduce event driven programming model

[Bruce Richardson]

On Tue, Dec 06, 2016 at 09:22:15AM +0530, Jerin Jacob wrote:
> In a polling model, lcores poll ethdev ports and associated
> rx queues directly to look for packet. In an event driven model,
> by contrast, lcores call the scheduler that selects packets for
> them based on programmer-specified criteria. Eventdev library
> adds support for event driven programming model, which offer
> applications automatic multicore scaling, dynamic load balancing,
> pipelining, packet ingress order maintenance and
> synchronization services to simplify application packet processing.
> 
> By introducing event driven programming model, DPDK can support
> both polling and event driven programming models for packet processing,
> and applications are free to choose whatever model
> (or combination of the two) that best suits their needs.
> 
> This patch adds the eventdev specification header file.
> 
> Signed-off-by: Jerin Jacob <jerin.jacob at caviumnetworks.com>
> ---
>  MAINTAINERS                        |    3 +
>  doc/api/doxy-api-index.md          |    1 +
>  doc/api/doxy-api.conf              |    1 +
>  lib/librte_eventdev/rte_eventdev.h | 1274 ++++++++++++++++++++++++++++++++++++
>  4 files changed, 1279 insertions(+)
<snip>
> +
> +/** Structure to hold the queue to port link establishment attributes */
> +struct rte_event_queue_link {
> +	uint8_t queue_id;
> +	/**< Event queue identifier to select the source queue to link */
> +	uint8_t priority;
> +	/**< The priority of the event queue for this event port.
> +	 * The priority defines the event port's servicing priority for
> +	 * event queue, which may be ignored by an implementation.
> +	 * The requested priority should in the range of
> +	 * [RTE_EVENT_DEV_PRIORITY_HIGHEST, RTE_EVENT_DEV_PRIORITY_LOWEST].
> +	 * The implementation shall normalize the requested priority to
> +	 * implementation supported priority value.
> +	 */
> +};
> +
> +/**
> + * Link multiple source event queues supplied in *rte_event_queue_link*
> + * structure as *queue_id* to the destination event port designated by its
> + * *port_id* on the event device designated by its *dev_id*.
> + *
> + * The link establishment shall enable the event port *port_id* from
> + * receiving events from the specified event queue *queue_id*
> + *
> + * An event queue may link to one or more event ports.
> + * The number of links can be established from an event queue to event port is
> + * implementation defined.
> + *
> + * Event queue(s) to event port link establishment can be changed at runtime
> + * without re-configuring the device to support scaling and to reduce the
> + * latency of critical work by establishing the link with more event ports
> + * at runtime.
> + *
> + * @param dev_id
> + *   The identifier of the device.
> + *
> + * @param port_id
> + *   Event port identifier to select the destination port to link.
> + *
> + * @param link
> + *   Points to an array of *nb_links* objects of type *rte_event_queue_link*
> + *   structure which contain the event queue to event port link establishment
> + *   attributes.
> + *   NULL value is allowed, in which case this function links all the configured
> + *   event queues *nb_event_queues* which previously supplied to
> + *   rte_event_dev_configure() to the event port *port_id* with normal servicing
> + *   priority(RTE_EVENT_DEV_PRIORITY_NORMAL).
> + *
> + * @param nb_links
> + *   The number of links to establish
> + *
> + * @return
> + * The number of links actually established. The return value can be less than
> + * the value of the *nb_links* parameter when the implementation has the
> + * limitation on specific queue to port link establishment or if invalid
> + * parameters are specified in a *rte_event_queue_link*.
> + * If the return value is less than *nb_links*, the remaining links at the end
> + * of link[] are not established, and the caller has to take care of them.
> + * If return value is less than *nb_links* then implementation shall update the
> + * rte_errno accordingly, Possible rte_errno values are
> + * (-EDQUOT) Quota exceeded(Application tried to link the queue configured with
> + *  RTE_EVENT_QUEUE_CFG_FLAG_SINGLE_LINK to more than one event ports)
> + * (-EINVAL) Invalid parameter
> + *
> + */
> +int
> +rte_event_port_link(uint8_t dev_id, uint8_t port_id,
> +		    const struct rte_event_queue_link link[],
> +		    uint16_t nb_links);
> +

Hi again Jerin,

another small suggestion here. I'm not a big fan of using small
structures to pass parameters into functions, especially when not all
fields are always going to be used. Rather than use the event queue link
structure, can we just pass in two array parameters here - the list of
QIDs, and the list of priorities. In cases where the eventdev
implementation does not support link prioritization, or where the app
does not want different priority mappings , then the second
array can be null [implying NORMAL priority for the don't care case].

	int
	rte_event_port_link(uint8_t dev_id, uint8_t port_id,
		const uint8_t queues[], const uint8_t priorities[],
		uint16_t nb_queues);

This just makes mapping an array of queues easier, as we can just pass
an array of ints directly in, and it especially makes it easier to
create a single link via:

  rte_event_port_link(dev_id, port_id, &queue_id, NULL, 1);

Regards,
/Bruce