Re: [PATCH v4 1/6] eventdev: introduce event driven programming model

["Eads, Gage" <gage.eads@intel.com>]

>  -----Original Message-----
>  From: Eads, Gage
>  Sent: Wednesday, January 25, 2017 10:54 AM
>  To: Richardson, Bruce <bruce.richardson@intel.com>; Jerin Jacob
>  <jerin.jacob@caviumnetworks.com>; dev@dpdk.org
>  Cc: thomas.monjalon@6wind.com; hemant.agrawal@nxp.com; Van Haaren,
>  Harry <harry.van.haaren@intel.com>; McDaniel, Timothy
>  <timothy.mcdaniel@intel.com>
>  Subject: RE: [dpdk-dev] [PATCH v4 1/6] eventdev: introduce event driven
>  programming model
>  
>  
>  
>  >  -----Original Message-----
>  >  From: Richardson, Bruce
>  >  Sent: Wednesday, January 25, 2017 10:36 AM
>  >  To: Eads, Gage <gage.eads@intel.com>; Jerin Jacob
>  > <jerin.jacob@caviumnetworks.com>; dev@dpdk.org
>  >  Cc: thomas.monjalon@6wind.com; hemant.agrawal@nxp.com; Van Haaren,
>  > Harry <harry.van.haaren@intel.com>; McDaniel, Timothy
>  > <timothy.mcdaniel@intel.com>
>  >  Subject: RE: [dpdk-dev] [PATCH v4 1/6] eventdev: introduce event
>  > driven  programming model
>  >
>  >
>  >
>  >  > -----Original Message-----
>  >  > From: Eads, Gage
>  >  > Sent: Wednesday, January 25, 2017 4:32 PM  > To: Jerin Jacob
>  > <jerin.jacob@caviumnetworks.com>; dev@dpdk.org  > Cc:
>  > thomas.monjalon@6wind.com; Richardson, Bruce  >
>  > <bruce.richardson@intel.com>; hemant.agrawal@nxp.com; Van Haaren,  >
>  > Harry <harry.van.haaren@intel.com>; McDaniel, Timothy  >
>  > <timothy.mcdaniel@intel.com>  > Subject: RE: [dpdk-dev] [PATCH v4 1/6]
>  > eventdev: introduce event  > driven programming model  >  > Hi Jerin,
>  > >  > See the bottom of this email for a proposed tweak to the  >
>  > rte_event_enqueue_burst() return value.
>  >  >
>  >  > >  -----Original Message-----
>  >  > >  From: Jerin Jacob [mailto:jerin.jacob@caviumnetworks.com]
>  >  > >  Sent: Wednesday, December 21, 2016 3:25 AM  > >  To:
>  > dev@dpdk.org  > >  Cc: thomas.monjalon@6wind.com; Richardson, Bruce  >
>  > > <bruce.richardson@intel.com>; hemant.agrawal@nxp.com; Eads, Gage  >
>  > > <gage.eads@intel.com>; Van Haaren, Harry  > >
>  > <harry.van.haaren@intel.com>; Jerin Jacob  > >
>  > <jerin.jacob@caviumnetworks.com>  > >  Subject: [dpdk-dev] [PATCH v4
>  > 1/6] eventdev: introduce event driven  > > programming model  > >
>  > <message truncated for brevity>  > >  +/**  > >  + * Enqueue a burst
>  > of events objects or an event object supplied  > > in  > >
>  > *rte_event*  > >  + * structure on an  event device designated by its
>  > *dev_id*  > > through the event  + * port specified by *port_id*. Each
>  > event  > > object specifies the event queue on  + * which it will be
>  > enqueued.
>  >  > >  + *
>  >  > >  + * The *nb_events* parameter is the number of event objects to
>  > > > enqueue  which are  + * supplied in the *ev* array of *rte_event*
>  > > > structure.
>  >  > >  + *
>  >  > >  + * The rte_event_enqueue_burst() function returns the number of
>  > +  > > * events objects it actually enqueued. A return value equal to
>  > > > *nb_events*  + * means that all event objects have been enqueued.
>  >  > >  + *
>  >  > >  + * @param dev_id
>  >  > >  + *   The identifier of the device.
>  >  > >  + * @param port_id
>  >  > >  + *   The identifier of the event port.
>  >  > >  + * @param ev
>  >  > >  + *   Points to an array of *nb_events* objects of type *rte_event*
>  >  > structure
>  >  > >  + *   which contain the event object enqueue operations to be
>  >  > processed.
>  >  > >  + * @param nb_events
>  >  > >  + *   The number of event objects to enqueue, typically number of
>  >  > >  + *   rte_event_port_enqueue_depth() available for this port.
>  >  > >  + *
>  >  > >  + * @return
>  >  > >  + *   The number of event objects actually enqueued on the event
>  >  > device. The
>  >  > >  + *   return value can be less than the value of the *nb_events*
>  >  > parameter
>  >  > >  when
>  >  > >  + *   the event devices queue is full or if invalid parameters are
>  >  > specified in a
>  >  > >  + *   *rte_event*. If return value is less than *nb_events*, the
>  >  > remaining events
>  >  > >  + *   at the end of ev[] are not consumed,and the caller has to take
>  >  > care of
>  >  > >  them
>  >  > >  + *
>  >  > >  + * @see rte_event_port_enqueue_depth()  + */  +uint16_t  > >
>  > +rte_event_enqueue_burst(uint8_t dev_id, uint8_t port_id,
>  >  > >  +			const struct rte_event ev[], uint16_t nb_events);
>  >  >
>  >  > There are a number of reasons this operation could fail to enqueue
>  > all  > the events, including:
>  >  > - Backpressure
>  >  > - Invalid port ID
>  >  > - Invalid queue ID
>  >  > - Invalid sched type when a queue is configured for ATOMIC_ONLY,  >
>  > ORDERED_ONLY, or PARALLEL_ONLY  > - ...
>  >  >
>  >  > The current API doesn't provide a straightforward way to determine
>  > the  > cause of a failure. This is a particular issue on event PMDs
>  > that can  > backpressure, where the app may want to treat that case
>  > differently  > than the other failure cases.
>  >  >
>  >  > Could we change the return type to int16_t, and define a set of
>  > error  > cases (e.g. -ENOSPC for backpressure, -EINVAL for an invalid
>  argument)?
>  >  > (With corresponding changes needed in the PMD API) Similarly we
>  > could  > change rte_event_dequeue_burst() to return an int16_t, with
>  > -EINVAL as  > a possible error case.
>  >
>  >  Use rte_errno instead, I suggest. That's what it's there for.
>  >
>  >  /Bruce
>  
>  That makes sense. In that case, the API comment could be tweaked like so:
>  
>    * If the return value is less than *nb_events*, the remaining events at the
>    * end of ev[] are not consumed and the caller has to take care of them, and
>    * rte_errno is set accordingly. Possible errno values include:
>    * - EINVAL - The port ID is invalid, an event's queue ID is invalid, or an
>    *            event's sched type doesn't match the capabilities of the
>    *            destination queue.
>    * - ENOSPC - The event port was backpressured and unable to enqueue one or
>    *            more events.

However it seems better to use a signed integer for the dequeue burst return value, if it is to use rte_errno. Application code could be simplified:

(signed return value)
ret = rte_event_dequeue_burst(...);
if (ret < 0)
    rte_panic("Dequeued returned errno %d\n", rte_errno);

vs.

(unsigned return value)
ret = rte_event_dequeue_burst(...);
if (ret == 0 && rte_errno != 0)
    rte_panic("Dequeued returned errno %d\n", rte_errno);

And with an unsigned return value, all dequeue implementations would have to clear rte_errno when no events are dequeued.

Thanks,
Gage